Hybrid Analysis v2.0.0

About the connector

Hybrid Analysis is a 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 analysis, searching the Hybrid Analysis server for reports based on specific parameters, and retrieving reports from the Hybrid Analysis server.

Version information

Connector Version: 2.0.0

Authored By: Community

Certified: No

Release Notes for version 2.0.0

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

• Added the following new operations and playbooks:
  • Get Analysis Report for Multiple Hashcodes
  • Submit URL
  • Quick Scan URL
• Updated the "File ID" parameter with the "Attachment ID" parameter for the "Submit File" operation.
• Removed the "Get API Limit" operation.
• Updated the Output Schema for all the operations.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:

yum install cyops-connector-hybrid-analysis

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.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the Hybrid Analysis server.

Minimum Permissions Required

• Not applicable

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.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations:

Function	Description	Annotation and Category
Get Analysis Report for Multiple Hashcodes	Retrieves the analysis report summary from the Hybrid Analysis server for multiple MD5/SHA1/SHA256 hash codes you have specified	hashes_search Investigation
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 analysis.	detonate_file Investigation
Submit URL	Submits a URL to the Hybrid Analysis server for analysis.	submit_url Investigation
Quick Scan URL	Submits a URL to the Hybrid Analysis server for a Quick Scan. You can query the Hybrid Analysis server again, in a few minutes, to check the results of the scan.	url_quick_scan 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 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 Analysis Report for Multiple Hashcodes

Input parameters

Parameter	Description
Hash Codes	Specify the hash codes in the MD5, SHA256, or SHA1 format whose summary you want to retrieve from the Hybrid Analysis server. You can specify multiple codes in the CSV format.

Output

The output contains the following populated JSON schema:
{
"job_id": "",
"environment_id": "",
"environment_description": "",
"size": "",
"type": "",
"type_short": [],
"target_url": "",
"state": "",
"error_type": "",
"error_origin": "",
"submit_name": "",
"md5": "",
"sha1": "",
"sha256": "",
"sha512": "",
"ssdeep": "",
"imphash": "",
"av_detect": "",
"vx_family": "",
"url_analysis": "",
"analysis_start_time": "",
"threat_score": "",
"interesting": "",
"threat_level": "",
"verdict": "",
"certificates": [],
"domains": [],
"classification_tags": [],
"compromised_hosts": [],
"hosts": [],
"total_network_connections": "",
"total_processes": "",
"total_signatures": "",
"extracted_files": [],
"file_metadata": "",
"processes": [],
"tags": [],
"mitre_attcks": [],
"submissions": [
{
"submission_id": "",
"filename": "",
"url": "",
"created_at": ""
}
],
"network_mode": "",
"machine_learning_models": []
}

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:
{
"id": "",
"environment_id": "",
"description": "",
"group_icon": "",
"architecture": "",
"analysis_mode": "",
"virtual_machines": [],
"total_virtual_machines": "",
"busy_virtual_machines": "",
"invalid_virtual_machines": ""
}

operation: Submit File

Input parameters

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

Parameter	Description
Attachment ID	The ID of the file that you want to submit to the Hybrid Analysis server. The file ID is used to access the file from the 'Attachments' module of FortiSOAR™. In the playbook, the value of the attachment ID field defaults to {{vars.attachment_id}}
Environment ID	The ID of the environment in which the file is 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 hash value. By default, this is set to, False.
Priority	The 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) Specify the email addresses that are associated with the file that you have submitted for analysis. 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) A comment that you want to add when submitting the file.
Custom Date Time for the Analysis System	(Optional) The Custom date and time that you can set for the analysis system.
Custom CMD Line Pass to the Analysis File	(Optional) The custom command line that you want to pass to the analysis file.
Custom Run Time	(Optional) The runtime duration that you can specify in seconds.
Submit Name	(Optional) The name of the submitted file. The Submission Name field is used for file type detection and analysis.
Document Password	(Optional) The password of the document is used to fill in Adobe or Office password prompts.
Environment Variable (Format name=value)	(Optional) The 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 the future to query and retrieve scan reports from the Hybrid Analysis server for this file.

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

operation: Submit URL

Input parameters

Parameter	Description
URL	Specify the URL that you want to submit to the Hybrid Analysis server.
Environment ID	The ID of the environment in which the URL is 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 URL is not shared with any third party. By default, this is set to, False.
Do Not Lookup with Hash?	If you select this option, i.e. set it to True; then this sample URL is not looked up using its hash value. By default, this is set to, False.
Priority	(Optional) The priority value of the sample URL. By default, all URL samples are set to run with the highest priority i.e., 100. You can set this value to any value between 1 (lowest) and 100(highest).
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.
Email Notification	(Optional) Specify the email addresses that are associated with the URL that you have submitted for analysis. This email address will be used for notification purposes.
Comment	(Optional) A comment that you want to add when submitting the URL. Note: You can use #tags while entering comments.
Custom Date Time for the Analysis System	(Optional) The Custom date and time that you can set for the analysis system.
Custom Run Time	(Optional) The runtime duration that you can specify in seconds.
Environment Variable (Format name=value)	(Optional) The system environment value. You must provide this value in the name=value format.

Output

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

operation: Quick Scan URL

Input parameters

Parameter	Description
URL	Specify the URL that you want to submit to the Hybrid Analysis server for a quick scan.
Do Not Share with Third Party?	If you select this option, i.e. set it to True; then this sample URL is not shared with any third party. By default, this is set to, False.
Allow Community Access?	If you select this option, i.e. set it to True; then this sample URL is available for the community. By default, this is set to, True. Note: When the 'Do Not Share with Third Party?' option is set to 'False', then this option must be set as True, i.e., it is not possible to set a value other than 'True'.

Output

The output contains the following populated JSON schema:
{
"submission_type": "",
"id": "",
"sha256": "",
"scanners": [
{
"name": "",
"status": "",
"error_message": "",
"progress": "",
"total": "",
"positives": "",
"percent": "",
"anti_virus_results": []
}
],
"whitelist": [],
"reports": [],
"finished": ""
}

operation: Get Analysis Report

Input parameters

Parameter	Description
Job ID	The 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	The 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:
{
"job_id": "",
"environment_id": "",
"environment_description": "",
"size": "",
"type": "",
"type_short": [],
"target_url": "",
"state": "",
"error_type": "",
"error_origin": "",
"submit_name": "",
"md5": "",
"sha1": "",
"sha256": "",
"sha512": "",
"ssdeep": "",
"imphash": "",
"av_detect": "",
"vx_family": "",
"url_analysis": "",
"analysis_start_time": "",
"threat_score": "",
"interesting": "",
"threat_level": "",
"verdict": "",
"certificates": [],
"domains": [],
"classification_tags": [],
"compromised_hosts": [],
"hosts": [],
"total_network_connections": "",
"total_processes": "",
"total_signatures": "",
"extracted_files": [],
"file_metadata": "",
"processes": [
{
"uid": "",
"parentuid": "",
"name": "",
"normalized_path": "",
"command_line": "",
"sha256": "",
"av_label": "",
"av_matched": "",
"av_total": "",
"pid": "",
"icon": "",
"file_accesses": [],
"created_files": [],
"registry": [],
"mutants": [],
"handles": [],
"streams": [],
"script_calls": [],
"process_flags": []
}
],
"tags": [],
"mitre_attcks": [],
"submissions": [
{
"submission_id": "",
"filename": "",
"url": "",
"created_at": ""
}
],
"network_mode": "",
"machine_learning_models": []
}

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)	The 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 that have 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:
{
"count": "",
"result": [
{
"vx_family": "",
"verdict": "",
"submit_name": "",
"type_short": "",
"job_id": "",
"analysis_start_time": "",
"environment_description": "",
"threat_score": "",
"av_detect": "",
"sha256": "",
"environment_id": "",
"size": "",
"type": ""
}
],
"search_terms": [
{
"id": "",
"value": ""
}
]
}

operation: Get Files Dropped by Sample

Input parameters

Parameter	Description
Job ID	The 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	The 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 the following populated JSON schema:
{
"id": "",
"@id": "",
"file": {
"id": "",
"@id": "",
"size": "",
"uuid": "",
"@type": "",
"assignee": "",
"filename": "",
"metadata": [],
"mimeType": "",
"thumbnail": "",
"uploadDate": ""
},
"name": "",
"type": "",
"uuid": "",
"@type": "",
"@context": "",
"assignee": "",
"createDate": "",
"createUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"modifyDate": "",
"modifyUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"recordTags": [],
"description": ""
}

operation: Get Sample Screenshot

Input parameters

Parameter	Description
Job ID	The 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	The 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 screenshots based on the input parameters you have specified. You can optionally also add the screenshots to the FortiSOAR™ Attachments module.

The output contains the following populated JSON schema:
{
"name": "",
"image": "",
"date": ""
}

operation: Get Submission State

Input parameters

Parameter	Description
Job ID	The 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	The 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:
{
"state": "",
"error_type": "",
"error_origin": "",
"error": "",
"related_reports": []
}

operation: Get Latest Analysis Reports

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"count": "",
"status": "",
"data": [
{
"job_id": "",
"md5": "",
"sha1": "",
"sha256": "",
"interesting": "",
"analysis_start_time": "",
"threat_score": "",
"threat_level": "",
"threat_level_human": "",
"av_detect": "",
"unknown": "",
"submit_name": "",
"url_analysis": "",
"size": "",
"type": "",
"environment_id": "",
"environment_description": "",
"shared_analysis": "",
"reliable": "",
"report_url": "",
"vt_detect": "",
"ms_detect": "",
"processes": [
{
"uid": "",
"name": "",
"normalized_path": "",
"command_line": "",
"sha256": ""
}
],
"ssdeep": ""
}
]
}

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:
{
"detonation": {
"total": "",
"apikey": {
"quota": {
"hour": "",
"day": "",
"week": "",
"month": "",
"year": "",
"omega": ""
},
"used": {
"hour": "",
"day": "",
"week": "",
"month": "",
"year": "",
"omega": ""
},
"available": {
"hour": "",
"day": "",
"week": "",
"month": "",
"year": "",
"omega": ""
},
"quota_reached": ""
},
"quota_reached": ""
},
"quick_scan": {
"total": "",
"apikey": "",
"quota_reached": ""
}
}

Included playbooks

The Sample - Hybrid Analysis - 2.0.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 API Quota
• Get Analysis Report
• Get Analysis Report for Multiple Hashcodes
• Get Environment
• Get Files Dropped by Sample
• Get Multiple Analysis Reports
• Get Sample Screenshot
• Get Submission State
• Quick Scan URL
• Submit File
• Submit URL

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.