How it works

IRIS-SOAR is split up into three main functions, alert fetching, alert processing and case processing. All three presented functions can be used independently from each other. E.g. you can use the alert collector to push alerts into the IRIS and then use your own alert processing scripts to process the alerts. Or you can use the alert collector and the alert processing but use your own case processing scripts. Or you can use all three functions together.

1. Alert Fetching

The isoar_daemon.py (which can run in the background or manually called via cron etc.) automatically calls the isoar_alert_collector.py script. This script fetches alerts from the installed integrations (currently Elastic SIEM and IBM QRadar) and pushes them into the IRIS as an alert.

To do that it first calls the integration to provide the alerts. Then the alerts will be transformed to the IRIS format and pushed into the IRIS.

2. Alert Processing

Using playbooks placed in "alert_playbooks" the IRIS will process in every interval (deemed by the daemon script) every alert that has just been pushed by the alert collector or is already there with the state 'pending'.

The playbooks are written in python and are given a python list of 'Alert' objects. The playbooks can then process one or multiple alerts using the alert's class methods like escalate, assign, comment, etc.

The example playbooks are written in a way that they can be used as a template for new playbooks. The current exampe "PB_Create_Case_for_Multiple_Host_Alerts.py" will merge an alert to an existing case regarding a host or create a new case if no case exists for the host and a threshold of alerts has been reached.

3. Case Processing

Using playbooks placed in "case_playbooks" 'isoar_case_worker.py' will process in every interval (deemed by the daemon script) every case that has just been pushed by the alert collector or is already there with the state 'pending'.

The playbooks are written in python and are given a python list of 'Case' objects. The playbooks are first 'asked' if they are able to process a specific case. If they return True the case will be processed by the playbook. If they return False the case may be processed by the next playbook and so on. Playbooks can make use of the Case class methods to add notes to cases. Also they can use the available integrations to get more context information about the case. These context information also can be added in form of events and / or IOCs to the case using the Case class methods.

The example playbooks are written in a way that they can be used as a template for new playbooks. E.g. the playbook "PB_010_Generic_Elastic_Alerts.py" will process all cases that have been created by the Elastic SIEM integration. It will add notes to the case and also add events and IOCs to the case. The events and IOCs are fetched from the Elastic SIEM integration. An equivalent example playbook for IBM QRadar is also available.