Automation


Playbook

The main component of Alertflex automation functionality is Playbook. The playbook is a set of separate jobs, that are executed by Alertflex according to the Flow Id of the job.

Alertflex uses an event-driven approch. Therefore mostly, automation tasks are started by security events. Every new event is analyzed by the controller if it mutch to a defined response profile. The response profile can have a link to a specific automation playbook, that will be run in case the response profile is triggered.

../_images/response-profile.png

Job

The Job is separate software module that implement specific IT security operations task. It can be created and edited from Playbooks>Workflow panel. Every Job’s Webform includes Flow ID that can be modifyed to change order of execution Playbook. It is common parametr for all Jobs.

There are two types of jobs - basic and supplementary.

Basic job performs different cybersecurity automation tasks. To basic jobs belongs:

  • ArJob (Active Response)

  • CtiJob (Cyber Threat Intelligence)

  • SandboxJob

  • ScanJob

  • ScriptJob

Supplementary jobs:

  • FileJob (Manipulation with files)

  • NotifyJob ( Send notifications to users)

  • ReportJob (Send reports to users)

It is worth mentioning separately the LogicJob. This type of job serves the logic of the playbook.

  • It can change the next flow Id of the job to skip some job

  • delay execution of the playbook

  • run a new playbook

  • set parameters (modify context playbook)

  • stop the playbook

../_images/job-logic.png

Playbook Context

The one important task of LogicJob is a modification context of Playbook.

When Alertflex is processing the playbook as a “response” to a security event, it is holding the context of this event as an object of Java Class. Definition of the class you can see via the link https://github.com/alertflex/cnode/blob/master/controller/src/main/java/org/alertflex/common/PojoAlertLogic.java

The context of the playbook is visible for different Jobs and can be used by them. Additionally, the context includes several additional fields that don’t belong to the security event and can be used to transmit variable information between Jobs, these fields are shown below:

String stringParam1 = "indef";
String stringParam2 = "indef";
String stringParam3 = "indef";
Integer integerParam = 0;
Double doubleParam = 0L;
Boolean booleanParam = false;

For modification above parameters, LogicJob executes the Groovy script that is defined in LogicJob webform and interacts with the PojoAlertLogic object. Groovy script language (https://groovy-lang.org/) was chosen because it is well integrated with Java and often used for such tasks in other automation tools such as Jenkins, JMeter, etc.

Below given several examples using LogicJob, Groovy script, and Playbook Context

Use case: LogicJob

Task: Stop execution Playbook if field userName of security event isn’t define - indef

Precondition: LogicJob should have a type - stop the playbook.

Example of Groovy script:

// check if user isn't define
def userField = pal.getUserName()
if ( userField.equals("indef") ) pal.setBooleanParam(true)
return true

Explanation: After execution Groovy script, LogicJob should check the booleanParam. If it equals true, LogicJob stops the playbook

Note: All types of LogicJob require a value of booleanParam equals true for changing the logic of playbook (except type change flow, see note for case CtiJob and ArJob below)

../_images/logicjob-playbook.png

Use case: ScriptJob

Task: Passing value of srcIp field of security event as argument to the script

Precondition: LogicJob should have a type - set parameters

Example of Groovy script:

// get value of srcIp
def ip = pal.getSrcIp()
// generate a command line for ScriptJob
pal.setStringParam1("sh test_script.sh " + ip)
// parameter was changed, set booleanParam to true
pal.setBooleanParam(true)
return true

Explanation: ScriptJob uses StringParam1 as a command line for the script if booleanParam is set to true (except the type of script Calico). In another case, ScriptJob uses the command line parameter from the webform.

Note: The command line for the script should include the full string of the command itself and arguments.

../_images/scriptjob-playbook.png

Use case: NotifyJob

Task: Create notification message

Precondition: LogicJob should have a type - set parameters

Example of Groovy script:

// generate notification message
pal.setStringParam1("Hello world!")
// parametr was changed, set booleanParam to true
pal.setBooleanParam(true)
return true

Explanation: NotifyJob uses StringParam1 as text of notification if booleanParam is set to true. In another case, NotifyJob uses notify message from webform.

../_images/notifyjob-playbook.png

Use case: CtiJob and ArJob

Task: Check by CTI service a source IP address of security event, if the score of scanning result is highly suspicious then block this IP via AWS network ACL

Precondition: LogicJob should have a type - change flow, ArJob should have a type - AwsNacl

Example of Groovy script:

def severity = pal.getIntParam()
def ipType = pal.stringParam1()
if ( severity > 2 && ipType == "srcIp" ) pal.setBooleanParam(true)
return true

Explanation: Before in examples, LogicJob was used to modify parameters of Playbook Context. The current example uses the possibility of CtiJob to modify context.

  1. By default, CtiJob performs a reputation check IP addresses or file hash for security event fields included in the Playbook context. In case of suspicious data has been found, the CtiJob module creates a new alert and modifies StringParam fields in context. The value of stringParam1 will be set to the type of suspicious field. The value of intParam will be set to the severity of the alert.

  2. The LogicJob checks that severity is high than 2 (critical) and stringParam1 equals to srcIp. If the condition is true, LogicJob transfers control to ArJob.

  3. The ArJob can initiate 5 different types of responses:

  • Creates rule for AWS Network ACL to block IP address

  • Sends commands (start, stop, etc) to remote docker

  • Executes AWS lambda function

  • Sends a command to block IP to remote Suricata IDS

  • Executes remote script on Wazuh agent

In this example, ArJob uses the stringParam1 of playbook context to determine for what IP address of security event need to create NACL rule

Note: if booleanParam is false, LogicJob miss execution ArJob by jumping to the next LogicJob block, please see the screenshot below

../_images/ctijob-arjob.png

Use case: ScanJob

Task: Continuously check GuardDuty threat detection service, if new findings exist, send a notification to the user

Precondition: LogicJob should have a type - change flow, parameter time interval of playbook should be set to a monitoring period of GuardDuty alerts

Example of Groovy script:

def numAlerts = pal.getIntParam()
if ( numAlerts > 0 ) pal.setBooleanParam(true)
return true

Explanation: Similar to CtiJob, ScanJob can modify the playbook context. Because ScanJob deals with various third-party products such as vulnerability scanners and cloud services, the playbook context is modified depending on the type ScanJob:

  • AmazonInspector: intParam - the number of new Inspector findings

  • ElasticAnomalyTask (the OpenDistro Anomaly Detection feature) : doubleParam - anomaly grade, intParam - the severity of alert

  • GuardDuty: intParam - the number of new GuardDuty alerts

  • IpInsights (AWS SageMaker IP Insight algorithm): doubleParam - IpInsights algorithm prediction, intParam - the severity of alert

Note: The playbook for this use case is not triggered by a security event, it is triggered periodically by Alertflex according to the parameter of the playbook time interval

../_images/scanjob-playbook.png