Fortinet black logo

Cuckoo v1.1.0

1.1.0
Copy Link
Copy Doc ID f32fd0d8-d782-11ed-8e6d-fa163e15d75b:557

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.1.0

Authored By: Fortinet

Certified: No

Release Notes for version 1.1.0

The following enhancements have been made to the Cuckoo connector in version 1.1.0:

  • Enhanced the authentication mechanism for accessing the Cuckoo APIs by adding "API Token" as a configuration parameter.

Installing the connector

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

You can also use the yum command as a root user to install the connector:
yum install cyops-connector-cuckoo

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.

Minimum Permissions Required

  • Not applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Cuckoo connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Server IP Specify the IP of the Cuckoo sandbox server to which you will connect and perform the automated operations and the API token configured for your account for using the Cuckoo APIs.
Port Number Specify the port number of the server on which the API of the Cuckoo sandbox is running.
API Token Specify the API token configured for your account for using the Cuckoo APIs.

Actions supported by the connector

Function Description Annotation and Category
Submit File Submits a specific file for detonation on the Cuckoo Sandbox based on the specified reference ID of the file to be analyzed. submit_file
Investigation
Submit URL Submits a specific URL for detonation on Cuckoo Sandbox based on the specified URL to be analyzed. submit_url
Investigation
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. get_report
Investigation

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 Specify the FortiSOAR™ File IRI to submit files directly from the FortiSOAR™ Attachments module to the Cuckoo sandbox server for analysis.
In the playbook, this defaults to the {{vars.file_iri}} value.

Output

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.

The output contains the following populated JSON schema:
{
"task_id": ""
}

operation: Submit URL

Input parameters

Parameter Description
URL to Detonate Specify the 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.

The output contains the following populated JSON schema:
{
"task_id": ""
}

operation: Get Report

Input parameters

Parameter Description
TaskID Specify the 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.

The output contains a non-dictionary value.

Included playbooks

The Sample - Cuckoo - 1.1.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 the connector upgrade and delete.

Previous
Next

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.1.0

Authored By: Fortinet

Certified: No

Release Notes for version 1.1.0

The following enhancements have been made to the Cuckoo connector in version 1.1.0:

Installing the connector

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

You can also use the yum command as a root user to install the connector:
yum install cyops-connector-cuckoo

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Minimum Permissions Required

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Cuckoo connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Server IP Specify the IP of the Cuckoo sandbox server to which you will connect and perform the automated operations and the API token configured for your account for using the Cuckoo APIs.
Port Number Specify the port number of the server on which the API of the Cuckoo sandbox is running.
API Token Specify the API token configured for your account for using the Cuckoo APIs.

Actions supported by the connector

Function Description Annotation and Category
Submit File Submits a specific file for detonation on the Cuckoo Sandbox based on the specified reference ID of the file to be analyzed. submit_file
Investigation
Submit URL Submits a specific URL for detonation on Cuckoo Sandbox based on the specified URL to be analyzed. submit_url
Investigation
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. get_report
Investigation

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 Specify the FortiSOAR™ File IRI to submit files directly from the FortiSOAR™ Attachments module to the Cuckoo sandbox server for analysis.
In the playbook, this defaults to the {{vars.file_iri}} value.

Output

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.

The output contains the following populated JSON schema:
{
"task_id": ""
}

operation: Submit URL

Input parameters

Parameter Description
URL to Detonate Specify the 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.

The output contains the following populated JSON schema:
{
"task_id": ""
}

operation: Get Report

Input parameters

Parameter Description
TaskID Specify the 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.

The output contains a non-dictionary value.

Included playbooks

The Sample - Cuckoo - 1.1.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 the connector upgrade and delete.

Previous
Next