.png)
Joe Sandbox
LAST UPDATED: JAN 14, 2025
Overview
Joe Sandbox is a sophisticated malware analysis platform that provides in-depth, automated analysis of potentially malicious files, URLs, or documents.
D3 SOAR is providing REST operations to function with Joe Sandbox.
Joe Sandbox is available for use in:
Connection
To connect to Joe Sandbox from D3 SOAR, follow this part to collect the required information below:
Parameter | Description | Example |
Server URL | The server URL used for the connection. | https://jbxcloud.joesecurity.org |
API Key | The API key used to authenticate the connection. | ***** |
API Version | The API version used for the connection. | v2 |
Configuring Joe Sandbox to Work with D3 SOAR
Log in to Joe Sandbox.
Enter the username.
Enter the password.
Click on the Log in button.
Click on the
icon, then click on the API Key link.
Click on the Copy Content to Clipboard button (
) to copy the API Key. Refer to step 3i sub-step 2 in Configuring D3 SOAR to Work with Joe Sandbox.
READER NOTE
A Group Admin can follow these steps to add new users to Joe Sandbox:
Click on the
icon, then click on the Account link.
Click on the Add User button.
Add the new user's information.
Enter their username.
Enter their email address.
(Optional) Check the Grant Admin Role checkbox to make the new user a Group Admin.
Only Group Admins can create and manage user accounts.
Click on the Add User button.
The new user will receive an email to set their password and can then generate their own API key.
Configuring D3 SOAR to Work with Joe Sandbox
Log in to D3 SOAR.
Find the Joe Sandbox integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Joe Sandbox in the search box to find the integration, then click it to select it.
Click on the + Connection button on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Joe Sandbox.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add a description for the connection.
Active: Check the checkbox to ensure the connection is available for use.
Privileged: Chooses access level for the connection. Only roles with Privileged Connection settings can set and use privileged integration connections.
Configure User Permissions: Defines which users have access to the connection.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input the Server URL. The default value is https://jbxcloud.joesecurity.org.
2. Copy the API Key from the Joe Sandbox platform. Refer to step 3 of Configuring Joe Sandbox to Work with D3 SOAR.
3. Input the API Version. The default value is v2.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Joe Sandbox includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command function, users can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Joe Sandbox API, refer to the Joe Sandbox API reference. Users must log in to view the API reference.
Download Report
Downloads analysis reports using their associated Web IDs.
READER NOTE
Web IDs is a required parameter to run this command.
Run the Get Analysis List command to obtain the Web IDs. Web IDs can be found in the raw data at the path $.data[*].webid.
Input
Input Parameter | Required/Optional | Description | Example |
Web IDs | Required | The Web IDs associated with the analysis reports to download. Web IDs can be obtained using the Get Analysis List command. |
JSON
|
Type | Optional | The format type for the report. Acceptable values are html, lighthtml, executive, or pdf. |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Download Report failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Analysis not found. |
Error Sample Data Download Report failed. Status Code: 404. Message: Analysis not found. |
Download Sample File
Downloads sample files using their associated Web IDs.
READER NOTE
Web IDs is a required parameter to run this command.
Run the Get Analysis Information command to obtain the Web IDs. Web IDs can be found in the raw data at the path $.[*].data.webid.
Only certain Web IDs are allowed for this command. Follow these steps to identify the permitted Web IDs:
Run the Get Analysis List command to obtain all Web IDs, then copy the data from the Result table.
Click into the Get Analysis Information command.
Convert the data into a comma-separated list (e.g., 12345, 22345) and input it into the Web IDs parameter.
Run the command, click on the Raw Data tab, then look for the "filename" field value.
Web IDs that can be used for this command will have a "filename" field value in the format *****.***** (e.g., "demo.exe").
Identify the corresponding Web ID.
Input
Input Parameter | Required/Optional | Description | Example |
Web IDs | Required | The Web IDs associated with the sample files to download. Web IDs can be obtained using the Get Analysis Information command. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Download Sample File failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Analysis not found. |
Error Sample Data Download Sample File failed. Status Code: 404. Message: Analysis not found. |
Get Analysis Information
Retrieves detailed information for the specified analyses.
READER NOTE
Web IDs is a required parameter to run this command.
Run the Get Analysis List command to obtain the Web IDs. Web IDs can be found in the raw data at the path $.data[*].webid.
Input
Input Parameter | Required/Optional | Description | Example |
Web IDs | Required | The Web IDs of the analyses for which to retrieve detailed information. Web IDs can be obtained using the Get Analysis List command. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Analysis Information failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Webid not found. |
Error Sample Data Get Analysis Information failed. Status Code: 404. Message: Webid not found. |
Get Analysis List
Retrieves a list of all analysis Web IDs.
Input
N/A
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Analysis List failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid API key. |
Error Sample Data Get Analysis List failed. Status Code: 403. Message: Invalid API key. |
Get Submission Information
Retrieves detailed information for the specified submissions.
READER NOTE
Submission IDs is a required parameter to run this command.
Run the List Submissions command to obtain the Submission IDs. Submission IDs can be found in the raw data at the path $.data[*].submission_id.
Input
Input Parameter | Required/Optional | Description | Example |
Submission IDs | Required | The Submission IDs of the submissions for which to retrieve detailed information. Submission IDs can be obtained using the List Submissions command. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Get Submission Information failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Submission not found. |
Error Sample Data Get Submission Information failed. Status Code: 404. Message: Submission not found. |
Is Online
Checks if the Joe Sandbox backend is online or in maintenance mode.
Input
N/A
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Is Online failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid API key. |
Error Sample Data Is Online failed. Status Code: 403. Message: Invalid API key. |
List Submissions
Lists all submissions.
Input
N/A
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Submissions failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid API key. |
Error Sample Data List Submissions failed. Status Code: 403. Message: Invalid API key. |
Search
Searches through all analyses using either a query or an XPath expression but not both.
Input
Input Parameter | Required/Optional | Description | Example |
Query | Optional | Searches for the specified string in the following fields: MD5, SHA1, SHA256, filename, threat name, URL, tags, and comments. | https://*****.*****/ |
Xpath | Optional | The XPath expression and corresponding value used to search within the XML report. All fields within the report can be queried. Refer to Filters | Joe Sandbox Cloud for detailed information. | fileinfo[sha1='*****'] |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Search failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: ***** is not a valid XPath expression. |
Error Sample Data Search failed. Status Code: 400. Message:***** is not a valid XPath expression. |
Submit Sample File
Submits the specified files to be analyzed.
File IDs and File Source
It is not recommended to use the Test Command feature with the Submit Sample File command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:
Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.
Input
Input Parameter | Required/Optional | Description | Example |
File IDs | Required | The file IDs of the file source to submit for analysis. |
JSON
|
File Source | Optional | The file source of the files to submit for analysis. The options for file source are:
| IR_ATCHMNT |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Submit Sample File failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 404. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The file does not exist |
Error Sample Data Submit Sample File failed. Status Code: 404. Message: The file does not exist. |
Submit URL
Submits the specified URLs to be analyzed.
Input
Input Parameter | Required/Optional | Description | Example |
URLs | Required | The URLs to submit for analysis. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Submit URL failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid API key. |
Error Sample Data Submit URL failed. Status Code: 403. Message: Invalid API key. |
Test Connection
Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Output Type | Description | Return Data Type |
Return Data | Indicates one of the possible command execution states: Successful or Failed. The Failed state can be triggered by any of the following errors:
More details about an error can be viewed in the Error tab. | String |
Error Handling
If the Return Data displays Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Test Connection failed. Failed to check the connector. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Joe Sandbox portal. Refer to the HTTP Status Code Registry for details. | Status Code: 403. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid API key. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 403. Message: Invalid API key. |