What is an Expression Builder?
In this article we are going to look at using the Expression Builder (introduced in Software Version 5.0) in Playbooks.
The Expression Builder allows the parsing and manipulating of JSON results and further utilizing them in subsequent actions in a simple and intuitive manner. The Expression Builder generates a variety of dynamic transformation functions that can be chained together and previewed and tested, thereby allowing for an interactive experience for the transformation and parsing of raw action results.
What does the Expression Builder screen look like?
A typical Expression Builder screen looks like this:
It contains the following information:
This is an example of potential data and is not based on real time results. The actual data may be different and may contain more or less fields from the example. If the analyst knows of extra fields that will be returned in run time then they can type the relevant key path in the syntax textbox.
The following functions are supported:
- First (x) – Return first X elements of an array
- Last (x) – Return last X elements of an array
- Min (KeyPath) – return an element of an array by the minimum
- Max (KeyPath) – return an element of an array by the maximum
- Filter (ConditionKey, Operator, Value) – Filter objects by field
- DateFormat (“pattern”) – format date by given pattern (‘yyyy/dd/mm HH:mm:ss’) to supported format (“YYYY-MM-DDThh:mm:ssZ”)
- Count () – return the number of elements in expression
- OrderBy (KeyPath, “Direction”) – order array by given child field
- toLower () – convert expression to lower case letters
- toUpper () – convert expression to upper case letters
- Replace (“x”, “y”) – replace string in an expression
- Distinct () – remove duplicates from an array
The Expression field is where you insert the JSON results together with the functions and pipes to add several functions together and build the expression. We will explore examples of building expressions later on in this article.
>Run / Results:
After filling in the Expression Builder, clicking Run will display the Results based on the JSON Sample Data shown above in the Expression Builder
Using the Expression Builder in Playbook Actions
Let’s look at three use cases building an Expression in an Action.
Use Case Number One: IPS
Let’s say we are building a Playbook which has found a malicious flow in a Network.
Imagine that a vulnerable management tool such as Qualys has scheduled scanning every day. In this example, we are using Qualys – List Scans to get all the latest scans from Qualys (30 days hard coded)
We will be using the expression builder to extract the ID (REF) of the newest scan as placeholder for download VM scan results. VM scan results will download the relevant report.
Using the List Operations, we are going to extract the list of the vulnerabilities’ identifiers which was found on the network (CVE) from the report and compare it to the CVE from the case
We can use an IPS alert to trigger the Playbook. Start off with an Active Directory_Enrich Entities action so that we can enrich all the entities that are potentially affected. and then use Qualys VM – List Scans to retrieve the latest scan results for the network machines and determine if any of them are vulnerable to the detected flow.
Now let’s take a look at the next action QualysVM_Download VM Scan Results_1. This screenshot shows the Placeholder together with the Expression Builder that has been added.
To add this placeholder:
- Click the Placeholder icon .
- Select Playbook > QualysVM_list_Scans_1_JSONResult.
- Click on the Expression Builder icon as shown below.
The Expression Builder screen opens up.
- Add the following in the Expression field. The expressions means that we use MAX to take the latest result by date (LAUNCH_DATETIME) and then extract the specific scan id of the relevant scan where REF means scan id.
bc. | max(LAUNCH_DATETIME) | REF
- Click Run. The expected results will appear.
- Click Insert to include the Expression Builder as part of the Placeholder.
- Next action should be as follows: Action > List operations using CVEs from the cases + expression builder displays – see following screenshots.
- Once the Playbook is triggered in real time, you can see the scan results in the Context Details pane, including the specific scan as pdf.
Use Case Number Two: Too Many Failed Login Attempts
For this use case let’s say that we had failed login attempts and we want to figure out which department the user belongs to and when was the last time he changed his password in order to determine the severity of the alert. In this Playbook we are going to use Active Directory to get more information.
In the first action, we will use ActiveDirectory_Enrich entities to find out more information on all the internal entities. In this Insight message, we want to find out the user and the last time they logged in. Below is a screenshot of this action already with the necessary Placeholders with the Expression Builders in.
To add these placeholders:
- In the Message field, click the Placeholder icon .
- In the Insert Placeholder screen, click the Expression Builder icon next to the ActiveDirectory_Enrich entities_JSONResult
- Add the following in the expression field: This will choose the entity identifier. Currently, if more than one entity returned results – we will get it as comma separated list.
bc. | Entity
- Click Run and you will see the sample result. In this case, email@example.com.
- Click Insert to use this as part of your placeholder message. Add the relevant free text to your message as well.
- Once again, click the Placeholder icon  and then click the Expression Builder icon next to the ActiveDirectory_Enrich entities_JSONResult.
- Add the following expression. This will capture the last logon time of the specified user.
- Click Insert and then click Save.
- Once the Playbook is triggered in real time, you will see a message on the Insight pane with the user name and last login time.
Use Case Number Three: Virus Total
The action checks the reputation of the file hash on VirusTotal. In this example, we are getting a report for a specific file hash. We are then extracting the reputation (i.e. is it known to be malicious) by a specific scan engine. In this case, Kaspersky.
So we are going to check if Kaspersky marked the file hash as malicious and create an entity for that.
In the first action, we will use VirusTotal_Scan Hash.
Now, let’s take a look at the next action. Siemplify_Create Or Update Entity Properties. This creates or changes properties for an entity. Detected by Kaspersky.
Below is a screenshot of this action already with the necessary Placeholders with the Expression Builders in.
To add this placeholder:
- In the Field Value field, click the Placeholder icon .
- In the Insert Placeholder screen, click the Expression Builder icon next to the VirusTotal_ScanHash_JSONResult.
- Add the following expression: | filter(EntityResult.scans.Kaspersky.detected, “=”, “true”) | Entity
If we scanned more than one hash, it filters the results by all the entity objects that Kaspersky marked as malicious – and then returns just the entity name.
- Click Insert and then click Save.
- Results will display at run time as follows.
Need more help with this?
Click here to open a Support ticket