Fortinet Document Library

Version:


Table of Contents

Cisco Threat Grid

1.1.0
Copy Link

About the connector

A Cisco AMP Threat Grid Appliance provides a safe and highly secure on-premises advanced malware analysis and threat intelligence technology. ThreatGrid empowers organizations operating under various compliance and policy restrictions, to submit malware samples to the appliance. By maintaining a Cisco AMP Threat Grid Appliance on-premises, organizations are able to send suspicious documents and files to it to be analyzed without leaving the network, thereby protecting the organization.

This document provides information about the Cisco AMP Threat Grid Connector, which facilitates automated interactions, with a ThreatGrid server using FortiSOAR™ playbooks. Add the Cisco AMP Threat Grid Connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting a sample to ThreatGrid, retrieving reports for a submitted file, and getting daily feeds from ThreatGrid.\

 

Version information

Connector SDK Version: 1.1.0

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with ThreatGrid Versions: 3.4.44 and later

 

Release Notes for version 1.1.0

Following enhancements have been made to the Threat Grid Connector in version 1.1.0:

  • Masked the text entered in the API Key field on the Configuration page.
  • Added a link to the online help.
  • Updated operation names and enhanced their input parameters.
  • Update connector name to Cisco AMP Threat Grid.
  • Updated playbook names and added new playbooks.
  • Added output_schema for all operations.
  • Enhanced the input parameter named VM for the Submit Sample operation by changing the field type from a text box to a drop-down list. The VM drop-down list now lists all the all the available VM making it easier for you to select the appropriate VM.
    Similarly, for the Get daily feeds operation the Available Name Feeds input parameter has been changed from a textbox to a drop-down list, which lists all the available feed names.

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL and credentials of the ThreatGrid server on which you will perform the automated operations.
  • You must have the API key for the ThreatGrid server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
  • You must have the FortiSOAR™ Built-in connector cyops_utilities version 2.0.1 installed on your system. For more information on FortiSOAR™ built-in connectors, see FortiSOAR™ documentation.

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Cisco AMP Threat Grid connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL for the ThreatGrid server from where the connector gets notifications.
API Key API key to access the ThreatGrid server.
Verify SSL Specifies whether an SSL certificate will be required for the connection between the Cisco AMP Threat Grid Connector and ThreatGrid server.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Submit Sample Submits a sample file to the ThreatGrid server for analysis. detonate_file
Investigation
Search Report Searches for reports on the ThreatGrid server based on the input text you have specified. get_analysis
Investigation
Get IOCs Retrieves details of IOCs associated with the submitted sample from the ThreatGrid server. IOC (Indicators of Compromise) enables you to identify a known threat, an attacker's methodology, or any other evidence of compromise. get_iocs
Investigation
Get HTML Report Retrieves an HTML report for a submitted sample from the ThreatGrid server. The HTML file is stored in the Attachments module in FortiSOAR™. get_reputation
Investigation
Get Status Retrieves the state of a submitted sample from the ThreatGrid server. There are a number of states that a sample can be in once it is submitted to ThreatGrid. The states are: pending, running, succ, proc, fail, prep, wait, and run.  
Get All Reports Retrieves organization reports of samples submitted from the ThreatGrid server, based on the date you have specified as the input. get_file
Investigation
Get JSON Report Retrieves the detailed static and dynamic reports of the submitted sample from the ThreatGrid server. get_analysis
Investigation
Search Report by feeds Searches for reports from the ThreatGrid server based on the feed you have specified.
Feeds are retrieved daily from ThreatGrid and used by organizations and partners for targeted threat intelligence, by focusing on the specific types of threats faced by particular industries.
get_report
Investigation
Get Summary Retrieves the threat summary of a submitted sample from the ThreatGrid server. get_report
Investigation

 

operation: Submit Sample

Input parameters

 

Parameter Description
Filename Name of the file that you want to submit to ThreatGrid for analysis.
File IRI FortiSOAR™ File IRI of the file that you want to submit to ThreatGrid for analysis.
Note: The file that you want to submit to ThreatGrid for analysis must be part of the Attachment module in FortiSOAR™.
VM (Optional) Sandbox VM on which ThreatGrid will analyze the submitted sample.
Available VMs are available: Windows 10 (beta), Windows 7 64-bit, Windows 7 64-bit (Japanese), Windows 7 64-bit (Korean), Windows 7 64bit Profile 2. There is an additional option Other, in case any new VM is supported by ThreatGrid in the future.
Other VM Name (Optional) If you want to analyze the sample on any VM, other than the supported VMs.
Private Sample (Optional) Specify whether the sample should be kept private, based on a Boolean value.

 

Output

The JSON output that contains the details of the file submitted to the ThreatGrid server.

Following image displays a sample output:

 

Sample output of the Submit Sample operation

 

operation: Search Report

Input parameters

 

Parameter Description
Text Text such as SHA 256, MD5, or ID of the sample based on which you want to search for reports on the ThreatGrid server.

 

Output

The JSON output that contains the details of the reports retrieved from the ThreatGrid server, based on the input text you have specified.

Following image displays a sample output:

 

Sample output of the Search Report operation

 

operation: Get IOCs

Input parameters

 

Parameter Description
sampleID ID of the sample for which you want to retrieve associated IOCs from the ThreatGrid server.

 

Output

The JSON output that contains the details of the IOCs associated with the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get IOCs operation

 

operation: Get HTML Report

Input parameters

 

Parameter Description
sampleID ID of the sample for which you want to retrieve the report from the ThreatGrid server.

 

Output

The output is an HTML file that contains the report for the sample that is retrieved from the ThreatGrid server, based on the sample ID you have specified. The HTML file is stored in the Attachments module in FortiSOAR™.

Following image displays a sample HTML output:

 

Sample output of the Get HTML Report operation

 

When you add this function as a step in a playbook or if you run the Submit Sample sample playbook, which contains get_report as a step, then the output of the function contains the URL of the report and the name of the attachment as shown as a sample output in the following sample image:

 

Sample output of the get report step in the Submit sample to threatgrid playbook

 

operation: Get Status

Input parameters

 

Parameter Description
sampleID ID of the sample for whose status you want to retrieve from the ThreatGrid server.

 

Output

The JSON output that contains the status of the sample retrieved from the ThreadGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get Status operation

 

operation: Get All Reports

Input parameters

 

Parameter Description
Before Specify the datetime in the (ISO 8601) format, for example, 2017-07-31 11:58:54, before which date, the data of all samples that have been submitted by users belonging to a particular organization, are retrieved date-wise. Default timezone is UTC.
After Specify the date in the (ISO 8601) format, for example, 2017-07-31 11:58:54, after which date, the data of all samples that have been submitted by users belonging to a particular organization, are retrieved date-wise. Default timezone is UTC.

 

Output

The JSON output contains the data of all samples, date-wise, that have been submitted by users belonging to a particular organization retrieved from the ThreatGrid server, based on the date range you have specified.

Following image displays a sample output:

 

Sample output of the Get All Reports operation

 

operation: Get JSON Report

Input parameters:

 

Parameter Description
sampleID ID of the sample whose analysis you want to retrieve from the ThreatGrid server.

 

Output:

The JSON output contains the detailed analysis of the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get JSON Report operation

 

operation: Search Report by Feeds

Input parameters

 

Parameter Description
Feed Name Name of feed, in ThreatGrid, from which you want to retrieve data daily.
The feed names available are: autorun-registry, banking-dns, dll-hijacking-dns, doc-net-com-dns, downloaded-pe-dns, dynamic-dns, irc-dns, modified-hosts-dns, parked-dns, public-ip-check-dns, ransomware-dns, rat-dns, scheduled-tasks, sinkholed-ip-dns, and stolen-cert-dns.

 

Output

The JSON output contains the daily feed retrieved from the ThreatGrid server, based on the feed name you have specified.

Following image displays a sample output:

 

Sample output of the Search Report by Feeds operation

 

operation: Get Summary

Input parameters

 

Parameter Description
sampleID ID of the sample whose summary you want to retrieve from the ThreatGrid server.

 

Output

The JSON output contains the summary of the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get Summary operation

 

Included playbooks

The Sample - Cisco AMP Threat Grid - 1.1.0 playbook collection comes bundled with the Cisco AMP Threat Grid Connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cisco AMP Threat Grid Connector.

  • Get All Reports
  • Get HTML Report
  • Get IOCs
  • Get JSON Report
  • Get Status
  • Get Summary
  • Search Report
  • Search Report by Feeds
  • Submit Sample

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.

 

About the connector

A Cisco AMP Threat Grid Appliance provides a safe and highly secure on-premises advanced malware analysis and threat intelligence technology. ThreatGrid empowers organizations operating under various compliance and policy restrictions, to submit malware samples to the appliance. By maintaining a Cisco AMP Threat Grid Appliance on-premises, organizations are able to send suspicious documents and files to it to be analyzed without leaving the network, thereby protecting the organization.

This document provides information about the Cisco AMP Threat Grid Connector, which facilitates automated interactions, with a ThreatGrid server using FortiSOAR™ playbooks. Add the Cisco AMP Threat Grid Connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting a sample to ThreatGrid, retrieving reports for a submitted file, and getting daily feeds from ThreatGrid.\

 

Version information

Connector SDK Version: 1.1.0

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with ThreatGrid Versions: 3.4.44 and later

 

Release Notes for version 1.1.0

Following enhancements have been made to the Threat Grid Connector in version 1.1.0:

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Cisco AMP Threat Grid connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL for the ThreatGrid server from where the connector gets notifications.
API Key API key to access the ThreatGrid server.
Verify SSL Specifies whether an SSL certificate will be required for the connection between the Cisco AMP Threat Grid Connector and ThreatGrid server.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Submit Sample Submits a sample file to the ThreatGrid server for analysis. detonate_file
Investigation
Search Report Searches for reports on the ThreatGrid server based on the input text you have specified. get_analysis
Investigation
Get IOCs Retrieves details of IOCs associated with the submitted sample from the ThreatGrid server. IOC (Indicators of Compromise) enables you to identify a known threat, an attacker's methodology, or any other evidence of compromise. get_iocs
Investigation
Get HTML Report Retrieves an HTML report for a submitted sample from the ThreatGrid server. The HTML file is stored in the Attachments module in FortiSOAR™. get_reputation
Investigation
Get Status Retrieves the state of a submitted sample from the ThreatGrid server. There are a number of states that a sample can be in once it is submitted to ThreatGrid. The states are: pending, running, succ, proc, fail, prep, wait, and run.  
Get All Reports Retrieves organization reports of samples submitted from the ThreatGrid server, based on the date you have specified as the input. get_file
Investigation
Get JSON Report Retrieves the detailed static and dynamic reports of the submitted sample from the ThreatGrid server. get_analysis
Investigation
Search Report by feeds Searches for reports from the ThreatGrid server based on the feed you have specified.
Feeds are retrieved daily from ThreatGrid and used by organizations and partners for targeted threat intelligence, by focusing on the specific types of threats faced by particular industries.
get_report
Investigation
Get Summary Retrieves the threat summary of a submitted sample from the ThreatGrid server. get_report
Investigation

 

operation: Submit Sample

Input parameters

 

Parameter Description
Filename Name of the file that you want to submit to ThreatGrid for analysis.
File IRI FortiSOAR™ File IRI of the file that you want to submit to ThreatGrid for analysis.
Note: The file that you want to submit to ThreatGrid for analysis must be part of the Attachment module in FortiSOAR™.
VM (Optional) Sandbox VM on which ThreatGrid will analyze the submitted sample.
Available VMs are available: Windows 10 (beta), Windows 7 64-bit, Windows 7 64-bit (Japanese), Windows 7 64-bit (Korean), Windows 7 64bit Profile 2. There is an additional option Other, in case any new VM is supported by ThreatGrid in the future.
Other VM Name (Optional) If you want to analyze the sample on any VM, other than the supported VMs.
Private Sample (Optional) Specify whether the sample should be kept private, based on a Boolean value.

 

Output

The JSON output that contains the details of the file submitted to the ThreatGrid server.

Following image displays a sample output:

 

Sample output of the Submit Sample operation

 

operation: Search Report

Input parameters

 

Parameter Description
Text Text such as SHA 256, MD5, or ID of the sample based on which you want to search for reports on the ThreatGrid server.

 

Output

The JSON output that contains the details of the reports retrieved from the ThreatGrid server, based on the input text you have specified.

Following image displays a sample output:

 

Sample output of the Search Report operation

 

operation: Get IOCs

Input parameters

 

Parameter Description
sampleID ID of the sample for which you want to retrieve associated IOCs from the ThreatGrid server.

 

Output

The JSON output that contains the details of the IOCs associated with the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get IOCs operation

 

operation: Get HTML Report

Input parameters

 

Parameter Description
sampleID ID of the sample for which you want to retrieve the report from the ThreatGrid server.

 

Output

The output is an HTML file that contains the report for the sample that is retrieved from the ThreatGrid server, based on the sample ID you have specified. The HTML file is stored in the Attachments module in FortiSOAR™.

Following image displays a sample HTML output:

 

Sample output of the Get HTML Report operation

 

When you add this function as a step in a playbook or if you run the Submit Sample sample playbook, which contains get_report as a step, then the output of the function contains the URL of the report and the name of the attachment as shown as a sample output in the following sample image:

 

Sample output of the get report step in the Submit sample to threatgrid playbook

 

operation: Get Status

Input parameters

 

Parameter Description
sampleID ID of the sample for whose status you want to retrieve from the ThreatGrid server.

 

Output

The JSON output that contains the status of the sample retrieved from the ThreadGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get Status operation

 

operation: Get All Reports

Input parameters

 

Parameter Description
Before Specify the datetime in the (ISO 8601) format, for example, 2017-07-31 11:58:54, before which date, the data of all samples that have been submitted by users belonging to a particular organization, are retrieved date-wise. Default timezone is UTC.
After Specify the date in the (ISO 8601) format, for example, 2017-07-31 11:58:54, after which date, the data of all samples that have been submitted by users belonging to a particular organization, are retrieved date-wise. Default timezone is UTC.

 

Output

The JSON output contains the data of all samples, date-wise, that have been submitted by users belonging to a particular organization retrieved from the ThreatGrid server, based on the date range you have specified.

Following image displays a sample output:

 

Sample output of the Get All Reports operation

 

operation: Get JSON Report

Input parameters:

 

Parameter Description
sampleID ID of the sample whose analysis you want to retrieve from the ThreatGrid server.

 

Output:

The JSON output contains the detailed analysis of the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get JSON Report operation

 

operation: Search Report by Feeds

Input parameters

 

Parameter Description
Feed Name Name of feed, in ThreatGrid, from which you want to retrieve data daily.
The feed names available are: autorun-registry, banking-dns, dll-hijacking-dns, doc-net-com-dns, downloaded-pe-dns, dynamic-dns, irc-dns, modified-hosts-dns, parked-dns, public-ip-check-dns, ransomware-dns, rat-dns, scheduled-tasks, sinkholed-ip-dns, and stolen-cert-dns.

 

Output

The JSON output contains the daily feed retrieved from the ThreatGrid server, based on the feed name you have specified.

Following image displays a sample output:

 

Sample output of the Search Report by Feeds operation

 

operation: Get Summary

Input parameters

 

Parameter Description
sampleID ID of the sample whose summary you want to retrieve from the ThreatGrid server.

 

Output

The JSON output contains the summary of the sample retrieved from the ThreatGrid server, based on the sample ID you have specified.

Following image displays a sample output:

 

Sample output of the Get Summary operation

 

Included playbooks

The Sample - Cisco AMP Threat Grid - 1.1.0 playbook collection comes bundled with the Cisco AMP Threat Grid Connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cisco AMP Threat Grid Connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.