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.

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

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)

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.

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.

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.
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.
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.
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

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
