Fortinet FortiSandbox

the fortinet fortisandbox connector allows for automated threat detection and analysis by interfacing with fortisandbox's sandboxing technology fortinet fortisandbox offers advanced threat detection by analyzing files and urls in a secure sandbox environment this connector enables swimlane turbine users to automate the submission of files and urls for analysis, retrieve detailed reports, and cancel submissions as needed by integrating with fortinet fortisandbox, users can enhance their security posture with automated sandboxing capabilities, streamline threat analysis workflows, and rapidly respond to potential threats with actionable intelligence 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 to effectively utilize the fortinet fortisandbox connector with swimlane turbine, ensure you have the following prerequisites http basic authentication with the following parameters url the endpoint url for the fortisandbox api username the username credential for fortisandbox access password the password credential for fortisandbox access 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/alert/ https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/1223/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/scan/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/alert/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/alert/ 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 https //fndn fortinet net/index php?/fortiapi/1221 fortisandbox/5285/1221/alert/ 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 cancels 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, utilizing 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 the provided login credentials within 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 parameters within the 'loginname' 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