Fortinet Document Library

Version:


Table of Contents

Cisco Threat Grid

1.2.0
Copy Link

About the connector

A Cisco Threat Grid Appliance provides a safe and highly secure on-premises advanced malware analysis and threat intelligence technology. Cisco Threat Grid empowers organizations operating under various compliance and policy restrictions, to submit malware samples to the appliance. By maintaining a Cisco Threat Grid Appliance on-premises, organizations can 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 Threat Grid Connector, which facilitates automated interactions, with a Cisco Threat Grid server using FortiSOAR™ playbooks. Add the Cisco Threat Grid Connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting a sample to Cisco Threat Grid, retrieving reports for a submitted file, and getting daily feeds from Cisco Threat Grid.

Version information

Connector Version: 1.2.0

FortiSOAR™ Version Tested on: 4.11.0-1161

Cisco Threat Grid Version Tested on: 3.4.44

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.2.0

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

  • Added the Get Rate Limit Information operation.
  • Renamed the Get HTML Report operation to Download Report and added new input parameters for the Download Report operation.
  • Added input parameters for the following operations:
    • Submit Sample
    • Search Report
    • Search Report by Feeds
  • Updated connector name to Cisco Threat Grid.
  • Updated playbooks and added new playbooks based on enhanced and new operations.

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-cisco-threatgrid

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the URL of the Cisco Threat Grid server on which you will perform the automated operations and the API key configured for your account to access that Cisco Threat Grid 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, click the Cisco Threat Grid connector row, and in the Configuration tab enter the required configuration details.

Parameter Description
Server URL URL for the Cisco Threat Grid server from where the connector gets notifications and to which you will connect and perform automated operations.
API Key API key that is configured for your account for the Cisco Threat Grid server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
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 Cisco Threat Grid server for analysis. detonate_file
Investigation
Search Report Searches for reports on the Cisco Threat Grid server based on the input text and parameters you have specified. get_analysis
Investigation
Get IOCs Retrieves details of IOCs associated with the submitted sample from the Cisco Threat Grid 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
Download Report Retrieves a report or analysis for a submitted sample from the Cisco Threat Grid server. The report file is stored in the Attachments module in FortiSOAR™ . get_reputation
Investigation
Get Status Retrieves the state of a submitted sample from the Cisco Threat Grid server. There are a number of states that a sample can be in once it is submitted to Cisco Threat Grid. The states are: pending, running, succ, proc, fail, prep, wait, and run. get_status
Investigation
Get All Reports Retrieves organization reports of samples submitted from the Cisco Threat Grid server, based on the input date you have specified. get_file
Investigation
Get JSON Report Retrieves the detailed static and dynamic reports of the submitted sample from the Cisco Threat Grid server. get_analysis
Investigation
Search Report by feeds Searches for reports from the Cisco Threat Grid server based on the feed you have specified.
Feeds are retrieved daily from Cisco Threat Grid 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 Cisco Threat Grid server. get_report
Investigation
Get Rate Limit Information Retrieves information for all available submissions from the Cisco Threat Grid server. get_rate_limit_info
Investigation

operation: Submit Sample

Input parameters

Parameter Description
Filename Name of the file that you want to submit to Cisco Threat Grid for analysis.
File IRI FortiSOAR™ File IRI of the file that you want to submit to Cisco Threat Grid for analysis.
Note: The file that you want to submit to Cisco Threat Grid for analysis must be part of the Attachment module in FortiSOAR™ .
Tags (CSV / List Format) (Optional) Tags that applies to the sample that you want to submit to Cisco Threat Grid for analysis.
Virtual Machine (Optional) Select the Sandbox VM on which Cisco Threat Grid will analyze the submitted sample.
The available VMs get dynamically populated from the Cisco Threat Grid server.
Playbook (Optional) Select the Name of the playbook that is to applied to this sample during the process of this operation.
The available playbooks get dynamically populated from the Cisco Threat Grid server.
Network Exit Localization (Optional) Select the Network Exit Localization for any outgoing network traffic that is generated during the analysis.
The available network exit localizations get dynamically populated from the Cisco Threat Grid server.
Private Sample (Optional) Specify whether the sample should be kept private, based on a Boolean value.
By default, this parameter is selected, i.e., the sample is kept private.

Output

The JSON output contains the details of the file submitted to the Cisco Threat Grid 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 Cisco Threat Grid server.
Filter Submissions (Optional) Option by which you want to filter submissions.
You can choose between the following options:
User Only: Submissions are filtered by the current user.
Organization Only: Submissions are filtered by the organization of the current user.
Before (Optional) Datetime from when you want to return submissions, i.e., return submissions that were created before the specified DateTime.
For example, 2017-08-01T10:58:54Z.
After (Optional) Datetime till when you want to return submissions, i.e., return submissions that were created after the specified DateTime.
For example, 2017-08-01T12:58:54Z.
State (Optional) State by which you want to filter submissions.
You can choose from the following options: Waiting, Processing, Success, or Fail.
Limit (Optional) Maximum number of records that this operation should return.
By default, this option is set as 100.

Output

The JSON output contains the details of the reports retrieved from the Cisco Threat Grid server, based on the input text and parameters you have specified.

Following image displays a sample output:

Sample output of the Search Report operation

operation: Get IOCs

Input parameters

Parameter Description
Sample ID ID of the sample for which you want to retrieve associated IOCs from the Cisco Threat Grid server.

Output

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

Following image displays a sample output:

Sample output of the Get IOCs operation

operation: Download Report

Input parameters

Parameter Description
Sample ID ID of the sample for which you want to retrieve the report from the Cisco Threat Grid server.
Download Type of report to download.
You can choose from the following options: Report HTML, Analysis JSON, Network PCAP, Runtime Video, or Processes JSON.

Output

The sample output of the Download Report operation, when you choose the report type as Report HTML is an HTML file that contains the report for the sample that is retrieved from the Cisco Threat Grid 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 Download 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 Cisco Threat Grid playbook

operation: Get Status

Input parameters

Parameter Description
Sample ID ID of the sample for whose status you want to retrieve from the Cisco Threat Grid server.

 

Output

The JSON output contains the status of the sample retrieved from the Cisco Threat Grid 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, which have been submitted by users belonging to a particular organization retrieved from the Cisco Threat Grid 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
Sample ID ID of the sample whose analysis you want to retrieve from the Cisco Threat Grid server.

Output:

The JSON output contains the detailed analysis of the sample retrieved from the Cisco Threat Grid 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 Cisco Threat Grid, 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.
Date (Optional) Date based on which you will retrieve the feed report. You must enter the date in the format YYYY-MM-DD.

Output

The JSON output contains the daily feed retrieved from the Cisco Threat Grid 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
Sample ID ID of the sample whose summary you want to retrieve from the Cisco Threat Grid server.

Output

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

Following image displays a sample output:

Sample output of the Get Summary operation

operation: Get Rate Limit Information

Input parameters

None.

Output

The JSON output contains details of all available submissions of users and their organizations, retrieved from the Cisco Threat Grid server.

Following image displays a sample output:

Sample output of the Get Rate Limit Information operation

Included playbooks

The Sample - Cisco Threat Grid - 1.2.0 playbook collection comes bundled with the Cisco 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 Threat Grid connector.

  • Download Report
  • Get All Reports
  • Get IOCs
  • Get JSON Report
  • Get Rate Limit Information
  • 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 Threat Grid Appliance provides a safe and highly secure on-premises advanced malware analysis and threat intelligence technology. Cisco Threat Grid empowers organizations operating under various compliance and policy restrictions, to submit malware samples to the appliance. By maintaining a Cisco Threat Grid Appliance on-premises, organizations can 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 Threat Grid Connector, which facilitates automated interactions, with a Cisco Threat Grid server using FortiSOAR™ playbooks. Add the Cisco Threat Grid Connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting a sample to Cisco Threat Grid, retrieving reports for a submitted file, and getting daily feeds from Cisco Threat Grid.

Version information

Connector Version: 1.2.0

FortiSOAR™ Version Tested on: 4.11.0-1161

Cisco Threat Grid Version Tested on: 3.4.44

Authored By: Fortinet.

Certified: Yes

Release Notes for version 1.2.0

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

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-cisco-threatgrid

For the detailed 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, click the Cisco Threat Grid connector row, and in the Configuration tab enter the required configuration details.

Parameter Description
Server URL URL for the Cisco Threat Grid server from where the connector gets notifications and to which you will connect and perform automated operations.
API Key API key that is configured for your account for the Cisco Threat Grid server to which you will connect and perform the automated operations.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
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 Cisco Threat Grid server for analysis. detonate_file
Investigation
Search Report Searches for reports on the Cisco Threat Grid server based on the input text and parameters you have specified. get_analysis
Investigation
Get IOCs Retrieves details of IOCs associated with the submitted sample from the Cisco Threat Grid 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
Download Report Retrieves a report or analysis for a submitted sample from the Cisco Threat Grid server. The report file is stored in the Attachments module in FortiSOAR™ . get_reputation
Investigation
Get Status Retrieves the state of a submitted sample from the Cisco Threat Grid server. There are a number of states that a sample can be in once it is submitted to Cisco Threat Grid. The states are: pending, running, succ, proc, fail, prep, wait, and run. get_status
Investigation
Get All Reports Retrieves organization reports of samples submitted from the Cisco Threat Grid server, based on the input date you have specified. get_file
Investigation
Get JSON Report Retrieves the detailed static and dynamic reports of the submitted sample from the Cisco Threat Grid server. get_analysis
Investigation
Search Report by feeds Searches for reports from the Cisco Threat Grid server based on the feed you have specified.
Feeds are retrieved daily from Cisco Threat Grid 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 Cisco Threat Grid server. get_report
Investigation
Get Rate Limit Information Retrieves information for all available submissions from the Cisco Threat Grid server. get_rate_limit_info
Investigation

operation: Submit Sample

Input parameters

Parameter Description
Filename Name of the file that you want to submit to Cisco Threat Grid for analysis.
File IRI FortiSOAR™ File IRI of the file that you want to submit to Cisco Threat Grid for analysis.
Note: The file that you want to submit to Cisco Threat Grid for analysis must be part of the Attachment module in FortiSOAR™ .
Tags (CSV / List Format) (Optional) Tags that applies to the sample that you want to submit to Cisco Threat Grid for analysis.
Virtual Machine (Optional) Select the Sandbox VM on which Cisco Threat Grid will analyze the submitted sample.
The available VMs get dynamically populated from the Cisco Threat Grid server.
Playbook (Optional) Select the Name of the playbook that is to applied to this sample during the process of this operation.
The available playbooks get dynamically populated from the Cisco Threat Grid server.
Network Exit Localization (Optional) Select the Network Exit Localization for any outgoing network traffic that is generated during the analysis.
The available network exit localizations get dynamically populated from the Cisco Threat Grid server.
Private Sample (Optional) Specify whether the sample should be kept private, based on a Boolean value.
By default, this parameter is selected, i.e., the sample is kept private.

Output

The JSON output contains the details of the file submitted to the Cisco Threat Grid 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 Cisco Threat Grid server.
Filter Submissions (Optional) Option by which you want to filter submissions.
You can choose between the following options:
User Only: Submissions are filtered by the current user.
Organization Only: Submissions are filtered by the organization of the current user.
Before (Optional) Datetime from when you want to return submissions, i.e., return submissions that were created before the specified DateTime.
For example, 2017-08-01T10:58:54Z.
After (Optional) Datetime till when you want to return submissions, i.e., return submissions that were created after the specified DateTime.
For example, 2017-08-01T12:58:54Z.
State (Optional) State by which you want to filter submissions.
You can choose from the following options: Waiting, Processing, Success, or Fail.
Limit (Optional) Maximum number of records that this operation should return.
By default, this option is set as 100.

Output

The JSON output contains the details of the reports retrieved from the Cisco Threat Grid server, based on the input text and parameters you have specified.

Following image displays a sample output:

Sample output of the Search Report operation

operation: Get IOCs

Input parameters

Parameter Description
Sample ID ID of the sample for which you want to retrieve associated IOCs from the Cisco Threat Grid server.

Output

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

Following image displays a sample output:

Sample output of the Get IOCs operation

operation: Download Report

Input parameters

Parameter Description
Sample ID ID of the sample for which you want to retrieve the report from the Cisco Threat Grid server.
Download Type of report to download.
You can choose from the following options: Report HTML, Analysis JSON, Network PCAP, Runtime Video, or Processes JSON.

Output

The sample output of the Download Report operation, when you choose the report type as Report HTML is an HTML file that contains the report for the sample that is retrieved from the Cisco Threat Grid 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 Download 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 Cisco Threat Grid playbook

operation: Get Status

Input parameters

Parameter Description
Sample ID ID of the sample for whose status you want to retrieve from the Cisco Threat Grid server.

 

Output

The JSON output contains the status of the sample retrieved from the Cisco Threat Grid 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, which have been submitted by users belonging to a particular organization retrieved from the Cisco Threat Grid 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
Sample ID ID of the sample whose analysis you want to retrieve from the Cisco Threat Grid server.

Output:

The JSON output contains the detailed analysis of the sample retrieved from the Cisco Threat Grid 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 Cisco Threat Grid, 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.
Date (Optional) Date based on which you will retrieve the feed report. You must enter the date in the format YYYY-MM-DD.

Output

The JSON output contains the daily feed retrieved from the Cisco Threat Grid 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
Sample ID ID of the sample whose summary you want to retrieve from the Cisco Threat Grid server.

Output

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

Following image displays a sample output:

Sample output of the Get Summary operation

operation: Get Rate Limit Information

Input parameters

None.

Output

The JSON output contains details of all available submissions of users and their organizations, retrieved from the Cisco Threat Grid server.

Following image displays a sample output:

Sample output of the Get Rate Limit Information operation

Included playbooks

The Sample - Cisco Threat Grid - 1.2.0 playbook collection comes bundled with the Cisco 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 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.