Alert with external web service

[ 1 Description ] [ 2 Flow configuration ] [ 3 Result ]

Description

A flow that, on-demand, activates an alert through an email after checking if a file (in the SHA-256 form) is infected by a virus. This is done via an external web service (VirusTotal) that scans the file through several antiviruses. By clicking the first unit, we generate an event with the SHA-256, which will be complemented with additional information to get a complete analysis.

Flow configuration

The following table describes the units needed to create this flow, as well as how to configure and link them.

Unit type and description	Configuration

Unit type and description

Configuration

Tick

When clicking on this unit, you will generate an event that contains a field called sha_256, which includes the encryption of a sample file.

Drag a Tick unit to the canvas and open its configuration options by double-clicking it.

In the General tab, simply add a name to the unit (in this example, we called it tckCheckSHA256).

Now go to the Fields tab. Click the + icon to add 3 different columns to the events sent:

sha_256 - The encrypted value of the file to be sent. Add sha_256 as the Name of the column, choose String as Type and enter the SHA-256 encrypted file in the Value field. In this example, we will add the following:
52d3df0ed60c46f336c131bf2ca454f73bafdc4b04dfa2aea80746f5ba9e6d1c
file_name - Name of the encrypted file. Add file_name as the Name of the column, choose String as Type and enter textfile.exe in the Value field.
computer - Name of the computer from which we are sending the file. Add computer as the Name of the column, choose String as Type and enter the name in the Value field (in this case, 2009-EMEA-006).

Click Apply to save the configuration.

HttpCall

This unit will receive the SHA-256 input file and return the outcome of all the antivirus which scanned the file, by performing a request to the VirusTotal API.

Drag a HttpCall unit to the canvas and link the output port of the Tick unit to the input port of this unit.

Then, open the configuration options of the unit by double-clicking it and enter the following values:

Name - httpVirusTotal
Host - www.virustotal.com
Path - /vtapi/v2/file/report

Leave the rest of the fields with their default values.

Then, scroll down to the bottom of the window to add the required Parameters to the API request by clicking the + icon. We need to add 3 parameters with the following values:

Parameter 1

We must add the apikey parameter to authorize our API request.

Name - apikey
Value - Enter your API key. You must join the VirusTotal Community to get your API key. Learn more here.

Parameter 2

The resource parameter is needed to indicate the resources to be analyzed.

From field - Choose the sha_256 field of the events fired by the Tick unit.
Name - resource

Parameter 3

We will also add the optional allinfo parameter, which will return additional information about the file analyzed.

Name - allinfo
Value - true

Click Apply to save the configuration.

JsonParser

This unit will parse the response string generated by the VirusTotal API and transform it into a JSON object.

Drag a JsonParser unit to the canvas and link the output port out of the HttpCall unit to the input port of this unit.

Then, open the configuration options of the unit by double-clicking it and enter the following values:

Name - JSONparser
In field - Choose the response field generated by the HttpCall unit.
Out field - Type the name of the JSON field which will be created. In this example, we will call it json_response.

Click Apply to save the configuration.

Map

Using this unit, we will add two additional columns to the output result to indicate the total amount of virus detected and their types.

Drag a Map unit to the canvas and link the output port out of the JsonParser unit to the input port of this unit.

Then, open the configuration options of the unit by double-clicking it. In the General tab, simply add a name to the unit (in this example, we called it VirusTotal_Count).

Now go to the Fields to add tab. Click the + icon in the fields section to add 2 new columns to the events sent:

Column 1

We will add a column to list the different types of viruses found in the file.

Field name - virustotal_result
Type - List
Expression - This is the expression that defines the new column:

def values = json_response.scans
				.collect{it}
				.findAll{it.value.detected}
values.collect{it.key +" -> "+ it.value.result}

Column 2

This column will indicate the total amount of viruses found.

Field name - virustotal_count
Type - String
Expression - This is the expression that defines the new column:

def total = json_response.total
def positives = json_response.positives
def result = positives + " / " + total
result

Click Apply to save the configuration.

EmailSink

This unit will send the complete virus analysis to an indicated email address.

Drag an EmailSink unit to the canvas and link the output port out of the Map unit to the input port of this unit.

Then, open the configuration options of the unit by double-clicking it In the General tab, add a Name to the unit (in this example, we called it toMail), the Subject of the mails that will be sent (in this example, Threat detected) and the Message to be sent. This is the message that we used in this example, referencing the information in the columns of the events received:

Threat detected: %%﹛file_name﹜%%﹛sha_256﹜(%%﹛computer﹜).

Virustotal count: %% ﹛virustotal_count﹜

VirusTotal result: %% ﹛virustotal_result﹜

Now go to the To recipients tab, click the + icon in the TOs section, and enter the email addresses you want to send the mails.

Click Apply to save the configuration.

Result

After saving and starting the Flow, you must click the red button of the Tick unit to begin sending events.

Once you have defined the whole Flow, click the Start button to activate it and click the first unit (Tick). If everything is correctly configured and a threat is detected, the addresses indicated in the EmailSink unit will receive an email including the analysis of the SHA-256 file, with the information we defined and added to the events generated.

Import this Flow

Download the above Flow and import it to your domain clicking the Import from JSON option in the File menu.

Add your API key and mail addresses before trying it out

As explained in the Flow configuration section, you must include your own VirusTotal API key in the configuration of the HttpCall unit and the required email addresses in the EmailSink unit to make this flow work.