Fortinet Document Library

Version:


Table of Contents

Fortinet FortiSandbox

1.0.0
Copy Link

About the connector

Fortinet FortiSandbox utilizes advanced detection, dynamic antivirus scanning, and threat scanning technology to detect viruses and APTs. Fortinet FortiSandbox executes suspicious files in the VM host module to determine if the file is High, Medium, or Low Risk, based on the behaviour observed in the VM sandbox module.

This document provides information about the Fortinet FortiSandbox connector, which facilitates automated interactions, with your Fortinet FortiSandbox server using FortiSOAR™ playbooks. Add the Fortinet FortiSandbox connector, as a step in FortiSOAR™ playbooks and perform automated operations such as submitting files to Fortinet FortiSandbox from the FortiSOAR™ "Attachments" module and retrieving the status of the system and scan stats from Fortinet FortiSandbox.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.12.1-253

Authored By: Fortinet

Certified: Yes 

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-fortinet-fortisandbox

For the detailed procedure to install a connector, click here

Prerequisites to configuring the connector

  • You must have the URL of Fortinet FortiSandbox server to which you will connect and perform automated operations and credentials(username-password pair) to access that server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
  • To configure the connector, you must add the following roles to users in Fortinet Sandbox, including an account that can access the JSON API:

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Fortinet FortiSandbox connector row, and in the Configure tab enter the required configuration details. 

Parameter Description
Server URL URL of the Fortinet FortiSandbox server to which you will connect and perform automated operations.
Username Username of the Fortinet FortiSandbox server to which you will connect and perform automated operations.
Password Password used to access the Fortinet FortiSandbox 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 and onwards: 

Function Description Annotation and Category
Submit File Submits a file to Fortinet FortiSandbox from the FortiSOAR™ "Attachments" module, i.e., based on the attachment IRI you have specified. submit_file
Investigation
Submit URL Submits a URL(s) to Fortinet FortiSandbox. submit_url
Investigation
Get System Status Retrieves the status of the system from Fortinet FortiSandbox. get_system_status
Investigation
Get Scan Stats Retrieves the scan stats for the last 7 days from Fortinet FortiSandbox. get_scan_stats
Investigation
Get Submission Job List Retrieves all job IDs associated with submission ID you have specified from Fortinet FortiSandbox. get_job_list
Investigation
Get Job Verdict Detail Retrieves job verdict detail for job ID you have specified from Fortinet FortiSandbox. get_job_detail
Investigation
Get File Rating Retrieves file rating for the file type and filehash you have specified from Fortinet FortiSandbox. get_file_rating
Investigation
Get URL Rating Get rating details for the URL you have specified from Fortinet FortiSandbox. get_url_rating
Investigation
Get File Verdict Retrieves the file verdict details for the file type and filehash you have specified from Fortinet FortiSandbox. get_file_verdict
Investigation
Get Job Behaviour Retrieves job behaviour details associated with the file type and filehash you have specified from Fortinet FortiSandbox. get_job_details
Investigation
Update White or Black List Updates an existing whitelist or an existing blacklist in Fortinet FortiSandbox, based in on the input parameter such as indicator type and value, and action you have specified. update_white_black_list
Miscellaneous
Toggle FPN State Marks specified sample based on the Job ID you have specified as false negative or false positive in Fortinet FortiSandbox. toggle_fpn_state
Miscellaneous
Get AV-Rescan Result Retrieves AV-Rescan results for the time duration you have specified from Fortinet FortiSandbox. get_scan_result
Investigation
Get All Installed VM Retrieves the names and the clone numbers of all installed VMs on Fortinet FortiSandbox. get_installed_vm
Investigation
Get PDF Report Retrieves a PDF report from Fortinet FortiSandbox based on the query type and value parameter you have specified and creates an attachment in the FortiSOAR™ "Attachment" module if the report is found. get_report
Investigation
List Filehash or URL From Malware Package or URL Package Retrieves a list of file hashes or URLs based on the type you have specified from the Malware Package or URL Package in Fortinet FortiSandbox. list_filehash_url
Investigation

operation: Submit File

Input parameters

Parameter Description
Attachment IRI IRI of the attachment that you want to submit to Fortinet FortiSandbox.
Attachment IRI that is used to access the file directly from the FortiSOAR™ "Attachments" module.
VM Name (Optional) Name of the VM that will scan the specified URL file.
If you do not specify and VM Name, then the VM Name will default to the one that will be used.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "msg": "",
             "sid": "",
             "error": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Submit URL

Input parameters

Parameter Description
URL URL that you want to submit to Fortinet FortiSandbox.
Note: You can submit a single URL or multiple URLs in a list format.
VM Name (Optional) Name of the VM that will scan the specified URL.
If you do not specify and VM Name, then the VM Name will default to the one that will be used.
Timeout (Optional) Time after which the scan will timeout, i.e., the time in seconds of the length of the scan.
By default, the timeout value is set to 60 seconds.
Depth (Optional) This option specifies the depth of web links this operation should scan. Select this option, i.e., set to True, to crawl into the links of the specified URL for scanning purposes. Deselect this option, i.e., set to False, to scan only the specified URL and not any links of within the URL.

Output

The output contains the following populated JSON schema:
{
     "id": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "sid": "",
             "msg": "",
             "error": ""
         }
     },
     "ver": ""
}

operation: Get System Status

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "fdn_server_accessible": "",
             "Build": "",
             "Patch": "",
             "Platform Full Name": "",
             "Minor": "",
             "64-bit Applications": "",
             "Serial Number": "",
             "Time Zone": "",
             "Platform Type": "",
             "Branch Point": "",
             "Hostname": "",
             "Release Version Information": "",
             "wf_server_accessible": "",
             "vm_network_access": "",
             "cloud_server_accessible": "",
             "Current Time": "",
             "License Status": "",
             "Admin Domain Configuration": "",
             "Version": "",
             "FIPS Mode": "",
             "win_lic_activated": "",
             "Major": ""
         }
     },
     "id": ""
}

operation: Get Scan Stats

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "suspicious_low": "",
             "pending": "",
             "processing": "",
             "suspicious_high": "",
             "suspicious_medium": ""
         }
     },
     "id": ""
}

operation: Get Submission Job List

Input parameters

Parameter Description
Submission ID ID of the submission whose associated Job IDs you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "jids": [],
             "total_jids": ""
         }
     },
     "id": ""
}

operation: Get Job Verdict Detail

Input parameters

Parameter Description
Job ID ID of the job whose job verdict details you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "score": "",
             "false_positive_negative": "",
             "sha1": "",
             "now": "",
             "download_url": "",
             "detection_os": "",
             "finish_ts": "",
             "infected_os": "",
             "detail_url": "",
             "vid": "",
             "untrusted": "",
             "start_ts": "",
             "rating": "",
             "sha256": "",
             "category": "",
             "rating_source": "",
             "malware_name": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get File Rating

Input parameters

Parameter Description
Hash Type Type of the filehash based on which you want to retrieve the file rating from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) based on which you want to retrieve the file rating from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "score": "",
             "now": "",
             "untrusted": "",
             "start_ts": "",
             "rating": [],
             "finish_ts": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": 0
         }
     },
     "ver": "",
     "id": ""
}

operation: Get URL Rating

Input parameters

Parameter Description
URL URL for which you want to retrieve the rating details from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": [
             {
                 "behavior_info": "",
                 "url": "",
                 "now": "",
                 "untrusted": "",
                 "start_ts": "",
                 "rating": [],
                 "finish_ts": ""
             }
         ],
         "url": "",
         "status": {
             "code": "",
             "message": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get File Verdict

Input parameters

Parameter Description
Hash Type Type of the filehash based on which you want to retrieve the file verdict details from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) based on which you want to retrieve the file verdict details from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "data": [
             {
                 "checksum": "",
                 "sid": "",
                 "kidsum": "",
                 "job_list": [
                     {
                         "score": "",
                         "jid": "",
                         "behavior_info": "",
                         "false_positive_negative": "",
                         "vid": "",
                         "untrusted": "",
                         "start_ts": "",
                         "rating": "",
                         "rsrcid": "",
                         "finish_ts": "",
                         "malware_name": ""
                     }
                 ],
                 "now": ""
             }
         ],
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": ""
}

operation: Get Job Behaviour

Input parameters

Parameter Description
Hash Type Type of the filehash whose associated job behaviour details you want to retrieve from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) whose associated job behaviour details you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "url": "",
         "data": {
             "behavior_files": ""
         },
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": "",
     "ver": ""
}

operation: Update White or Black List

Input parameters

Parameter Description
List Type Type of list on Fortinet FortiSandbox in which you want to add the indicator.
You can select from the following list types: White or Black.
Indicator Type Type of indicator that you want to add to the whitelist or blacklist in Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, SHA256, Domain, URL, or URL Regex.
Indicator Value Value of the indicator (considering the Indicator type you have chosen from the Indicator Type drop-down list) that you want to add to the whitelist or blacklist in Fortinet FortiSandbox.
Action Action that you want to apply on the whitelist or blacklist in Fortinet FortiSandbox, i.e., you can choose to append the specified indicator to the whitelist or blacklist in Fortinet FortiSandbox, or you can choose to delete the specified indicator from the whitelist or blacklist in Fortinet FortiSandbox.
You can choose from the following actions: Append, Replace, Clear, Download, or Delete.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "msg": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Toggle FPN State

Input parameters

Parameter Description
Job ID Job ID that you want to mark as false negative or false positive in Fortinet FortiSandbox.
Comments Comments that you want to provide for marking the specified job as false negative or false positive.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "msg": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get AV-Rescan Result

Input parameters

Parameter Description
From Start datetime from when you want to retrieve the AV-Rescan results from Fortinet FortiSandbox.
To End datetime till when you want to retrieve the AV-Rescan results from Fortinet FortiSandbox.
Need AV Version (Optional) Select this option, i.e., set as True, if you want this operation to return only the AV version.
By default, this is deselected, i.e., set as False.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "url": "",
         "data": {
             "rescan_list": [],
             "avadb_ver": ""
         },
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": "",
     "ver": ""
}

operation: Get All Installed VM

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "vm-list": [
                 {
                     "clonenum": "",
                     "id": "",
                     "name": "",
                     "version": "",
                     "status": ""
                 }
             ]
         }
     },
     "id": ""
}

operation: Get PDF Report

Input parameters

Parameter Description
Query Type Type of query to be used to retrieve the PDF report from Fortinet FortiSandbox.
Note: Query type only supports SHA256 filehash.
Query Value Value of the SHA256 filehash based on which you want to retrieve the PDF report from Fortinet FortiSandbox.

Output

The output contains a non-dictionary value.

operation: List Filehash or URL From Malware Package or URL Package

Input parameters

Parameter Description
Type Type based on which you want to retrieve a list of file hashes or URLs from the Malware Package or URL Package in Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, SHA256, or URL.
Lazy Use this parameter to specify the major and minor number of the Malware Package or the URL Package.
If you clear this option, i.e., set it to False, then the list of file hashes or URLs is retrieved from the Malware Package or URL Package of the specified major and minor number.
If you select this option, i.e., set it to True, then the latest version of the Malware Package or URL Package is used to retrieve the list of file hashes or URLs.
If this parameter is set as False, then you must specify the following:
  • Major: Major number of the Malware Package or the URL Package to be used to retrieve the list of file hashes or URLs.
  • Minor: Minor number of the Malware Package or the URL Package to be used to retrieve the list of file hashes or URLs.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "data": {
             "md5sum": "",
             "download_file": "",
             "major": "",
             "minor": ""
         },
         "url": "",
         "status": {
             "code": "",
             "message": ""
         }
     },
     "id": ""
}

Included playbooks

The Sample - Fortinet Fortisandbox - 1.0.0 playbook collection comes bundled with the Fortinet FortiSandbox connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Fortinet FortiSandbox connector.

  • Get All Installed VM
  • Get AV-Rescan Result
  • Get File Rating
  • Get File Verdict
  • Get Job Behaviour
  • Get Job Verdict Detail
  • Get PDF Report
  • Get Scan Stats
  • Get Submission Job List
  • Get System Status
  • Get URL Rating
  • List Filehash or URL From Malware Package or URL Package
  • Mark Sample False Negative or False Positive
  • Submit File
  • Submit URL
  • Update White or Black List

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

Fortinet FortiSandbox utilizes advanced detection, dynamic antivirus scanning, and threat scanning technology to detect viruses and APTs. Fortinet FortiSandbox executes suspicious files in the VM host module to determine if the file is High, Medium, or Low Risk, based on the behaviour observed in the VM sandbox module.

This document provides information about the Fortinet FortiSandbox connector, which facilitates automated interactions, with your Fortinet FortiSandbox server using FortiSOAR™ playbooks. Add the Fortinet FortiSandbox connector, as a step in FortiSOAR™ playbooks and perform automated operations such as submitting files to Fortinet FortiSandbox from the FortiSOAR™ "Attachments" module and retrieving the status of the system and scan stats from Fortinet FortiSandbox.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.12.1-253

Authored By: Fortinet

Certified: Yes 

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-fortinet-fortisandbox

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, select the Fortinet FortiSandbox connector row, and in the Configure tab enter the required configuration details. 

Parameter Description
Server URL URL of the Fortinet FortiSandbox server to which you will connect and perform automated operations.
Username Username of the Fortinet FortiSandbox server to which you will connect and perform automated operations.
Password Password used to access the Fortinet FortiSandbox 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 and onwards: 

Function Description Annotation and Category
Submit File Submits a file to Fortinet FortiSandbox from the FortiSOAR™ "Attachments" module, i.e., based on the attachment IRI you have specified. submit_file
Investigation
Submit URL Submits a URL(s) to Fortinet FortiSandbox. submit_url
Investigation
Get System Status Retrieves the status of the system from Fortinet FortiSandbox. get_system_status
Investigation
Get Scan Stats Retrieves the scan stats for the last 7 days from Fortinet FortiSandbox. get_scan_stats
Investigation
Get Submission Job List Retrieves all job IDs associated with submission ID you have specified from Fortinet FortiSandbox. get_job_list
Investigation
Get Job Verdict Detail Retrieves job verdict detail for job ID you have specified from Fortinet FortiSandbox. get_job_detail
Investigation
Get File Rating Retrieves file rating for the file type and filehash you have specified from Fortinet FortiSandbox. get_file_rating
Investigation
Get URL Rating Get rating details for the URL you have specified from Fortinet FortiSandbox. get_url_rating
Investigation
Get File Verdict Retrieves the file verdict details for the file type and filehash you have specified from Fortinet FortiSandbox. get_file_verdict
Investigation
Get Job Behaviour Retrieves job behaviour details associated with the file type and filehash you have specified from Fortinet FortiSandbox. get_job_details
Investigation
Update White or Black List Updates an existing whitelist or an existing blacklist in Fortinet FortiSandbox, based in on the input parameter such as indicator type and value, and action you have specified. update_white_black_list
Miscellaneous
Toggle FPN State Marks specified sample based on the Job ID you have specified as false negative or false positive in Fortinet FortiSandbox. toggle_fpn_state
Miscellaneous
Get AV-Rescan Result Retrieves AV-Rescan results for the time duration you have specified from Fortinet FortiSandbox. get_scan_result
Investigation
Get All Installed VM Retrieves the names and the clone numbers of all installed VMs on Fortinet FortiSandbox. get_installed_vm
Investigation
Get PDF Report Retrieves a PDF report from Fortinet FortiSandbox based on the query type and value parameter you have specified and creates an attachment in the FortiSOAR™ "Attachment" module if the report is found. get_report
Investigation
List Filehash or URL From Malware Package or URL Package Retrieves a list of file hashes or URLs based on the type you have specified from the Malware Package or URL Package in Fortinet FortiSandbox. list_filehash_url
Investigation

operation: Submit File

Input parameters

Parameter Description
Attachment IRI IRI of the attachment that you want to submit to Fortinet FortiSandbox.
Attachment IRI that is used to access the file directly from the FortiSOAR™ "Attachments" module.
VM Name (Optional) Name of the VM that will scan the specified URL file.
If you do not specify and VM Name, then the VM Name will default to the one that will be used.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "msg": "",
             "sid": "",
             "error": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Submit URL

Input parameters

Parameter Description
URL URL that you want to submit to Fortinet FortiSandbox.
Note: You can submit a single URL or multiple URLs in a list format.
VM Name (Optional) Name of the VM that will scan the specified URL.
If you do not specify and VM Name, then the VM Name will default to the one that will be used.
Timeout (Optional) Time after which the scan will timeout, i.e., the time in seconds of the length of the scan.
By default, the timeout value is set to 60 seconds.
Depth (Optional) This option specifies the depth of web links this operation should scan. Select this option, i.e., set to True, to crawl into the links of the specified URL for scanning purposes. Deselect this option, i.e., set to False, to scan only the specified URL and not any links of within the URL.

Output

The output contains the following populated JSON schema:
{
     "id": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "sid": "",
             "msg": "",
             "error": ""
         }
     },
     "ver": ""
}

operation: Get System Status

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "fdn_server_accessible": "",
             "Build": "",
             "Patch": "",
             "Platform Full Name": "",
             "Minor": "",
             "64-bit Applications": "",
             "Serial Number": "",
             "Time Zone": "",
             "Platform Type": "",
             "Branch Point": "",
             "Hostname": "",
             "Release Version Information": "",
             "wf_server_accessible": "",
             "vm_network_access": "",
             "cloud_server_accessible": "",
             "Current Time": "",
             "License Status": "",
             "Admin Domain Configuration": "",
             "Version": "",
             "FIPS Mode": "",
             "win_lic_activated": "",
             "Major": ""
         }
     },
     "id": ""
}

operation: Get Scan Stats

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "suspicious_low": "",
             "pending": "",
             "processing": "",
             "suspicious_high": "",
             "suspicious_medium": ""
         }
     },
     "id": ""
}

operation: Get Submission Job List

Input parameters

Parameter Description
Submission ID ID of the submission whose associated Job IDs you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "message": "",
             "code": ""
         },
         "url": "",
         "data": {
             "jids": [],
             "total_jids": ""
         }
     },
     "id": ""
}

operation: Get Job Verdict Detail

Input parameters

Parameter Description
Job ID ID of the job whose job verdict details you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "score": "",
             "false_positive_negative": "",
             "sha1": "",
             "now": "",
             "download_url": "",
             "detection_os": "",
             "finish_ts": "",
             "infected_os": "",
             "detail_url": "",
             "vid": "",
             "untrusted": "",
             "start_ts": "",
             "rating": "",
             "sha256": "",
             "category": "",
             "rating_source": "",
             "malware_name": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get File Rating

Input parameters

Parameter Description
Hash Type Type of the filehash based on which you want to retrieve the file rating from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) based on which you want to retrieve the file rating from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": {
             "score": "",
             "now": "",
             "untrusted": "",
             "start_ts": "",
             "rating": [],
             "finish_ts": ""
         },
         "url": "",
         "status": {
             "message": "",
             "code": 0
         }
     },
     "ver": "",
     "id": ""
}

operation: Get URL Rating

Input parameters

Parameter Description
URL URL for which you want to retrieve the rating details from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "data": [
             {
                 "behavior_info": "",
                 "url": "",
                 "now": "",
                 "untrusted": "",
                 "start_ts": "",
                 "rating": [],
                 "finish_ts": ""
             }
         ],
         "url": "",
         "status": {
             "code": "",
             "message": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get File Verdict

Input parameters

Parameter Description
Hash Type Type of the filehash based on which you want to retrieve the file verdict details from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) based on which you want to retrieve the file verdict details from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "data": [
             {
                 "checksum": "",
                 "sid": "",
                 "kidsum": "",
                 "job_list": [
                     {
                         "score": "",
                         "jid": "",
                         "behavior_info": "",
                         "false_positive_negative": "",
                         "vid": "",
                         "untrusted": "",
                         "start_ts": "",
                         "rating": "",
                         "rsrcid": "",
                         "finish_ts": "",
                         "malware_name": ""
                     }
                 ],
                 "now": ""
             }
         ],
         "url": "",
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": ""
}

operation: Get Job Behaviour

Input parameters

Parameter Description
Hash Type Type of the filehash whose associated job behaviour details you want to retrieve from Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, or SHA256.
Filehash Value of the filehash (considering the filehash type you have chosen from the Hash Type drop-down list) whose associated job behaviour details you want to retrieve from Fortinet FortiSandbox.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "url": "",
         "data": {
             "behavior_files": ""
         },
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": "",
     "ver": ""
}

operation: Update White or Black List

Input parameters

Parameter Description
List Type Type of list on Fortinet FortiSandbox in which you want to add the indicator.
You can select from the following list types: White or Black.
Indicator Type Type of indicator that you want to add to the whitelist or blacklist in Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, SHA256, Domain, URL, or URL Regex.
Indicator Value Value of the indicator (considering the Indicator type you have chosen from the Indicator Type drop-down list) that you want to add to the whitelist or blacklist in Fortinet FortiSandbox.
Action Action that you want to apply on the whitelist or blacklist in Fortinet FortiSandbox, i.e., you can choose to append the specified indicator to the whitelist or blacklist in Fortinet FortiSandbox, or you can choose to delete the specified indicator from the whitelist or blacklist in Fortinet FortiSandbox.
You can choose from the following actions: Append, Replace, Clear, Download, or Delete.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "msg": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Toggle FPN State

Input parameters

Parameter Description
Job ID Job ID that you want to mark as false negative or false positive in Fortinet FortiSandbox.
Comments Comments that you want to provide for marking the specified job as false negative or false positive.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "msg": ""
         }
     },
     "ver": "",
     "id": ""
}

operation: Get AV-Rescan Result

Input parameters

Parameter Description
From Start datetime from when you want to retrieve the AV-Rescan results from Fortinet FortiSandbox.
To End datetime till when you want to retrieve the AV-Rescan results from Fortinet FortiSandbox.
Need AV Version (Optional) Select this option, i.e., set as True, if you want this operation to return only the AV version.
By default, this is deselected, i.e., set as False.

Output

The output contains the following populated JSON schema:
{
     "result": {
         "url": "",
         "data": {
             "rescan_list": [],
             "avadb_ver": ""
         },
         "status": {
             "message": "",
             "code": ""
         }
     },
     "id": "",
     "ver": ""
}

operation: Get All Installed VM

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "status": {
             "code": "",
             "message": ""
         },
         "url": "",
         "data": {
             "vm-list": [
                 {
                     "clonenum": "",
                     "id": "",
                     "name": "",
                     "version": "",
                     "status": ""
                 }
             ]
         }
     },
     "id": ""
}

operation: Get PDF Report

Input parameters

Parameter Description
Query Type Type of query to be used to retrieve the PDF report from Fortinet FortiSandbox.
Note: Query type only supports SHA256 filehash.
Query Value Value of the SHA256 filehash based on which you want to retrieve the PDF report from Fortinet FortiSandbox.

Output

The output contains a non-dictionary value.

operation: List Filehash or URL From Malware Package or URL Package

Input parameters

Parameter Description
Type Type based on which you want to retrieve a list of file hashes or URLs from the Malware Package or URL Package in Fortinet FortiSandbox.
You can choose from the following values: MD5, SHA1, SHA256, or URL.
Lazy Use this parameter to specify the major and minor number of the Malware Package or the URL Package.
If you clear this option, i.e., set it to False, then the list of file hashes or URLs is retrieved from the Malware Package or URL Package of the specified major and minor number.
If you select this option, i.e., set it to True, then the latest version of the Malware Package or URL Package is used to retrieve the list of file hashes or URLs.
If this parameter is set as False, then you must specify the following:
  • Major: Major number of the Malware Package or the URL Package to be used to retrieve the list of file hashes or URLs.
  • Minor: Minor number of the Malware Package or the URL Package to be used to retrieve the list of file hashes or URLs.

Output

The output contains the following populated JSON schema:
{
     "ver": "",
     "result": {
         "data": {
             "md5sum": "",
             "download_file": "",
             "major": "",
             "minor": ""
         },
         "url": "",
         "status": {
             "code": "",
             "message": ""
         }
     },
     "id": ""
}

Included playbooks

The Sample - Fortinet Fortisandbox - 1.0.0 playbook collection comes bundled with the Fortinet FortiSandbox connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Fortinet FortiSandbox 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.