Fortinet Document Library

Version:


Table of Contents

Joe Sandbox Cloud

1.0.0
Copy Link

 

About the connector

Joe Sandbox detects and analyzes potential malicious files and URLs on Windows, Android, Mac OS, Linux, and iOS for suspicious activities. It performs deep malware analysis and generates comprehensive and detailed analysis reports.

This document provides information about the Joe Sandbox Cloud connector, which facilitates automated interactions, with Joe Sandbox Cloud server using FortiSOAR™ playbooks. Add the Joe Sandbox Cloud connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting files to the Joe Sandbox Cloud server for analyzes and searching for and retrieving reports from the Joe Sandbox Cloud server.

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Joe Sandbox Cloud Pro Version: 2.0 and later

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-joe-sandbox-cloud

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

 

Prerequisites to configuring the connector

  • You must have the URL of the Joe Sandbox Cloud server to which you will connect and perform the automated operations and the API Key configured for your account to access that Joe Sandbox Cloud server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

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

 

Parameter Description
Server URL URL of the Joe Sandbox Cloud server to which you will connect and perform automated operations.
API Key API Key that is configured for your account for the Joe Sandbox 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.
Defaults to 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
Get All System Information Retrieves a list of all systems and their details from your configured Joe Sandbox Cloud server. get_all_system_information
Investigation
Submit File Submits a file to the Joe Sandbox Cloud server for analyzes from your FortiSOAR™ Attachmentmodule. detonate_file
Investigation
Submit URL Submits a URL to the Joe Sandbox Cloud server for analyzes. detonate_url
Investigation
Get Submission Status Retrieves the status of a submitted file or URL from your configured Joe Sandbox Cloud server, based on the Web ID you have specified. A Web ID is a unique ID for a report. get_submitted_sample_state
Investigation
Search Report Retrieves a list of Web IDs (Unique ID for a report) from your configured Joe Sandbox Cloud server, based on the query you have specified. search_report
Investigation
Get Report Retrieves the report of a submitted file or URL from your configured Joe Sandbox Cloud server, based on the Web ID you have specified. A Web ID is a unique ID for a report. get_report
Investigation
Get All Analysed Sample Details Retrieves details of all analyzed samples (Web IDs) from your configured Joe Sandbox Cloud server. get_details
Investigation
Get Account Information Retrieves details of all accounts configured on your Joe Sandbox Cloud server. get_account_info
Investigation

 

operation: Get All System Information

Input parameters

None.

Output

The JSON output contains a list of all systems and their sandbox information retrieved from your configured Joe Sandbox Cloud.

Following image displays a sample output:

Sample output of the Get All System Information operation

operation: Submit File

Input parameters

Note: You can only upload files to the Joe Sandbox Cloud channels on your configured Joe Sandbox Cloud from the FortiSOAR™ Attachment module.

 

Parameter Description
File ID ID or IRI value of the file that you want to submit for analyzes from the FortiSOAR™ Attachments module to your configured Joe Sandbox Cloud server. The File ID or File IRI is used to access the file in the Attachments module of FortiSOAR™.
In the playbook, this defaults to the {{vars.attachment_id}} value if you have specified the file ID, or {{vars.file_iri}} value if you have specified the file IRI.
System (Optional) Systems on which you want to analyze the file. You can specify more than one system in this field.
For example, on Windows, if you do not specify any systems then systems are automatically selected for this field, such as["w7x64", "w7", "w10"].
Comments (Optional) Comments to add to the file that you are submitting to your configured Joe Sandbox Cloud server.
Analysis Time (Optional) Analysis time in seconds that you want to set for the file that you are submitting to your configured Joe Sandbox Cloud server. You can set any time between 20 to 500 seconds.
By default, this is set to 120 seconds.
Office Files Passwords (Optional) Password to decrypt Microsoft Office documents.
Internet Access Select this option (set it to true) to enable full internet access.
By default, this is set as false.
Hybrid Code Analysis Select this option (set it to true) to enable Hybrid Code Analysis (HCA).
By default, this is set as false.
Hybrid Decompilation Select this option (set it to true) to enable Hybrid Decompilation (DEC).
By default, this is set as false.
Report Cache Select this option (set it to true) to enable report cache, i.e, check the cache for existing report before running a full analyzes.
By default, this is set as false.
Static Only Select this option (set it to true) to perform only static analyzes.
By default, this is set as false, i.e., both static and dynamic analyzes is performed.
SSL Inspection Select this option (set it to true) to enable HTTPS Inspection.
By default, this is set as false.
VBA Instrumentation Select this option (set it to true) to enable VBA Instrumentation.
By default, this is set as false.
JS Instrumentation Select this option (set it to true) to enable JavaScript Instrumentation.
By default, this is set as false.
Java Jar Tracing Select this option (set it to true) to enable Java Jar Tracing, i.e., two analyzes are performed.
By default, this is set as false.
Email Notification Email address that should be sent a notification once the analyzes of the submitted file is completed.

 

Output

The JSON output contains the Web ID associated with the submitted file from your configured Joe Sandbox Cloud server. You can use this Web ID in future to query and retrieve reports for this file from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Submit File operation

operation: Submit URL

Input parameters

 

Parameter Description
URL URL that you want to submit for analyzes to your configured Joe Sandbox Cloud server.
System (Optional) Systems on which you want to analyze the URL. You can specify more than one system in this field. By default, the system that is chosen is dependent on the file extension of the submitted file or URL.
For example, on Windows, if you do not specify any systems then systems are automatically selected for this field, such as["w7x64", "w7", "w10"].
Comments (Optional) Comments to add to the URL that you are submitting to your configured Joe Sandbox Cloud server.
Analysis Time (Optional) Analysis time in seconds that you want to set for the URL that you are submitting to your configured Joe Sandbox Cloud server. You can set any time between 20 to 500 seconds.
By default, this is set to 120 seconds.
Office Files Passwords (Optional) Password to decrypt Microsoft Office documents.
Internet Access Select this option (set it to true) to enable full internet access.
By default, this is set as false.
Hybrid Code Analysis Select this option (set it to true) to enable Hybrid Code Analysis (HCA).
By default, this is set as false.
Hybrid Decompilation Select this option (set it to true) to enable Hybrid Decompilation (DEC).
By default, this is set as false.
Report Cache Select this option (set it to true) to enable report cache, i.e, check the cache for existing report before running a full analyzes.
By default, this is set as false.
Static Only Select this option (set it to true) to perform only static analyzes.
By default, this is set as false, i.e., both static and dynamic analyzes is performed.
SSL Inspection Select this option (set it to true) to enable HTTPS Inspection.
By default, this is set as false.
VBA Instrumentation Select this option (set it to true) to enable VBA Instrumentation.
By default, this is set as false.
JS Instrumentation Select this option (set it to true) to enable JavaScript Instrumentation.
By default, this is set as false.
Java Jar Tracing Select this option (set it to true) to enable Java Jar Tracing, i.e., two analyzes are performed.
By default, this is set as false.
Email Notification Email address that should be sent a notification once the analyzes of the submitted URL is completed.

 

Output

The JSON output contains the Web ID associated with the submitted URL from your configured Joe Sandbox Cloud server. You can use this Web ID in future to query and retrieve reports for this URL from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Submit URL operation

operation: Get Submission Status

Input parameters

 

Parameter Description
API (Web) ID ID of the submitted file or URL for which you want to retrieve the status information from your configured Joe Sandbox Cloud server.
When you submit a file or URL to your configured Joe Sandbox Cloud server, the output of those operations contains the API ID (or Web ID) associated with the submitted file or URL.

 

Output

The JSON output contains the status of the submitted file or URL, based on the Web ID that you have specified, retrieved from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Submission Status operation

operation: Search Report

Input parameters

 

Parameter Description
Query Query based on which you want to retrieve reports (Web IDs) from your configured Joe Sandbox Cloud server. A Web ID is a unique ID for a report.
While searching for a report, the Joe Sandbox Cloud server considers the following fields: webid, md5, sha1, sha256, filename, URL, and comments.

 

Output

The JSON output contains a list of Web IDs (Unique ID for a report) retrieved from your configured Joe Sandbox Cloud server, based on the query you have specified.

Following image displays a sample output:

Sample output of the Search Report operation

operation: Get Report

Input parameters

 

Parameter Description
API (Web) ID ID of the submitted file or URL for which you want to retrieve the report information from your configured Joe Sandbox Cloud server.
When you submit a file or URL to your configured Joe Sandbox Cloud server, the output of those operations contains the API ID (or Web ID) associated with the submitted file or URL.

 

Output

The JSON output contains the report associated with a submitted file or URL, based on the Web ID that you have specified, retrieved from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Report operation

operation: Get All Analysed Sample Details

Input parameters

None.

Output

The JSON output contains a list of all analyzed samples (Web IDs) and their details retrieved from your configured Joe Sandbox Cloud.

Following image displays a sample output:

Sample output of the Get All Analysed Sample Details operation

operation: Get Account Information

Input parameters

None.

Output

The JSON output contains details of all accounts configured on your Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Account Information operation

Included playbooks

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

  • Get Account Information
  • Get All Analysed Sample Details
  • Get All System Information
  • Get Report
  • Get Submission Status
  • Search Report
  • Submit File
  • Submit URL

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

Joe Sandbox detects and analyzes potential malicious files and URLs on Windows, Android, Mac OS, Linux, and iOS for suspicious activities. It performs deep malware analysis and generates comprehensive and detailed analysis reports.

This document provides information about the Joe Sandbox Cloud connector, which facilitates automated interactions, with Joe Sandbox Cloud server using FortiSOAR™ playbooks. Add the Joe Sandbox Cloud connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting files to the Joe Sandbox Cloud server for analyzes and searching for and retrieving reports from the Joe Sandbox Cloud server.

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

Compatibility with Joe Sandbox Cloud Pro Version: 2.0 and later

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-joe-sandbox-cloud

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

 

Parameter Description
Server URL URL of the Joe Sandbox Cloud server to which you will connect and perform automated operations.
API Key API Key that is configured for your account for the Joe Sandbox 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.
Defaults to 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
Get All System Information Retrieves a list of all systems and their details from your configured Joe Sandbox Cloud server. get_all_system_information
Investigation
Submit File Submits a file to the Joe Sandbox Cloud server for analyzes from your FortiSOAR™ Attachmentmodule. detonate_file
Investigation
Submit URL Submits a URL to the Joe Sandbox Cloud server for analyzes. detonate_url
Investigation
Get Submission Status Retrieves the status of a submitted file or URL from your configured Joe Sandbox Cloud server, based on the Web ID you have specified. A Web ID is a unique ID for a report. get_submitted_sample_state
Investigation
Search Report Retrieves a list of Web IDs (Unique ID for a report) from your configured Joe Sandbox Cloud server, based on the query you have specified. search_report
Investigation
Get Report Retrieves the report of a submitted file or URL from your configured Joe Sandbox Cloud server, based on the Web ID you have specified. A Web ID is a unique ID for a report. get_report
Investigation
Get All Analysed Sample Details Retrieves details of all analyzed samples (Web IDs) from your configured Joe Sandbox Cloud server. get_details
Investigation
Get Account Information Retrieves details of all accounts configured on your Joe Sandbox Cloud server. get_account_info
Investigation

 

operation: Get All System Information

Input parameters

None.

Output

The JSON output contains a list of all systems and their sandbox information retrieved from your configured Joe Sandbox Cloud.

Following image displays a sample output:

Sample output of the Get All System Information operation

operation: Submit File

Input parameters

Note: You can only upload files to the Joe Sandbox Cloud channels on your configured Joe Sandbox Cloud from the FortiSOAR™ Attachment module.

 

Parameter Description
File ID ID or IRI value of the file that you want to submit for analyzes from the FortiSOAR™ Attachments module to your configured Joe Sandbox Cloud server. The File ID or File IRI is used to access the file in the Attachments module of FortiSOAR™.
In the playbook, this defaults to the {{vars.attachment_id}} value if you have specified the file ID, or {{vars.file_iri}} value if you have specified the file IRI.
System (Optional) Systems on which you want to analyze the file. You can specify more than one system in this field.
For example, on Windows, if you do not specify any systems then systems are automatically selected for this field, such as["w7x64", "w7", "w10"].
Comments (Optional) Comments to add to the file that you are submitting to your configured Joe Sandbox Cloud server.
Analysis Time (Optional) Analysis time in seconds that you want to set for the file that you are submitting to your configured Joe Sandbox Cloud server. You can set any time between 20 to 500 seconds.
By default, this is set to 120 seconds.
Office Files Passwords (Optional) Password to decrypt Microsoft Office documents.
Internet Access Select this option (set it to true) to enable full internet access.
By default, this is set as false.
Hybrid Code Analysis Select this option (set it to true) to enable Hybrid Code Analysis (HCA).
By default, this is set as false.
Hybrid Decompilation Select this option (set it to true) to enable Hybrid Decompilation (DEC).
By default, this is set as false.
Report Cache Select this option (set it to true) to enable report cache, i.e, check the cache for existing report before running a full analyzes.
By default, this is set as false.
Static Only Select this option (set it to true) to perform only static analyzes.
By default, this is set as false, i.e., both static and dynamic analyzes is performed.
SSL Inspection Select this option (set it to true) to enable HTTPS Inspection.
By default, this is set as false.
VBA Instrumentation Select this option (set it to true) to enable VBA Instrumentation.
By default, this is set as false.
JS Instrumentation Select this option (set it to true) to enable JavaScript Instrumentation.
By default, this is set as false.
Java Jar Tracing Select this option (set it to true) to enable Java Jar Tracing, i.e., two analyzes are performed.
By default, this is set as false.
Email Notification Email address that should be sent a notification once the analyzes of the submitted file is completed.

 

Output

The JSON output contains the Web ID associated with the submitted file from your configured Joe Sandbox Cloud server. You can use this Web ID in future to query and retrieve reports for this file from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Submit File operation

operation: Submit URL

Input parameters

 

Parameter Description
URL URL that you want to submit for analyzes to your configured Joe Sandbox Cloud server.
System (Optional) Systems on which you want to analyze the URL. You can specify more than one system in this field. By default, the system that is chosen is dependent on the file extension of the submitted file or URL.
For example, on Windows, if you do not specify any systems then systems are automatically selected for this field, such as["w7x64", "w7", "w10"].
Comments (Optional) Comments to add to the URL that you are submitting to your configured Joe Sandbox Cloud server.
Analysis Time (Optional) Analysis time in seconds that you want to set for the URL that you are submitting to your configured Joe Sandbox Cloud server. You can set any time between 20 to 500 seconds.
By default, this is set to 120 seconds.
Office Files Passwords (Optional) Password to decrypt Microsoft Office documents.
Internet Access Select this option (set it to true) to enable full internet access.
By default, this is set as false.
Hybrid Code Analysis Select this option (set it to true) to enable Hybrid Code Analysis (HCA).
By default, this is set as false.
Hybrid Decompilation Select this option (set it to true) to enable Hybrid Decompilation (DEC).
By default, this is set as false.
Report Cache Select this option (set it to true) to enable report cache, i.e, check the cache for existing report before running a full analyzes.
By default, this is set as false.
Static Only Select this option (set it to true) to perform only static analyzes.
By default, this is set as false, i.e., both static and dynamic analyzes is performed.
SSL Inspection Select this option (set it to true) to enable HTTPS Inspection.
By default, this is set as false.
VBA Instrumentation Select this option (set it to true) to enable VBA Instrumentation.
By default, this is set as false.
JS Instrumentation Select this option (set it to true) to enable JavaScript Instrumentation.
By default, this is set as false.
Java Jar Tracing Select this option (set it to true) to enable Java Jar Tracing, i.e., two analyzes are performed.
By default, this is set as false.
Email Notification Email address that should be sent a notification once the analyzes of the submitted URL is completed.

 

Output

The JSON output contains the Web ID associated with the submitted URL from your configured Joe Sandbox Cloud server. You can use this Web ID in future to query and retrieve reports for this URL from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Submit URL operation

operation: Get Submission Status

Input parameters

 

Parameter Description
API (Web) ID ID of the submitted file or URL for which you want to retrieve the status information from your configured Joe Sandbox Cloud server.
When you submit a file or URL to your configured Joe Sandbox Cloud server, the output of those operations contains the API ID (or Web ID) associated with the submitted file or URL.

 

Output

The JSON output contains the status of the submitted file or URL, based on the Web ID that you have specified, retrieved from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Submission Status operation

operation: Search Report

Input parameters

 

Parameter Description
Query Query based on which you want to retrieve reports (Web IDs) from your configured Joe Sandbox Cloud server. A Web ID is a unique ID for a report.
While searching for a report, the Joe Sandbox Cloud server considers the following fields: webid, md5, sha1, sha256, filename, URL, and comments.

 

Output

The JSON output contains a list of Web IDs (Unique ID for a report) retrieved from your configured Joe Sandbox Cloud server, based on the query you have specified.

Following image displays a sample output:

Sample output of the Search Report operation

operation: Get Report

Input parameters

 

Parameter Description
API (Web) ID ID of the submitted file or URL for which you want to retrieve the report information from your configured Joe Sandbox Cloud server.
When you submit a file or URL to your configured Joe Sandbox Cloud server, the output of those operations contains the API ID (or Web ID) associated with the submitted file or URL.

 

Output

The JSON output contains the report associated with a submitted file or URL, based on the Web ID that you have specified, retrieved from your configured Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Report operation

operation: Get All Analysed Sample Details

Input parameters

None.

Output

The JSON output contains a list of all analyzed samples (Web IDs) and their details retrieved from your configured Joe Sandbox Cloud.

Following image displays a sample output:

Sample output of the Get All Analysed Sample Details operation

operation: Get Account Information

Input parameters

None.

Output

The JSON output contains details of all accounts configured on your Joe Sandbox Cloud server.

Following image displays a sample output:

Sample output of the Get Account Information operation

Included playbooks

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