Playbooks detailed use case

Playbooks are a powerful feature that allow us to create custom workflows for real events. In this exercise, we’ll use a third-party intelligence source – VirusTotal – to help us decide whether a suspect file detection likely poses a threat. Based on the findings, we’ll adjust the verdict if necessary, and send a notification. If you are not familiar with the interface of Playbooks you can find an introduction here.
Note: The section at the end covers how to debug your Playbook. This feature provides a very useful view of your Playbook’s behavior and can assist in identifying and correcting any issues with the workflow or syntax.

How to get started

This playbook will be specific to a workspace, so from top right of the workspace’s playbooks page, click on New Playbook. Since this will check a detection with VirusTotal, let’s name it VirusTotal Lookup, use the default Threat type of File, and select Create to start.

Our playbook now has its first element, and we need a trigger to start the workflow, so click on WS VirusTotal Lookup to open the inspector tab and edit its properties. With the properties panel showing, you may want to drag the WS VirusTotal Lookup element rectangle to the right if it’s partially obscured. To define the trigger that will initiate the playbook, select + Add condition group.

Set the trigger’s condition to Severity, change the test to Greater Or Equal, and set the trigger’s value to Suspicious. Be sure to select Save when done.

Threat Intelligence Source

Note: In order to proceed, you’ll need a VirusTotal account: you can sign up at www.virustotal.com. With an account, you have access to the VirusTotal API which we’ll use to do our lookup (you can read more about the VT API here).

Next, we’ll configure how we’ll use VirusTotal to assist with our evaluation of the potential threat. From the list of available elements, click and drag Threat intelligence source to below our WS VirusTotal Lookup element

Select your new Threat intelligence source element and enter a new name, such as VirusTotal Lookup.

Construct the API call

The method we’ll use is the default GET, and we’ll pass VirusTotal the hash of the file we’re investigating as specified in their API docs. Specifically, the call that we’ll be constructing, as shown in the VirusTotal API documentation, is:

To start, we enter the Source url as:
https://virustotal.com/api/v3/files/{{Incident: Sha1}} 

Note that when entering the URL above, once the first brackets “{{“ have been entered, a dialog appears allowing us to select the variable that we wish to use, in this case: Incident: SHA-1:

Set the Auth type to HTTP header, enter x-apikey as the Auth header, and for the header value, use the API Key from your VirusTotal account:

The final part of our query specifies the desired format for the response. We’ll use JSON, so under Headers, select + Add header, and enter the header name accept and the header value application/json.

Format the response

In the Data mapping section, from the response to our query we define two variables that we’ll use for our playbook workflow:

1. To filter results for antivirus vendors (engine_name) having the file flagged as malicious, we define the variable vt_engines, and create a list using Add to array (String) with values pulled from JsonPath with the Query:

$.data.attributes.last_analysis_results..[?(@.category == ‘malicious’)].engine_name

2. We define vt_id with the JsonPath Query $.data.id: this will be used to determine whether VirusTotal has a record of this file hash.

The data mapping described above is entered as follows:

Select Save to complete the VirusTotal lookup element and click back on the main area of the workflow. We now join the playbook VirusTotal Lookup (start) element to the VirusTotal Query (Threat intelligence source) element by clicking on the VirusTotal Lookup and click-and-drag the right arrow to the VirusTotal Query element. You may need to drag both elements to the right in order to gain the necessary space to be able to accomplish this step.

Click on the right arrow to join to the next element and start the workflow.

The playbook elements have been joined to form a workflow.

Condition tests

With the response from VirusTotal, we can determine whether to treat the file as malicious using a couple of Condition elements.
The conditions that we can test for, based on the formatted response we gathered, are:

1. Whether VirusTotal has a record of this file. We’ve tested for this by creating a local variable (vt_id) that’s mapped to the VirusTotal $.data.id, and if it exists then VirusTotal has seen this file before.
2. Which vendors (vt_engines) have the file flagged as malicious. This can be useful to determine the risk associated with files flagged by only a few vendors, as we can choose which vendors’ opinions we value the most. Note that a high number here is a good indicator of a malicious file, while a low number suggests but does not guarantee that a file is not malicious. Of course, Emsisoft has already detected the file.

The first test is created by dragging the Condition element below our VirusTotal Lookup, and we determine whether VirusTotal has a record of the file by testing if vt.id>0 

Our next condition will test which vendors (vt_engines) have the file flagged as malicious.

For example: The list vendors flagging the file as malicious includes our top 3 (non-Emsisoft) trusted vendors ie vt_engines contains (vendorA AND vendorB AND vendorC)

Let’s create a second condition below the first, again by dragging the Condition element below the first condition, and we test against specific vendors, we enter 3 tests as shown below, where values chosen for vendorA/vendorB/vendorC are from the VirusTotal vendor table.  Keep in mind that the list is subject to changes as new antivirus solutions are added and existing ones change names, so playbooks with references to vendors may require future updates.

Incident update

If either of the conditions we created are false, then we’ll update the incident to be a false positive to reflect this. Drag a new Incident update element below and to the left of the lowest condition test, name it False Positive, select + Add field, and Assign a Verdict of False positive.

Create a second Incident update element below and to the right of the lowest condition test, name it Confirmed Malicious, and + Add field as described above, this time with a Verdict of Confirmed Malicious.

Notification

Finally, we’ll create an email notification regarding the malicious detection. Drag the Notification element to the right of the previous Incident update element, specify an email notification and give it a name like “VT Positive Detection”. Give the email a subject and recipient(s).

For the email body, we can use variables to make some of the content. To start with, try the following, noting that the last line needs to be exactly as it is shown for the variable to be properly referenced. Here you have an example:

Playbook VirusTotal Lookup has confirmed that the following detection:

File: {{Alerts: FileName}}
Sha1: {{Incident: Sha1}}

Affected devices include:
{{Incident: InvolvedDevices}}

User accounts:
{{Incident: InvolvedDeviceUsers}}

Multiple virus engines returned positives.
VirusTotal returned response: {{vt_engines}} 

Connecting it all together

To complete the workflow, click on the VirusTotal Query element, and using the arrow on the right of the rectangle, connect it to the first Condition element. Repeat this process until you have the workflow below, noting that Condition elements support both TRUE and FALSE workflows:

Debugging your Playbook

Finally, test the workflow with the build-in debugger. Enter the debugger using the icon at the top right of the workflow diagram, as shown in the screenshot above, and the debugger sidebar opens at the right side of the window. You may want to increase the width of your window to provide adequate space.

Select a test incident, ie a previous detection from this workspace. If none exists, you may want to download an EICAR test file and run a scan against it, however if you download anything caution is urged!

Once you have an incident selected, click Run debug to see the result of your workflow. Note that you can Expand what is shown, and view Context or Log pages to see the details of the outcome. The button changes to Stop debug while the workflow executes and reverts back to Run debug when completed. The outcome of debugging this workflow is shown below, where you can see the custom variables we created (vt_engines and vt_id).

Execution

Playbooks are executed in the order that they appear on your playbooks page, with only the first playbook that matches the execution criteria being run. You can click and drag your playbooks to reorder them according to your priorities. Once you’re happy with the execution of the playbook, don’t forget to turn on Autorun!