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:
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:
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:
Following image displays a sample of the score and categories of the submitted files or URLs:
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.
