Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

About the connector

The Cuckoo Malware sandbox provides a service that analyzes suspicious file samples and URLs and gets the reputation of submitted entities.

This document provides information about the Cuckoo connector, which facilitates automated interactions, with a Cuckoo server using FortiSOAR™playbooks. Add the Cuckoo connector as a step in FortiSOAR™playbooks and perform automated operations, such as scanning and analyzing suspicious files and URLs and retrieving reports from Cuckoo for files and URLs that you have submitted to Cuckoo.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™Versions: 4.9.0.0-708 and later

Compatibility with Cuckoo Sandbox Versions: 2.0.4 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the IP of the Cuckoo sandbox to which you will connect and perform the automated operations and credentials to access that server.
  • You must open the port on which the Cuckoo API sandbox is configured to allow communication between FortiSOAR™and the Cuckoo sandbox.

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Cuckoo connector and click Configure to configure the following parameters:

 

Parameter Description
Server IP IP of the Cuckoo sandbox server to which you will connect and perform the automated operations.
Port Number Port number of the server on which the API of the Cuckoo sandbox is running.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks:

  • Submit File: Submits a file to the Cuckoo sandbox server for analysis.
  • Submit URL: Submits a URL to the Cuckoo sandbox server for analysis.
  • Get Report: Retrieves a report from the Cuckoo server for the files or URLs that you had submitted to the Cuckoo server for analysis. Reports are retrieved based on the task_id of the sample. Based on the report you can determine the reputation of the submitted files or URLs.

operation: Submit File

Input parameters

Note: Using this operation, you submit files that are available in the FortiSOAR™Attachments module to the Cuckoo sandbox server.

The Cuckoo sandbox server supports the uploading of the following file types to the Cuckoo sandbox for analysis:

  • Doc
  • Exe
  • JS
  • PDF
  • PPT
  • PS1
  • RAR
  • VBS
  • XLS
  • Zip

 

Parameter Description
File to Detonate Use the FortiSOAR™File IRI to submit files directly from the FortiSOAR™Attachments module to the Cuckoo sandbox server.
In the playbook, this defaults to the {{vars.file_iri}} value.

 

Output

A customized JSON output that is formatted for easy reference is the output for all the operations.

The JSON output contains the task_id and the status of submission for the submitted file. You can use this task_id in subsequent queries to retrieve scan reports from the Cuckoo server for the submitted file.

Following image displays a sample output:

 

Sample output of the Submit File operation

 

operation: Submit URL

Input parameters

 

Parameter Description
URL to Detonate URL that you want to submit to the Cuckoo sandbox for scanning and analyzing.

 

Output

The JSON output contains the task_id and the status of submission for the submitted URL. You can use this task_id in subsequent queries to retrieve scan reports from the Cuckoo server for the submitted URL.

Following image displays a sample output:

 

Sample output of the Submit URL operation
 

operation: Get Report

Input parameters

 

Parameter Description
TaskID TaskID for a previously submitted file or URL for which you want to retrieve an analysis report from the Cuckoo server.

 

Output

The JSON output contains the report retrieved from the Cuckoo sandbox server for the previously submitted files or URLs. You can use the report details to determine the reputation of the previously submitted files or URLs, along with other parameters such as network pcap, signatures, and targets.

Following image displays a sample output:

 

 

Sample output of the Get Report operation

 

Following image displays a sample of the score and categories of the submitted files or URLs:

 

Sample output of the Submitted files scores and categories

 

Included playbooks

The Sample - Cuckoo - 1.0.0 playbook collection comes bundled with the Cuckoo 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 Cuckoo connector.

  • Submit File to Cuckoo
  • Submit URL to Cuckoo
  • Get Report for Submitted 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

The Cuckoo Malware sandbox provides a service that analyzes suspicious file samples and URLs and gets the reputation of submitted entities.

This document provides information about the Cuckoo connector, which facilitates automated interactions, with a Cuckoo server using FortiSOAR™playbooks. Add the Cuckoo connector as a step in FortiSOAR™playbooks and perform automated operations, such as scanning and analyzing suspicious files and URLs and retrieving reports from Cuckoo for files and URLs that you have submitted to Cuckoo.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™Versions: 4.9.0.0-708 and later

Compatibility with Cuckoo Sandbox Versions: 2.0.4 and later

 

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 Cuckoo connector and click Configure to configure the following parameters:

 

Parameter Description
Server IP IP of the Cuckoo sandbox server to which you will connect and perform the automated operations.
Port Number Port number of the server on which the API of the Cuckoo sandbox is running.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks:

operation: Submit File

Input parameters

Note: Using this operation, you submit files that are available in the FortiSOAR™Attachments module to the Cuckoo sandbox server.

The Cuckoo sandbox server supports the uploading of the following file types to the Cuckoo sandbox for analysis:

 

Parameter Description
File to Detonate Use the FortiSOAR™File IRI to submit files directly from the FortiSOAR™Attachments module to the Cuckoo sandbox server.
In the playbook, this defaults to the {{vars.file_iri}} value.

 

Output

A customized JSON output that is formatted for easy reference is the output for all the operations.

The JSON output contains the task_id and the status of submission for the submitted file. You can use this task_id in subsequent queries to retrieve scan reports from the Cuckoo server for the submitted file.

Following image displays a sample output:

 

Sample output of the Submit File operation

 

operation: Submit URL

Input parameters

 

Parameter Description
URL to Detonate URL that you want to submit to the Cuckoo sandbox for scanning and analyzing.

 

Output

The JSON output contains the task_id and the status of submission for the submitted URL. You can use this task_id in subsequent queries to retrieve scan reports from the Cuckoo server for the submitted URL.

Following image displays a sample output:

 

Sample output of the Submit URL operation
 

operation: Get Report

Input parameters

 

Parameter Description
TaskID TaskID for a previously submitted file or URL for which you want to retrieve an analysis report from the Cuckoo server.

 

Output

The JSON output contains the report retrieved from the Cuckoo sandbox server for the previously submitted files or URLs. You can use the report details to determine the reputation of the previously submitted files or URLs, along with other parameters such as network pcap, signatures, and targets.

Following image displays a sample output:

 

 

Sample output of the Get Report operation

 

Following image displays a sample of the score and categories of the submitted files or URLs:

 

Sample output of the Submitted files scores and categories

 

Included playbooks

The Sample - Cuckoo - 1.0.0 playbook collection comes bundled with the Cuckoo 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 Cuckoo 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.