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