Fortinet FortiSandbox

Fortinet FortiSandbox is a cybersecurity solution that provides advanced threat protection through sandboxing technology.

Fortinet FortiSandbox is a powerful security solution designed to detect and analyze advanced threats through sandboxing technology. This connector enables seamless integration with Swimlane Turbine, allowing users to automate threat detection and response workflows. By leveraging FortiSandbox's capabilities, Swimlane Turbine users can efficiently manage file and URL submissions, retrieve detailed verdicts and reports, and enhance their security operations with minimal manual intervention.

Limitations

Only submissions that are still in the queue can be canceled; jobs already processing cannot be canceled.

File uploads are subject to FortiSandbox size limits (e.g. files under 20MB for on-demand submission).

PDF report generation can be slow for large or multi-URL submissions.

All API requests use JSON-RPC over HTTP; parameters are sent inside a loginname object with session-based authentication.

Supported Version

The FortiSandbox connector supports the following:

FortiSandbox JSON-RPC API (scan and alert namespaces):

Scan result endpoints: get-jobs-of-submission, file verdict, url rating, job verdict, get-pdf-report.

Alert on-demand endpoints: submit-file (file and URL), cancel-submission.

HTTP Basic Authentication for initial login; session token is used for subsequent JSON-RPC calls.

Configuration

Prerequisites

Before you can use the Fortinet FortiSandbox connector for Turbine, you'll need access to the Fortinet FortiSandbox API. This requires the following:

HTTP Basic authentication using the following parameters:

URL: The endpoint URL for accessing Fortinet FortiSandbox services.

Username: Your Fortinet FortiSandbox account username.

Password: The password associated with your Fortinet FortiSandbox account.

Authentication Methods

HTTP Basic Authentication

Setup Instructions:

FortiSandbox uses HTTP Basic authentication for API access. The connector sends the configured username and password to obtain a session token used for JSON-RPC requests. Follow the steps below:

Obtain a FortiSandbox user account with API (JSON-RPC) access from your FortiSandbox administrator.

In Swimlane Turbine, create an asset for the Fortinet FortiSandbox connector.

Enter the URL of your FortiSandbox server (include /jsonrpc in the path if your deployment uses it).

Enter the Username and Password for the FortiSandbox API user.

Set Verify SSL to match your environment (disable only if using self-signed certificates and you accept the risk).

Optionally configure HTTP(s) Proxy if traffic must go through a proxy.

Document References:

FortiSandbox API – Scan

FortiSandbox API – Alert

FortiSandbox Authentication

Troubleshoot Tips

Ensure the asset URL includes the correct base path (e.g. https://host/jsonrpc) if your FortiSandbox uses JSON-RPC under a path.

If requests fail with authentication errors, verify the user has API access and that the username and password are correct.

For self-signed or internal certificates, you may need to disable Verify SSL in the asset; use only in trusted environments.

Capabilities

Get Jobs of Submission

Get File Verdict

Get URL Rating

Get Job Verdict

Get PDF Report

Submission File Upload

Submission URL Upload

Cancel Submission

Get Jobs of Submission

Returns the list of job IDs and status for a given submission ID. Use this after submitting a file or URL to track associated scan jobs.

More details can be found in the FortiSandbox Scan API – get-jobs-of-submission.

Get File Verdict

Returns the sandbox verdict for a file identified by its hash (MD5, SHA1, or SHA256). Use this to check whether a file has been previously analyzed and to retrieve its rating and malware name.

More details can be found in the FortiSandbox Scan API – file.

Get URL Rating

Returns the sandbox rating for one or more URLs. Use this to check whether URLs have been analyzed and to retrieve their safety rating (e.g. Clean, Malicious).

More details can be found in the FortiSandbox Scan API – urlrating.

Get Job Verdict

Returns the full verdict and metadata for a specific job ID, including rating, score, file hashes, malware name, and detail URL.

More details can be found in the FortiSandbox Scan API – job.

Get PDF Report

Returns a PDF scan report for a job, queried by job ID (jid) or by file SHA256 hash. The report is returned as base64-encoded content with a report name.

More details can be found in the FortiSandbox Scan API – get-pdf-report.

Submission File Upload

Submits a file for on-demand sandbox analysis. The file is sent to FortiSandbox; the response includes a submission ID (sid) that can be used with Get Jobs of Submission and Get Job Verdict.

More details can be found in the FortiSandbox Alert API – submit-file.

Submission URL Upload

Submits one or more URLs for on-demand sandbox analysis. The response includes a submission ID (sid) for tracking jobs.

More details can be found in the FortiSandbox Alert API – submit-file.

Cancel Submission

Cancels a queued submission by submission ID. Only submissions that have not yet started processing can be canceled.

More details can be found in the FortiSandbox Alert API – cancel-submission.

Additional Documentation

Fortinet FortiSandbox Connector Documentation

Fortinet FortiSandbox API Documentation

Configurations

HTTP Basic Authentication

Authenticates using username and password.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
username	Username	string	Required
password	Password	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Cancel Submission

Cancel an active submission in Fortinet FortiSandbox using the provided login credentials within the JSON body.

Endpoint

URL: /jsonrpc/alert/ondemand/cancel-submission

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use exec for this action.
loginname.params	array	Optional	Request parameters for cancel-submission call.
loginname.params.url	string	Optional	Must be "/alert/ondemand/cancel-submission".
loginname.params.sid	string	Optional	Submission ID to cancel.
loginname.params.reason	string	Optional	Optional reason for cancellation.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","sid":"string"}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":16,"result":{"status":{"code":0,"message":"OK"},"url":"/alert/ondemand/cancel-submission"},"ver":"4.2.1"}

Get File Verdict

Retrieve the verdict of a file by its hash from Fortinet FortiSandbox using JSON-RPC's /scan/result/file method. Requires login credentials.

Endpoint

URL: /jsonrpc/scan/result/file

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use get for this action.
loginname.params	array	Optional	Request parameters for file verdict lookup.
loginname.params.url	string	Optional	Must be "/scan/result/file".
loginname.params.ctype	string	Optional	Hash algorithm for the file checksum.
loginname.params.checksum	string	Optional	File hash value in the selected format.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","ctype":"string","checksum":"string"}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	object	Response data
result.data.behavior_info	number	Response data
result.data.detection_os	array	Response data
result.data.false_positive_negative	array	Response data
result.data.file_name	string	Response data
result.data.finish_ts	number	Response data
result.data.ftype	array	Response data
result.data.infected_os	array	Response data
result.data.jid	array	Response data
result.data.malware_name	array	Response data
result.data.now	number	Response data
result.data.pwd_extn	array	Response data
result.data.rating	array	Response data
result.data.rating_source	array	Response data
result.data.score	number	Response data
result.data.start_ts	number	Response data
result.data.untrusted	number	Response data
result.data.vid	array	Response data
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":10,"result":{"data":{"behavior_info":0,"detection_os":[],"false_positive_negative":[],"file_name":"eicar.zip","finish_ts":1752009625,"ftype":[],"infected_os":[],"jid":[],"malware_name":[],"now":1752187403,"pwd_extn":[],"rating":[],"rating_source":[],"score":1,"start_ts":1752009467},"status":{"code":0,"message":"OK"},"url":"/scan/result/file"},"ver":"5.0.0"}

Get Job Verdict

Retrieve the verdict of a job from Fortinet FortiSandbox using login credentials provided in the JSON body.

Endpoint

URL: /jsonrpc/scan/result/job

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use get for this action.
loginname.params	array	Optional	Request parameters for job verdict lookup.
loginname.params.jid	string	Optional	Job ID to retrieve verdict for.
loginname.params.url	string	Optional	Must be "/scan/result/job".
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"jid":"string","url":"https://example.com/api/resource"}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	object	Response data
result.data.category	string	Response data
result.data.detail_url	string	Response data
result.data.detection_os	string	Response data
result.data.download_url	string	Response data
result.data.false_positive_negative	number	Response data
result.data.file_name	string	Response data
result.data.finish_ts	number	Response data
result.data.ftype	string	Response data
result.data.infected_os	string	Response data
result.data.jid	string	Response data
result.data.malware_name	string	Response data
result.data.now	number	Response data
result.data.pwd_extn	number	Response data
result.data.rating	string	Response data
result.data.rating_source	string	Response data
result.data.score	number	Response data
result.data.sha1	string	Response data
result.data.sha256	string	Response data
result.data.start_ts	number	Response data
result.data.untrusted	number	Response data
result.data.vid	number	Response data
result.status	object	Status value

Output Example

{"id":15,"result":{"data":{"category":"NotApplicable","detail_url":"https://10.152.137.53/ng/new/job-detail?jid=7768513722233958359","detection_os":"['WIN7X86VMO16E']","download_url":"dGVzdC5wZGYK","false_positive_negative":0,"file_name":"test.pdf","finish_ts":1752187196,"ftype":"pdf","infected_os":"[]","jid":"7768513722233958359","malware_name":"N/A","now":1752187493,"pwd_extn":0,"rating":"Clean","rating_source":"Dynamic Scan"},"status":{"code":0,"message":"OK"},"url":"/scan/result/job"},"ver":...

Get PDF Report

Retrieve a detailed PDF scan report from Fortinet FortiSandbox using the JSON-RPC method for specified login credentials.

Endpoint

URL: /jsonrpc/scan/result/get-pdf-report

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use get for this action.
loginname.params	array	Optional	Request parameters for PDF report retrieval.
loginname.params.url	string	Optional	Must be "/scan/result/get-pdf-report".
loginname.params.qtype	string	Optional	Query by sha256 hash or jid.
loginname.params.qval	string	Optional	SHA256 hash or job ID value.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","qtype":"string","qval":"string"}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	object	Response data
result.data.report	string	Response data
result.data.report_name	string	Response data
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":50,"result":{"data":{"report":"U2FsdGVkX19t1sVVaklOIzwEM7nuAL(sample data)","report_name":"7765463547870976562.pdf"},"status":{"code":0,"message":"OK"},"url":"/scan/result/get-pdf-report"},"ver":"4.2.1"}

Get URL Rating

Retrieve the safety rating for a given URL from Fortinet FortiSandbox, requiring 'loginname' in the JSON body.

Endpoint

URL: /jsonrpc/scan/result/urlrating

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use get for this action.
loginname.params	array	Optional	Request parameters for URL rating lookup.
loginname.params.url	string	Optional	Must be "/scan/result/urlrating".
loginname.params.address	array	Optional	List of URLs to get ratings for.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","address":["string"]}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	array	Response data
result.data.behavior_info	number	Response data
result.data.finish_ts	number	Response data
result.data.now	number	Response data
result.data.rating	string	Response data
result.data.start_ts	number	Response data
result.data.untrusted	number	Response data
result.data.url	string	Response data
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":14,"result":{"data":[{}],"status":{"code":0,"message":"OK"},"url":"/scan/result/urlrating"},"ver":"2.5"}

Submission File Upload

Upload a file to Fortinet FortiSandbox for detailed sandbox analysis, requiring file data and login credentials.

Endpoint

URL: /jsonrpc/alert/ondemand/submit-file

Method: POST

Input

Argument Name	Type	Required	Description
file_data	array	Required	One or more files to submit for sandbox analysis.
file_data.file_name	string	Required	Display name for the uploaded file.
file_data.file	string	Required	File content (binary or base64).
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use set for this action.
loginname.params	array	Optional	Request parameters for file submission.
loginname.params.url	string	Optional	Must be "/alert/ondemand/submit-file".
loginname.params.type	string	Optional	Must be "file".
loginname.params.filename	string	Optional	Name of the file being submitted.
loginname.params.comments	string	Optional	Optional comments for the submission.
loginname.params.skip_steps	string	Optional	Comma-separated steps to skip.
loginname.params.enable_ai	boolean	Optional	Enable AI-based analysis.
loginname.params.forcedvm	boolean	Optional	Force use of specific VM.
loginname.params.overwrite_vm_list	string	Optional	Override default VM list.
loginname.params.vrecord	boolean	Optional	Record VM session video.
loginname.params.ret_cdr	number	Optional	Return CDR option.
loginname.params.file	string	Optional	Base64 file content.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"file_data":[{"file_name":"Example Name","file":"string"}],"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","type":"string","filename":"Example Name","comments":"string","skip_steps":"string","enable_ai":true,"forcedvm":true,"overwrite_vm_list":"string","vrecord":true,"ret_cdr":123,"file":"string"}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	object	Response data
result.data.sid	string	Response data
result.data.msg	string	Response data
result.data.error	string	Response data
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":11,"result":{"data":{"error":"","msg":"File was submitted successfully","sid":"7768513702245715053"},"status":{"code":0,"message":"OK"},"url":"/alert/ondemand/submit-file"},"ver":"5.0.3"}

Submission URL Upload

Submit one or more URLs to Fortinet FortiSandbox for comprehensive sandbox analysis. Parameters are encapsulated within the loginname.

Endpoint

URL: /jsonrpc/alert/ondemand/submit-file

Method: POST

Input

Argument Name	Type	Required	Description
loginname	object	Optional	All request parameters inside this object.
loginname.id	integer	Optional	JSON-RPC request identifier.
loginname.method	string	Optional	JSON-RPC method; use set for this action.
loginname.params	array	Optional	Request parameters for URL submission.
loginname.params.url	string	Optional	Must be "/alert/ondemand/submit-file".
loginname.params.type	string	Optional	Must be "url".
loginname.params.file	string	Optional	Base64 URLs content.
loginname.params.filename	string	Optional	Name for the URL list or report.
loginname.params.depth	number	Optional	Crawl depth for URL analysis.
loginname.params.timeout	number	Optional	Timeout in seconds for URL fetch.
loginname.session	string	Optional	Auth session token from login.
loginname.ver	string	Optional	FortiSandbox API version string.

Input Example

{"loginname":{"id":123,"method":"string","params":[{"url":"https://example.com/api/resource","type":"string","file":"string","filename":"Example Name","depth":123,"timeout":123}],"session":"string","ver":"string"}}

Output

Parameter	Type	Description
id	number	Unique identifier
result	object	Result of the operation
result.data	object	Response data
result.data.sid	string	Response data
result.data.msg	string	Response data
result.data.error	string	Response data
result.status	object	Status value
result.status.code	number	Status value
result.status.message	string	Status value
result.url	string	URL endpoint for the request
ver	string	Output field: ver

Output Example

{"id":12,"result":{"data":{"error":"","msg":"File was submitted successfully","sid":"7768516279030749916"},"status":{"code":0,"message":"OK"},"url":"/alert/ondemand/submit-file"},"ver":"2.0"}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT