Some application requires basic authentication to retrieve information.

curl --user "username:password" https://app.website.com/api...

Username and password should be pass in SGBox Playbook in the following way:

1. Encode your username/password in base64. In our case will be: dXNlcm5hbWU6cGFzc3dvcmQ=
2. Create a new Authorization header with value: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Create a playbook with a trigger node as start node

Edit the trigger to set, in the Test parameters section, the same name of the parameter of the event you want to use in the dashboard to trigger the playbook.

In the following nodes of the flow, use that parameter. In this example, we add a DNS Lookup node that uses the DestinationIP parameter coming from the trigger.

Save the playbook and go to SCM -> Dashboard -> Dashboard. In any Pattern analysis dashboard showing events with the DestinationIP parameter, you can right-click on the value and select Send this value to a playbook

Choose the previously saved playbook to get the DNS Lookup output.

Download the PB samples package for examples.

The package provides a set of sample playbooks to test and practice with PB module and the various nodes available.

API Request

Playbook Test API Request: This playbook shows how to use Generic API Request node. The first node makes a request to an API. The second reads a value from the response of the previous, to compose the URL to call.

SGBOX List

Playbook Test List JSON: This Playbook calls a test API to get a JSON response and extracts a list of usernames from that. Connect the playbook to a feed in SCM -> Actions -> Lists -> Feed to be used in LCE rules and Event Queries.

Playbook Test List CSV: This Playbook calls a test API to get a CSV response and extracts a list of usernames from that. Connect the playbook to a feed in SCM -> Actions -> Lists -> Feed to be used in LCE rules and Event Queries.

Logs

Playbook Test Log JSON: This playbook calls a test API to get some logs in JSON format. Then extracts the log lines from the JSON and stores them into SGBox, available for consultation in Historical Search. The timestamp is in a field of the JSON log line. The host is not present, so logs are associated with the host specified in the configuration form.

Playbook Test Log CSV: This playbook calls a test API to get some csv logs. Then, extract the logs line from the response and stores them into SGBox, available for consultation in Historical Search. The log line is not the entire CSV line, but only a part of it. The timestamp is at the beginning of the line and it’s extracted by the node. The host is a field of the CSV line too.

Trigger, Generate Log, Generate Event

Playbook Trigger + generate log and event: This playbook shows the use of a trigger and two actions: generate log and generate event.

• • Open the playbook
  • Edit the trigger node
  • Copy the Production URL
  • Paste the url in a browser

Add “&number=7” to the url.

The PB will generate a log and an event with the parameter Number = 7. Logs and events can be viewed in the Historical Search and in Class\/Pattern Analysis.

Run PB from LCE Rule

LCE Rule Test LCE rule for PB: once you trigger the previous playbook, generating the event, this rule will be triggered by the event. The rule has a Run Playbook action that calls the playbook [FROM LCE rule] Trigger + IF + Mail.

Playbook [FROM LCE rule] Trigger + IF + Mail:This playbook shows the use of nodes:

• trigger
• if
• mail

and how to trigger a playbook from a LCE rule. The trigger start node is the one called by the rule Test LCE Rule for PB. It takes parameters via POST from the rule. The IF node tests the Number parameter, then the mail node sends a different mail according to its value.

Run PB from Event Query

Query Test Query for PB: as for the LCE rule, once you trigger the previuos playbook, genereting the event, this query will find the event and pass it to the [FROM QUERY] Trigger + IF + Mail. playbook.

Playbook [FROM QUERY] Trigger + IF + Mail: This playbook shows the use of nodes:

• trigger
• iterate on data
• if
• mail

.Also, it shows how to trigger a playbook from an Event Query.
The trigger start node is the one called by the query Test Query for PB. It takes parameters via POST from the query. The IF node tests the Number parameter, then mail node sends a different email according to its value.
The iterate node causes the flow to be repeated for each line resulting from the query

Test Run PB Action

To test the Run PB action, both from LCE Rule and Event Queries, follow these steps:

• Activate Test LCE rule for PB rule
• Activate Test Query for PB query
• Open Trigger + generate log and event playbook
• Open its trigger node and copy the production url
• Paste the url in a browser
• Add “&number=7” to the url

You will receive two emails in a few minutes. The email address is the one set by default in Advanced Options mail section.

Any playbook can be launched as a reaction to a scheduled Event Query, when the query founds any result.

Simply add the Run playbook action to the query, then select a playbook or choose to create one from scratch.

You will be redirect to the playbook configuration page. The playbook must have a trigger node as start node. The trigger node will receive query results and display them in JSON format, to be read from any node in the playbook.

If the query can have more than one result, it’s important to know that the playbook will be launched only once, with the whole result set as input.

In this case, it could be very useful to add a Flow – Iterate on data node after the trigger node.

The Iterate node will loop on the result set, and the following nodes will be executed once per row, with the row as input.

Download the PB samples package for examples.

Sometimes the application insert some junk information that are not useful in the logs.
Here a description on how to collect the important information:

In our example there are some values like: current_link, next_link and last_log_item_generation that are excluded

Last start key: means the array where our values are stored, here an example of the scructure:

"security_events":[{event1}, {event2}, ... {eventN}]

Timestamp key: means the key that indicate the timestamp. in our example we put message.detection_time because detection_time is a key nested in message

Timestamp format: means the format of our timestamp.

Any playbook can be launched as a reaction to a LCE rule, when the rule is triggered.

Simply add the Run playbook action to the rule, then select a playbook or choose to create one from scratch.

You will be redirect to the playbook configuration page. The playbook must have a trigger node as start node. The trigger node will receive, from the LCE rule, the parameters of the event(s) that triggered the rule. Then, values can be read from any node in the playbook.

In this example, the event has only one parameter (Number). Other info are passed too, like the event timestamp, name, etc.

IMPORTANT: LCE engine runs every minute and every active rule can be triggered more than once in a minute. When this happens, the related playbook will be launched once per trigger.

Download the PB samples package for examples.

List of operators that can be used to compare the 2 values of a condition:

• Equals: returns TRUE if Value 1 = Value 2
• Greater than: returns TRUE if Value 1 > Value 2
• Greater or equal: returns TRUE if Value 1 >= Value 2
• Less than: returns TRUE if Value 1 < Value 2
• Less or equal: returns TRUE if Value 1 <= Value 2
• Contains: returns TRUE if Value 2 is contained into Value 1 as a string. E.g.: Playbooks contains book
• Starts with: returns TRUE if Value 2 is at the beginning of Value 1. E.g. Playbooks starts with Play
• Ends with: returns TRUE if Value 2 is at the end of Value 1. E.g. Playbooks ends with books
• Belongs to a set: being Value 2 a set of comma-separated values, returns TRUE if Value 1 belongs to Value 2. E.g. play belongs to books,play,playbooks
• Match with regexp: being Value 2 a regular expression, returns TRUE if Value 1 matches with Value 2. E.g. playbooks matches with .*book.$

Example – IF node reading a value from an API

Sends a different mail if the value Number read from the API is smaller or greater than 10.

For Value 1, we selected Extract from previous output and chosen the node Api Request. From the output of API Request (a JSON), we selected the key to get the value to test.
Value 2 is fixed at 10.
We use Less than as operator.

The response is TRUE because 7 <= 10. The node Mail <= 10 will be run, while Mail > 10 will be ignored.

Download the PB module – samples package for examples.

Logs nodes allows you to take an input, usually coming from a request to an API to retrieve logs, and process it to extract and store to SGBox a set of log lines.
The input always comes from a previous node in the flow. Select a node from the list to show its output.
Available nodes, to manage different input formats, are

• JSON logs
• CSV logs
• TEXT logs

JSON logs

Once the JSON output of a previous node is displayed, you can click on its keys to tell the node where to extract the logs from. Then, you have to tell the node where to extract the timestamp from, its format, the host, and other info. Follow the guide inside the node form.

See this article if you there are some problem to collect the logs see the advanced section

CSV logs

Retrieve logs from API

You can create a Playbook with one or more api requests, using Start timestamp and End timestamp parameters, followed by a Logs node.
Then, just schedule the playbook to be executed with any periodicity and, at every execution, it will call the API with updated timestamps to retrieve the last available logs and store them into SGBox, available for consultation in the Historical Search page.

Nodes allows you to extract, from an input, a list of values to be stored into SGBox, when the playbook is associated with a feed.
The input always comes from a previous node in the flow. Select a node from the list to show its output.
Available nodes, to manage different input formats, are

• List from JSON
• List from CSV
• List from TEXT

List from JSON

Once the JSON output of a previous node is displayed, you can click on its keys to tell the node where to extract the list from. Follow the guide inside the node form.

List from CSV