Fortinet Document Library

Version:


Table of Contents

Hybrid Analysis

1.1.0
Copy Link

About the connector

Hybrid Analysis is malware analysis service for the community that detects and analyzes unknown threats using a unique Hybrid Analysis technology.

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

Version information

Connector Version: 1.1.0

FortiSOAR™ Version Tested on: 4.12.1-253

Hybrid Analysis Version Tested on: 2.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.1.0

The following enhancement has been made to the Hybrid Analysis connector in version 1.1.0:

The User Agent has been added in the header for each API request. This change is not visible on the UI, and it was made since the Hybrid Analysis API was updated.

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-hybrid-analysis

For the procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the URL of the Hybrid Analysis server to which you will connect and perform the automated operations.
  • You must have the API key used to access the Hybrid Analysis endpoint.
  • 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 Hybrid Analysis connector row, and in the Configure tab enter the required configuration details.

Parameter Description
Server URL URL of the Hybrid Analysis server to which you will connect and perform the automated operations.
API Key API key that is configured for your account to access the Hybrid Analysis endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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 Environment Retrieves all the sandbox information from the Hybrid Analysis server. get_environment
Investigation
Submit File Submits a file from the FortiSOAR™ Attachments module to the Hybrid Analysis server for analyzes. detonate_file
Investigation
Get Analysis Report Retrieves all the analysis details from the Hybrid Analysis server for a submitted file, based on the input parameters you specify. get_reputation
Investigation
Advanced Search Retrieves all the reports from the Hybrid Analysis server that match the input parameters you specify. search_query
Investigation
Get Files Dropped by Sample Retrieves all the details of the dropped file from the Hybrid Analysis server and adds the file to the FortiSOAR™ Attachments module. You specify the sample for which you want to retrieve dropped files, based on the input parameters you have specified. get_file
Investigation
Get Sample Screenshot Retrieves screenshots of specified submitted samples that are captured during analysis from the Hybrid Analysis server. You specify the sample for which you want to retrieve screenshots based on the input parameters you have specified. You can optionally also add the screenshots to the FortiSOAR™ Attachments module. get_sample_screenshots
Investigation
Get Submission State Retrieves the state of a submitted file from the Hybrid Analysis server, based on the input parameters you have specified. get_submitted_sample_state
Investigation
Get Multiple Analysis Reports Retrieves a list of reports from the Hybrid Analysis server, based on the number of days you have specified. get_feed
Investigation
Get API Limit Retrieves details of the API limit for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector. get_api_limit
Investigation
Get API Quota Retrieves details of the API quota for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector. get_api_quota
Investigation

operation: Get Environment

Input parameters

None

Output

The JSON output retrieves all the sandbox information from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "architecture": "",
     "description": "",
     "group_icon": "",
     "analysis_mode": "",
     "total_virtual_machines": "",
     "busy_virtual_machines": "",
     "virtual_machines": "",
     "id": ""
}

operation: Submit File

Input parameters

Note: To use this operation, you must submit files from the FortiSOAR™ 'Attachments' module only.

Parameter Description
File ID ID or IRI value of the file that you want to submit to the Hybrid Analysis server. The file ID or IRI is used to access the file in the 'Attachments' module of FortiSOAR™.
In the playbook, the value of the File ID field defaults to {{vars.attachment_id}} or {{vars.file_iri}}.
Environment ID ID of the environment in which the file is to to be run.
For example, 300: 'Linux (Ubuntu 16.04, 64 bit)', 200: 'Android Static Analysis’.
Available environment IDs are: 300: 'Linux (Ubuntu 16.04, 64 bit)', 200: 'Android Static Analysis’, 120: 'Windows 7 64 bit’, 110: 'Windows 7 32 bit (HWP Support)', or 100: ‘Windows 7 32 bit’.
Do Not Share with Third Party? If you select this option, i.e. set it to True; then this sample is not shared with any third-party.
By default, this is set to, True.
Do Not Lookup with Hash? If you select this option, i.e. set it to True; then this sample is not looked up using its hashvalue.
By default, this is set to, False.
Priority Priority value of the sample. By default, the Priority is set to, 0. You can set this value to any value between 0 and 100, which is the highest value.
Action Script (Optional) Select a custom runtime action script.
Available custom runtime action script are as follows: default, default_maxantievasion, default_randomfiles, default_randomtheme, or default_openie.
Required Memory Dump? If you select this option, i.e. set it to, True; then memory dumps, or memory analysis dumps will occur.
By default, this is set to, True.
Experimental Anti-Evasion? If you select this option, i.e. set it to, True; enables all the experimental anti-evasion options of the kernelmode Monitor.
By default, this is set to False
Set the IN-Depth Script Logging If you select this option, i.e. set it to, True; then this enables the in-depth script logging engine of the kernelmode Monitor.
By default, this is set to, False.
Allow Sample Tampering If you select this option, i.e. set it to, True; then this enables the experimental anti-evasion options of the kernelmode Monitor that tamper with the input sample.
By default, this is set to, False.
Enabled TOR Analysis? If you select this option, i.e. set it to, True; then the network traffic for the analysis is routed using TOR (if it is properly configured on the server.
By default, this is set to, True.
Offline Analysis If you select this option, i.e. set it to, True; then the outbound network traffic for the guest VM is disabled. The value that you set for this field takes precedence over the value that you have set for the 'Enabled TOR Analysis?' field, in case you have specified both the values.
By default, this is set to, False.
Email Notification (Optional) Email Address that is associated with the file that you have submitted for submission. This email address will be used for notification purposes.
Properties File with VxStream Directives (Optional) Properties that can be associated with the submitted file. Properties might contain VxStream internal directives, such as actionScript.
Comment (Optional) Comment that you want to add when submitting the file.
Custom Date Time for the Analysis System (Optional) Custom date and time that you can set for the analysis system.
Custom CMD Line Pass to the Analysis File (Optional) Custom command line that can be passed to the analysis file.
Custom Run Time (Optional) Runtime duration that you specify in seconds.
Submit Name (Optional) Name of the submitted file. The Submission Name field is used for file type detection and analysis.
Document Password (Optional) Password of the document that will be used to fill in Adobe or Office password prompts.
Environment Variable (Format name=value) (Optional) System environment value. You must provide this value in the name=value format.

Output

The JSON output retrieves details of the submitted file, such as the Job ID, sha256 value, and environment ID from the Hybrid Analysis server. You can use these details in future to query and retrieve scan reports from the Hybrid Analysis server for this file.

The output contains the following populated JSON schema:
{
     "environment_id": "",
     "sha256": "",
     "job_id": ""
}

operation: Get Analysis Report

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve a report from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve a report from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose report you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves all the analysis details for the specified file from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "vx_family": "",
     "type": "",
     "total_processes": "",
     "job_id": "",
     "submit_name": "",
     "size": "",
     "certificates": [],
     "sha256": "",
     "total_signatures": "",
     "state": "",
     "hosts": [],
     "environment_id": "",
     "compromised_hosts": "",
     "environment_description": "",
     "target_url": "",
     "verdict": "",
     "imphash": "",
     "url_analysis": "",
     "processes": [],
     "analysis_start_time": "",
     "classification_tags": [],
     "total_network_connections": "",
     "md5": "",
     "sha1": "",
     "ssdeep": "",
     "threat_level": "",
     "domains": "",
     "av_detect": "",
     "threat_score": "",
     "interesting": "",
     "extracted_files": [
         {
             "file_path": "",
             "av_label": "",
             "threat_level": "",
             "threat_level_readable": "",
             "file_size": "",
             "name": "",
             "av_total": "",
             "type_tags": [],
             "av_matched": "",
             "sha256": ""
         }
     ]
}

operation: Advanced Search

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then all reports will be retrieved from the Hybrid Analysis server.

Parameter Description
File Name (e.g., invoice.exe) Name of the file based on which you want to search for a report on the Hybrid Analysis server.
File Type (e.g., docx) Type of the file based on which you want to search for a report on the Hybrid Analysis server.
File Type Description (e.g., PE32 executable) Description of the file type based on which you want to search for a report on the Hybrid Analysis server.
Verdict Verdict of the Hybrid Analysis server after scanning the submitted file. Select one of the following as the verdict value: Whitelisted, No Verdict, No Specific Threat, Suspicious, or Malicious.
AV Multiscan range (e.g. 50-70 [min 0, max 100]) AV Multiscan range of the file based on which you want to search for a report on the Hybrid Analysis server.
AV Family Substring (e.g., nemucod) AV Family Substring of the file type based on which you want to search for a report on the Hybrid Analysis server.
Hash Tag (e.g., ransomware) Hash tag of the file based on which you want to search for a report on the Hybrid Analysis server.
Port (e.g., 8080) Port of the file based on which you want to search for a report on the Hybrid Analysis server.
Host (e.g., 192.168.0.1) Host of the file based on which you want to search for a report on the Hybrid Analysis server.
Domain (e.g., checkip.dyndns.org) Domain of the file based on which you want to search for a report on the Hybrid Analysis server.
HTTP Request Substring (e.g., google) HTTP Request Substring of the file based on which you want to search for a report on the Hybrid Analysis server.
Similar Samples (e.g., <sha256>) Samples that are similar to the submitted file that you want to search for a report on the Hybrid Analysis server. For example, files having a similar SHA value.
Sample Context (e.g., <sha256>) Samples that have a similar context to the submitted file that you want to search for a report on the Hybrid Analysis server.
IMP Hash IMP Hash of the file based on which you want to search for a report on the Hybrid Analysis server.
SS Deep SS Deep of the file based on which you want to search for a report on the Hybrid Analysis server.
Authentihash Authentihash of the file based on which you want to search for a report on the Hybrid Analysis server.

Output

The JSON output retrieves all the reports that match the input parameters you have specified, from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "verdict": "",
             "vx_family": "",
             "environment_id": "",
             "environment_description": "",
             "analysis_start_time": "",
             "submit_name": "",
             "sha256": "",
             "type_short": "",
             "size": "",
             "job_id": "",
             "av_detect": "",
             "threat_score": "",
             "type": ""
         }
     ],
     "search_terms": [
         {
             "value": "",
             "id": ""
         }
     ],
     "count": ""
}

operation: Get Files Dropped by Sample

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve details of the dropped file from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve details of the dropped file from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose details of the dropped file you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves all the details of the dropped file from the Hybrid Analysis server and adds the dropped file to the FortiSOAR™ Attachments module.

The output contains a non-dictionary value.

operation: Get Sample Screenshot

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve screenshots that are captured during analysis from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve screenshots that are captured during analysis from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose screenshots you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.
Attach Screenshots to CyOPs If you select this option, i.e. set it to True, then the sample screenshots are added to the FortiSOAR™ Attachments module.
By default, this is set to, False.

Output

The JSON output retrieves screenshots of the specified submitted sample that are captured during analysis from the Hybrid Analysis server. You specify the sample for which you want to retrieve screenshot based on the input parameters you have specified. You can optionally also add the screenshots to the FortiSOAR™ Attachments module.

The output contains a non-dictionary value.

operation: Get Submission State

Input parameters

Parameter Description
Job ID ID of the submitted file for which you want to retrieve the state information from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the submitted file for which you want to retrieve the state information from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose state information you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves the state of the submitted file from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "error": "",
     "state": ""
}

operation: Get Multiple Analysis Reports

Input parameters

Parameter Description
Days Number of days for which you want to retrieve reports from the Hybrid Analysis server.

Output

The JSON output retrieves a list of reports from the Hybrid Analysis server, based on the number of days you have specified.

The output contains the following populated JSON schema:
{
     "data": [
         {
             "size": "",
             "type": "",
             "threatlevel": "",
             "sharedanalysis": "",
             "environmentDescription": "",
             "analysis_start_time": "",
             "md5": "",
             "reporturl": "",
             "ms_detect": "",
             "avdetect": "",
             "isinteresting": "",
             "vt_detect": "",
             "isurlanalysis": "",
             "threatscore": "",
             "isunknown": "",
             "process_list": "",
             "threatlevel_human": "",
             "sha256": "",
             "environmentId": "",
             "submitname": "",
             "sha1": "",
             "isreliable": "",
             "extracted_files": []
         }
     ],
     "status": "",
     "count": ""
}

operation: Get API Limit

Input parameters

None

Output

The JSON output retrieves details of the API limit for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector.

The output contains the following populated JSON schema:
{
     "response_code": "",
     "response": {
         "used": {
             "hour": "",
             "minute": ""
         },
         "name_of_reached_limit": "",
         "limit_reached": "",
         "limits": {
             "hour": "",
             "minute": ""
         }
     }
}

operation: Get API Quota

Input parameters

None

Output

The JSON output retrieves details of the API quota for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector.

The output contains the following populated JSON schema:
{
     "response_code": "",
     "response": {
         "quota_reached": "",
         "apikey": {
             "quota_reached": "",
             "used": {
                 "hour": "",
                 "month": "",
                 "omega": "",
                 "day": "",
                 "week": ""
             },
             "quota": {
                 "day": ""
             },
             "available": {
                 "day": ""
             }
         },
         "total": {
             "quota_reached": ""
         }
     }
}

Included playbooks

The Sample - Hybrid Analysis - 1.1.0 playbook collection comes bundled with the Hybrid Analysis 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 Hybrid Analysis connector.

  • Advanced Search
  • Get Analysis Report
  • Get API Limit
  • Get API Quota
  • Get Environment
  • Get Files Dropped by Sample
  • Get Multiple Analysis Reports
  • Get Sample Screenshot
  • Get Submission State
  • Submit File

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

Hybrid Analysis is malware analysis service for the community that detects and analyzes unknown threats using a unique Hybrid Analysis technology.

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

Version information

Connector Version: 1.1.0

FortiSOAR™ Version Tested on: 4.12.1-253

Hybrid Analysis Version Tested on: 2.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.1.0

The following enhancement has been made to the Hybrid Analysis connector in version 1.1.0:

The User Agent has been added in the header for each API request. This change is not visible on the UI, and it was made since the Hybrid Analysis API was updated.

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-hybrid-analysis

For the 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 Hybrid Analysis connector row, and in the Configure tab enter the required configuration details.

Parameter Description
Server URL URL of the Hybrid Analysis server to which you will connect and perform the automated operations.
API Key API key that is configured for your account to access the Hybrid Analysis endpoint.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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 Environment Retrieves all the sandbox information from the Hybrid Analysis server. get_environment
Investigation
Submit File Submits a file from the FortiSOAR™ Attachments module to the Hybrid Analysis server for analyzes. detonate_file
Investigation
Get Analysis Report Retrieves all the analysis details from the Hybrid Analysis server for a submitted file, based on the input parameters you specify. get_reputation
Investigation
Advanced Search Retrieves all the reports from the Hybrid Analysis server that match the input parameters you specify. search_query
Investigation
Get Files Dropped by Sample Retrieves all the details of the dropped file from the Hybrid Analysis server and adds the file to the FortiSOAR™ Attachments module. You specify the sample for which you want to retrieve dropped files, based on the input parameters you have specified. get_file
Investigation
Get Sample Screenshot Retrieves screenshots of specified submitted samples that are captured during analysis from the Hybrid Analysis server. You specify the sample for which you want to retrieve screenshots based on the input parameters you have specified. You can optionally also add the screenshots to the FortiSOAR™ Attachments module. get_sample_screenshots
Investigation
Get Submission State Retrieves the state of a submitted file from the Hybrid Analysis server, based on the input parameters you have specified. get_submitted_sample_state
Investigation
Get Multiple Analysis Reports Retrieves a list of reports from the Hybrid Analysis server, based on the number of days you have specified. get_feed
Investigation
Get API Limit Retrieves details of the API limit for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector. get_api_limit
Investigation
Get API Quota Retrieves details of the API quota for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector. get_api_quota
Investigation

operation: Get Environment

Input parameters

None

Output

The JSON output retrieves all the sandbox information from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "architecture": "",
     "description": "",
     "group_icon": "",
     "analysis_mode": "",
     "total_virtual_machines": "",
     "busy_virtual_machines": "",
     "virtual_machines": "",
     "id": ""
}

operation: Submit File

Input parameters

Note: To use this operation, you must submit files from the FortiSOAR™ 'Attachments' module only.

Parameter Description
File ID ID or IRI value of the file that you want to submit to the Hybrid Analysis server. The file ID or IRI is used to access the file in the 'Attachments' module of FortiSOAR™.
In the playbook, the value of the File ID field defaults to {{vars.attachment_id}} or {{vars.file_iri}}.
Environment ID ID of the environment in which the file is to to be run.
For example, 300: 'Linux (Ubuntu 16.04, 64 bit)', 200: 'Android Static Analysis’.
Available environment IDs are: 300: 'Linux (Ubuntu 16.04, 64 bit)', 200: 'Android Static Analysis’, 120: 'Windows 7 64 bit’, 110: 'Windows 7 32 bit (HWP Support)', or 100: ‘Windows 7 32 bit’.
Do Not Share with Third Party? If you select this option, i.e. set it to True; then this sample is not shared with any third-party.
By default, this is set to, True.
Do Not Lookup with Hash? If you select this option, i.e. set it to True; then this sample is not looked up using its hashvalue.
By default, this is set to, False.
Priority Priority value of the sample. By default, the Priority is set to, 0. You can set this value to any value between 0 and 100, which is the highest value.
Action Script (Optional) Select a custom runtime action script.
Available custom runtime action script are as follows: default, default_maxantievasion, default_randomfiles, default_randomtheme, or default_openie.
Required Memory Dump? If you select this option, i.e. set it to, True; then memory dumps, or memory analysis dumps will occur.
By default, this is set to, True.
Experimental Anti-Evasion? If you select this option, i.e. set it to, True; enables all the experimental anti-evasion options of the kernelmode Monitor.
By default, this is set to False
Set the IN-Depth Script Logging If you select this option, i.e. set it to, True; then this enables the in-depth script logging engine of the kernelmode Monitor.
By default, this is set to, False.
Allow Sample Tampering If you select this option, i.e. set it to, True; then this enables the experimental anti-evasion options of the kernelmode Monitor that tamper with the input sample.
By default, this is set to, False.
Enabled TOR Analysis? If you select this option, i.e. set it to, True; then the network traffic for the analysis is routed using TOR (if it is properly configured on the server.
By default, this is set to, True.
Offline Analysis If you select this option, i.e. set it to, True; then the outbound network traffic for the guest VM is disabled. The value that you set for this field takes precedence over the value that you have set for the 'Enabled TOR Analysis?' field, in case you have specified both the values.
By default, this is set to, False.
Email Notification (Optional) Email Address that is associated with the file that you have submitted for submission. This email address will be used for notification purposes.
Properties File with VxStream Directives (Optional) Properties that can be associated with the submitted file. Properties might contain VxStream internal directives, such as actionScript.
Comment (Optional) Comment that you want to add when submitting the file.
Custom Date Time for the Analysis System (Optional) Custom date and time that you can set for the analysis system.
Custom CMD Line Pass to the Analysis File (Optional) Custom command line that can be passed to the analysis file.
Custom Run Time (Optional) Runtime duration that you specify in seconds.
Submit Name (Optional) Name of the submitted file. The Submission Name field is used for file type detection and analysis.
Document Password (Optional) Password of the document that will be used to fill in Adobe or Office password prompts.
Environment Variable (Format name=value) (Optional) System environment value. You must provide this value in the name=value format.

Output

The JSON output retrieves details of the submitted file, such as the Job ID, sha256 value, and environment ID from the Hybrid Analysis server. You can use these details in future to query and retrieve scan reports from the Hybrid Analysis server for this file.

The output contains the following populated JSON schema:
{
     "environment_id": "",
     "sha256": "",
     "job_id": ""
}

operation: Get Analysis Report

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve a report from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve a report from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose report you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves all the analysis details for the specified file from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "vx_family": "",
     "type": "",
     "total_processes": "",
     "job_id": "",
     "submit_name": "",
     "size": "",
     "certificates": [],
     "sha256": "",
     "total_signatures": "",
     "state": "",
     "hosts": [],
     "environment_id": "",
     "compromised_hosts": "",
     "environment_description": "",
     "target_url": "",
     "verdict": "",
     "imphash": "",
     "url_analysis": "",
     "processes": [],
     "analysis_start_time": "",
     "classification_tags": [],
     "total_network_connections": "",
     "md5": "",
     "sha1": "",
     "ssdeep": "",
     "threat_level": "",
     "domains": "",
     "av_detect": "",
     "threat_score": "",
     "interesting": "",
     "extracted_files": [
         {
             "file_path": "",
             "av_label": "",
             "threat_level": "",
             "threat_level_readable": "",
             "file_size": "",
             "name": "",
             "av_total": "",
             "type_tags": [],
             "av_matched": "",
             "sha256": ""
         }
     ]
}

operation: Advanced Search

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then all reports will be retrieved from the Hybrid Analysis server.

Parameter Description
File Name (e.g., invoice.exe) Name of the file based on which you want to search for a report on the Hybrid Analysis server.
File Type (e.g., docx) Type of the file based on which you want to search for a report on the Hybrid Analysis server.
File Type Description (e.g., PE32 executable) Description of the file type based on which you want to search for a report on the Hybrid Analysis server.
Verdict Verdict of the Hybrid Analysis server after scanning the submitted file. Select one of the following as the verdict value: Whitelisted, No Verdict, No Specific Threat, Suspicious, or Malicious.
AV Multiscan range (e.g. 50-70 [min 0, max 100]) AV Multiscan range of the file based on which you want to search for a report on the Hybrid Analysis server.
AV Family Substring (e.g., nemucod) AV Family Substring of the file type based on which you want to search for a report on the Hybrid Analysis server.
Hash Tag (e.g., ransomware) Hash tag of the file based on which you want to search for a report on the Hybrid Analysis server.
Port (e.g., 8080) Port of the file based on which you want to search for a report on the Hybrid Analysis server.
Host (e.g., 192.168.0.1) Host of the file based on which you want to search for a report on the Hybrid Analysis server.
Domain (e.g., checkip.dyndns.org) Domain of the file based on which you want to search for a report on the Hybrid Analysis server.
HTTP Request Substring (e.g., google) HTTP Request Substring of the file based on which you want to search for a report on the Hybrid Analysis server.
Similar Samples (e.g., <sha256>) Samples that are similar to the submitted file that you want to search for a report on the Hybrid Analysis server. For example, files having a similar SHA value.
Sample Context (e.g., <sha256>) Samples that have a similar context to the submitted file that you want to search for a report on the Hybrid Analysis server.
IMP Hash IMP Hash of the file based on which you want to search for a report on the Hybrid Analysis server.
SS Deep SS Deep of the file based on which you want to search for a report on the Hybrid Analysis server.
Authentihash Authentihash of the file based on which you want to search for a report on the Hybrid Analysis server.

Output

The JSON output retrieves all the reports that match the input parameters you have specified, from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "result": [
         {
             "verdict": "",
             "vx_family": "",
             "environment_id": "",
             "environment_description": "",
             "analysis_start_time": "",
             "submit_name": "",
             "sha256": "",
             "type_short": "",
             "size": "",
             "job_id": "",
             "av_detect": "",
             "threat_score": "",
             "type": ""
         }
     ],
     "search_terms": [
         {
             "value": "",
             "id": ""
         }
     ],
     "count": ""
}

operation: Get Files Dropped by Sample

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve details of the dropped file from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve details of the dropped file from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose details of the dropped file you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves all the details of the dropped file from the Hybrid Analysis server and adds the dropped file to the FortiSOAR™ Attachments module.

The output contains a non-dictionary value.

operation: Get Sample Screenshot

Input parameters

Parameter Description
Job ID ID of the file for which you want to retrieve screenshots that are captured during analysis from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the file for which you want to retrieve screenshots that are captured during analysis from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose screenshots you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.
Attach Screenshots to CyOPs If you select this option, i.e. set it to True, then the sample screenshots are added to the FortiSOAR™ Attachments module.
By default, this is set to, False.

Output

The JSON output retrieves screenshots of the specified submitted sample that are captured during analysis from the Hybrid Analysis server. You specify the sample for which you want to retrieve screenshot based on the input parameters you have specified. You can optionally also add the screenshots to the FortiSOAR™ Attachments module.

The output contains a non-dictionary value.

operation: Get Submission State

Input parameters

Parameter Description
Job ID ID of the submitted file for which you want to retrieve the state information from the Hybrid Analysis server. You can get the job ID when you submit a sample file.
Note: If you specify the Job ID you do not require to specify File SHA256 or the environment ID.
File SHA256 SHA256 value of the submitted file for which you want to retrieve the state information from the Hybrid Analysis server. You can get the SHA256 value when you submit a sample file.
Note: If you specify File SHA256, then you must specify the Environment ID.
Environment ID ID of the environment on which the submitted file is to be run, whose state information you want to retrieve from the Hybrid Analysis server. You can get the Environment ID when you submit a sample file.
Note: If you specify Environment ID, then you must specify the File SHA256.

Output

The JSON output retrieves the state of the submitted file from the Hybrid Analysis server.

The output contains the following populated JSON schema:
{
     "error": "",
     "state": ""
}

operation: Get Multiple Analysis Reports

Input parameters

Parameter Description
Days Number of days for which you want to retrieve reports from the Hybrid Analysis server.

Output

The JSON output retrieves a list of reports from the Hybrid Analysis server, based on the number of days you have specified.

The output contains the following populated JSON schema:
{
     "data": [
         {
             "size": "",
             "type": "",
             "threatlevel": "",
             "sharedanalysis": "",
             "environmentDescription": "",
             "analysis_start_time": "",
             "md5": "",
             "reporturl": "",
             "ms_detect": "",
             "avdetect": "",
             "isinteresting": "",
             "vt_detect": "",
             "isurlanalysis": "",
             "threatscore": "",
             "isunknown": "",
             "process_list": "",
             "threatlevel_human": "",
             "sha256": "",
             "environmentId": "",
             "submitname": "",
             "sha1": "",
             "isreliable": "",
             "extracted_files": []
         }
     ],
     "status": "",
     "count": ""
}

operation: Get API Limit

Input parameters

None

Output

The JSON output retrieves details of the API limit for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector.

The output contains the following populated JSON schema:
{
     "response_code": "",
     "response": {
         "used": {
             "hour": "",
             "minute": ""
         },
         "name_of_reached_limit": "",
         "limit_reached": "",
         "limits": {
             "hour": "",
             "minute": ""
         }
     }
}

operation: Get API Quota

Input parameters

None

Output

The JSON output retrieves details of the API quota for the specified user account from the Hybrid Analysis server. You specify the user account when you are configuring the Hybrid Analysis connector.

The output contains the following populated JSON schema:
{
     "response_code": "",
     "response": {
         "quota_reached": "",
         "apikey": {
             "quota_reached": "",
             "used": {
                 "hour": "",
                 "month": "",
                 "omega": "",
                 "day": "",
                 "week": ""
             },
             "quota": {
                 "day": ""
             },
             "available": {
                 "day": ""
             }
         },
         "total": {
             "quota_reached": ""
         }
     }
}

Included playbooks

The Sample - Hybrid Analysis - 1.1.0 playbook collection comes bundled with the Hybrid Analysis 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 Hybrid Analysis 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.