VirusTotal Premium v1.0.0

About the connector

VirusTotal Premium Services are used to obtain additional threat context and expose advanced threat hunting and malware discovery endpoints and functionality.

This document provides information about the VirusTotal Premium Connector, which facilitates automated interactions, with a VirusTotal Premium server using FortiSOAR™ playbooks. Add the VirusTotal Premium connector as a step in FortiSOAR™ playbooks and perform automated operations such as searching for files in VirusTotal, retrieving information for specific ZIP files from VirusTotal, downloading VirustTotal report for a specified file from VirusTotal, etc.

The VirusTotal Premium playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for indicator types IP Address, File Hash, URL, and Domain. For more information, see Pluggable Enrichment.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.2.2-1098

VirusTotal Premium Version Tested on: 3.0

Authored By: Fortinet

Certified: Yes

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-virustotal-premium

Prerequisites to configuring the connector

• You must have the URL of the VirusTotal Premium server to which you will connect and perform automated operations and the API key that is configured for your account to access that server.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the VirusTotal Premium server.

Minimum Permissions Required

• Not Applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the VirusTotal Premium connector card. On the connector popup, click the Configurations tab to enter the required configuration details:

Parameter	Description
Server	Specify the server URL of the VirusTotal Premium server to which you will connect and perform the automated operations.
API Key	Specify the API key that is configured for your account to access the VirusTotal premium server.
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:

Function	Description	Annotation and Category
Download File	Downloads VirustTotal report for a specified file from VirusTotal based on the hash value of the file you have specified.	download_file Investigation
Create ZIP File	Creates a password-protected ZIP file with the VirusTotal files based on the hash values of the VirusTotal files and the password you have specified.	create_zip_file Investigation
Get ZIP File Status	Retrieves information of the ZIP file from VirusTotal based on the zip file ID you have specified.	get_zip_file_status Investigation
Get ZIP File URL	Retrieves a signed URL from where you can download the specified ZIP file from VirusTotal based on the zip file ID you have specified. Note: The retrieved URL expires after 1 hour.	get_zip_file_url Investigation
Download ZIP File	Downloads a zip file from VirusTotal based on the zip file ID you have specified.	download_zip_file Investigation
Get PCAP File Behaviour	Retrieves a PCAP file from VirusTotal based on the report ID you have specified. A PCAP file is generated while analyzing the file’s behavior in VirusTotal.	get_pcap_file_behaviour Investigation
Search Intelligence	Searches for files in VirusTotal using the query and other input parameters you have specified.	search_intelligence Investigation
Create Livehunt Ruleset	Creates a livehunt ruleset in VirusTotal based on the ruleset name, rules, and other input parameters that you have specified.	create_livehunt_ruleset Investigation
Get Livehunt Rulesets List	Retrieves a list of livehunt rulesets from VirusTotal based on the filter and other input parameters that you have specified.	get_livehunt_rulesets_list Investigation
Get Livehunt Ruleset Details	Retrieves details for a specific livehunt ruleset from VirusTotal based on the ruleset ID you have specified.	get_livehunt_ruleset_details Investigation
Update Livehunt Ruleset	Updates a specific hunting livehunt ruleset in VirusTotal based on the ruleset id, ruleset name, rules, and other input parameters that you have specified.	update_livehunt_ruleset Investigation
Delete Livehunt Ruleset	Deletes a specific livehunt ruleset from VirusTotal based on the ruleset ID you have specified.	delete_livehunt_ruleset Investigation
Get Livehunt Notifications List	Retrieves a list of all livehunt notifications from VirusTotal based on the filter and other input parameters that you have specified.	get_livehunt_notifications_list Investigation
Get Livehunt Notifications Files List	Retrieves a list of all file objects for livehunt notifications from VirusTotal based on the filter and other input parameters that you have specified.	get_livehunt_notifications_files_list Investigation
Get Livehunt Notifications Details	Retrieves details for a specific livehunt notification from VirusTotal based on the notification ID you have specified.	get_livehunt_notifications_details Investigation
Get Livehunt Rule Files List	Retrieves a hunting livehunt ruleset from VirusTotal by hunting notification files relationship in VirusTotal based on the ruleset ID and other input parameters that you have specified.	get_livehunt_rule_files_list Investigation
Create Retrohunt Job	Creates a Retrohunt job in VirusTotal based on the rules, and other input parameters that you have specified.	create_retrohunt_job Investigation
Abort Retrohunt Job	Aborts a specific Retrohunt job in VirusTotal based on the job ID you have specified.	abort_retrohunt_job Investigation
Get Retrohunt jobs List	Retrieves a list of all Retrohunt jobs from VirusTotal based on the filter and other input parameters that you have specified.	get_retrohunt_jobs_list Investigation
Get Retrohunt Job Details	Retrieves details for a specific Retrohunt job from VirusTotal based on the job ID you have specified.	get_retrohunt_job_details Investigation
Get Retrohunt Job Matching Files	Retrieves a list of all Retrohunt job matching files from VirusTotal.	get_retrohunt_job_matching_files Investigation
Delete Retrohunt Job	Deletes a specific Retrohunt job from VirusTotal based on the Retrohunt job ID you have specified.	delete_retrohunt_job Investigation

operation: Download File

Input parameters

Parameter	Description
Hash Value	Specify the SHA-256, SHA-1, or MD5 of the file for which you want to retrieve a VirusTotal report.

Output

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": "",
"tasks": [],
"alerts": [],
"assets": [],
"owners": [],
"people": [],
"@context": "",
"assignee": "",
"comments": [],
"warrooms": [],
"incidents": [],
"createDate": "",
"createUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"indicators": [],
"modifyDate": "",
"modifyUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"recordTags": [],
"userOwners": [],
"description": ""
}

operation: Create ZIP File

Input parameters

Parameter	Description
Hashes	Specify the list of comma-separated hash values of the files based on which you want to create a zip file in VirusTotal.
Password	(Optional) Specify the password for protecting the ZIP file that is being created with VirusTotal files.

Output

The output contains the following populated JSON schema:
{
"type": "",
"id": "",
"attributes": {
"status": "",
"progress": "",
"files_ok": "",
"files_error": ""
}
}

operation: Get ZIP File Status

Input parameters

Parameter	Description
ZIP File ID	Specify the file identifier of the ZIP file for which you want to retrieve the zip file information from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"type": "",
"id": "",
"attributes": {
"status": "",
"progress": "",
"files_ok": "",
"files_error": ""
}
}

operation: Get ZIP File URL

Input parameters

Parameter	Description
ZIP File ID	Specify the file identifier of the ZIP file for which you want to retrieve a signed URL from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"url": ""
}

operation: Download ZIP File

Input parameters

Parameter	Description
ZIP File ID	Specify the file identifier of the ZIP file that you want to download from VirusTotal

Output

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": "",
"tasks": [],
"alerts": [],
"assets": [],
"owners": [],
"people": [],
"@context": "",
"assignee": "",
"comments": [],
"warrooms": [],
"incidents": [],
"createDate": "",
"createUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"indicators": [],
"modifyDate": "",
"modifyUser": {
"id": "",
"@id": "",
"name": "",
"uuid": "",
"@type": "",
"avatar": "",
"userId": "",
"userType": "",
"createDate": "",
"createUser": "",
"modifyDate": "",
"modifyUser": ""
},
"recordTags": [],
"userOwners": [],
"description": ""
}

operation: Get PCAP File Behaviour

Input parameters

Parameter	Description
Report ID	Specify the Report ID of the sandbox from which you want to retrieve the PCAP file from VirusTotal. A PCAP file is generated while analyzing the file’s behavior in VirusTotal.

Output

The output contains a non-dictionary value.

operation: Search Intelligence

Input parameters

Parameter	Description
Query	Specify a query in the key: value pair using which you want to search files in VirusTotal. For example, content: "hello World"
Order By	(Optional) Specify the order in which you want to sort the results retrieved from VirusTotal. Note: If your 'Query' parameter contains content search, then the 'Order' parameter does not have any effect.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Descriptors Only	(Optional) Select this option to return the full object information. Clear this option (default) to return just the object descriptors.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"meta": {
"cursor": "",
"days_back": ""
},
"data": [
{
"attributes": {
"type_description": "",
"tlsh": "",
"vhash": "",
"exiftool": {
"ZipRequiredVersion": "",
"MIMEType": "",
"ZipCRC": "",
"FileType": "",
"ZipCompression": "",
"ZipUncompressedSize": "",
"ZipCompressedSize": "",
"FileTypeExtension": "",
"ZipFileName": "",
"ZipBitFlag": "",
"ZipModifyDate": ""
},
"trid": [
{
"file_type": "",
"probability": ""
}
],
"crowdsourced_yara_results": [
{
"description": "",
"source": "",
"author": "",
"ruleset_name": "",
"rule_name": "",
"ruleset_id": ""
}
],
"names": [],
"last_modification_date": "",
"type_tag": "",
"times_submitted": "",
"total_votes": {
"harmless": "",
"malicious": ""
},
"size": "",
"type_extension": "",
"last_submission_date": "",
"last_analysis_results": {},
"downloadable": "",
"sha256": "",
"tags": [],
"last_analysis_date": "",
"unique_sources": "",
"first_submission_date": "",
"sha1": "",
"ssdeep": "",
"bundle_info": {
"highest_datetime": "",
"lowest_datetime": "",
"num_children": "",
"extensions": {
"dex": "",
"xml": "",
"MF": "",
"png": "",
"zip": "",
"RSA": "",
"jpg": "",
"swf": "",
"dat": "",
"so": "",
"mp3": "",
"ttf": "",
"ogg": "",
"txt": "",
"sg": "",
"SF": "",
"pbk": "",
"pbj": ""
},
"file_types": {
"XML": "",
"DEX": "",
"ZIP": "",
"unknown": "",
"ELF": "",
"JPG": "",
"MP3": "",
"OGG": "",
"PNG": ""
},
"type": "",
"uncompressed_size": ""
},
"md5": "",
"androguard": {
"VTAndroidInfo": "",
"Libraries": [],
"AndroidApplicationError": "",
"MinSdkVersion": "",
"AndroguardVersion": "",
"Activities": [],
"certificate": {
"Subject": {
"DN": "",
"CN": ""
},
"validto": "",
"serialnumber": "",
"thumbprint": "",
"validfrom": "",
"Issuer": {
"DN": "",
"CN": ""
}
},
"AndroidApplication": "",
"RiskIndicator": {
"APK": {
"SHARED LIBRARIES": ""
},
"PERM": {
"DANGEROUS": "",
"INTERNET": "",
"INSTANT": "",
"NORMAL": ""
}
},
"Services": [],
"AndroidVersionCode": "",
"main_activity": "",
"Package": "",
"intent_filters": {},
"AndroidVersionName": "",
"TargetSdkVersion": "",
"AndroidApplicationInfo": "",
"Providers": [],
"permission_details": {},
"Receivers": [],
"StringsInformation": []
},
"magic": "",
"last_analysis_stats": {
"harmless": "",
"type-unsupported": "",
"suspicious": "",
"confirmed-timeout": "",
"timeout": "",
"failure": "",
"malicious": "",
"undetected": ""
},
"meaningful_name": "",
"reputation": ""
},
"type": "",
"id": "",
"links": {
"self": ""
},
"context_attributes": {
"snippet": "",
"confidence": "",
"match_in_subfile": ""
}
}
],
"links": {
"self": "",
"next": ""
}
}

operation: Create Livehunt Ruleset

Input parameters

Parameter	Description
Ruleset Name	Specify the name of the hunting livehunt ruleset that you want to create in VirusTotal.
Rules	Specify the rules based on which you want to create the hunting livehunt ruleset in VirustTotal.
Enabled	(Optional) Select this option (default) to 'enable' the livehunt ruleset that you want to create in VirusTotal.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 100.
Notification Emails	(Optional) Specify the list of comma-separated notifications emails using which you want to create the livehunt ruleset in VirusTotal.

Output

The output contains the following populated JSON schema:
{
"attributes": {
"name": "",
"modification_date": "",
"rules": "",
"enabled": "",
"rate_limited": "",
"creation_date": "",
"rule_names": [],
"limit": "",
"rate_limited_ratio": "",
"notification_emails": [],
"number_of_rules": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}

operation: Get Livehunt Rulesets List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all Livehunt Rulesets is returned.

Parameter	Description
Filter	(Optional) Specify the filter using values of certain attributes, for example, filter=enabled:true, based on which you want to filter the livehunt rulesets retrieved from VirusTotal.
Order By	(Optional) Specify the order in which you want to sort the results retrieved from VirusTotal. Note: If your 'Filter' parameter contains content search, then the 'Order' parameter does not have any effect.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": "",
"cursor": ""
},
"data": [
{
"attributes": {
"name": "",
"modification_date": "",
"rules": "",
"enabled": "",
"rate_limited": "",
"creation_date": "",
"rule_names": [],
"limit": "",
"rate_limited_ratio": "",
"notification_emails": [],
"number_of_rules": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}
],
"links": {
"self": "",
"next": ""
}
}

operation: Get Livehunt Ruleset Details

Input parameters

Parameter	Description
Ruleset ID	Specify the ID of the livehunt ruleset for which you want to retrieve details from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"attributes": {
"name": "",
"modification_date": "",
"rules": "",
"enabled": "",
"rate_limited": "",
"creation_date": "",
"rule_names": [],
"limit": "",
"rate_limited_ratio": "",
"notification_emails": [],
"number_of_rules": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}

operation: Update Livehunt Ruleset

Input parameters

Parameter	Description
Ruleset ID	Specify the ID of the livehunt ruleset that you want to update in VirusTotal.
Ruleset Name	Specify the name of the livehunt ruleset that you want to update in VirusTotal.
Rules	Specify the rules based on which you want to update the hunting livehunt ruleset in VirustTotal.
Enabled	(Optional) Select this option (default) to 'enable' the livehunt ruleset that you want to update in VirusTotal.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 100.
Notification Emails	(Optional) Specify the list of comma-separated notifications emails using which you want to update the livehunt ruleset in VirusTotal.

Output

The output contains the following populated JSON schema:
{
"attributes": {
"name": "",
"modification_date": "",
"rules": "",
"enabled": "",
"rate_limited": "",
"creation_date": "",
"rule_names": [],
"limit": "",
"rate_limited_ratio": "",
"notification_emails": [],
"number_of_rules": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}

operation: Delete Livehunt Ruleset

Input parameters

Parameter	Description
Ruleset ID	Specify the ID of the livehunt ruleset for which you want to remove the livehunt ruleset details from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"message": ""
}

operation: Get Livehunt Notifications List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all Livehunt Notifications is returned.

Parameter	Description
Filter	(Optional) Specify the filter using values of certain attributes, for example, filter=tag:my_rule, based on which you want to filter the livehunt notifications retrieved from VirusTotal.
Order By	(Optional) Specify the order in which you want to sort the results retrieved from VirusTotal. Note: If your 'Filter' parameter contains content search, then the 'Order' parameter does not have any effect.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.
Count Limit	(Optional) Specify the maximum count of notifications that this operation should return, per page, in the response. By default, this is set as 200, and the maximum value that can be set is 10,000.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": "",
"cursor": ""
},
"data": [
{
"attributes": {
"tags": [],
"snippet": "",
"rule_name": "",
"date": "",
"rule_tags": [],
"match_in_subfile": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}
],
"links": {
"self": "",
"next": ""
}
}

operation: Get Livehunt Notifications Files List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all file objects for livehunt notifications is returned.

Parameter	Description
Filter	(Optional) Specify the filter using values of certain attributes, for example, filter=tag:my_rule, based on which you want to filter the file objects for livehunt notifications retrieved from VirusTotal.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.
Count Limit	(Optional) Specify the maximum count of notifications that this operation should return, per page, in the response. By default, this is set as 200, and the maximum value that can be set is 10,000.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": "",
"cursor": ""
},
"data": [
{
"attributes": {
"type_description": "",
"tlsh": "",
"vhash": "",
"exiftool": {
"FileDescription": "",
"LinkerVersion": "",
"ImageVersion": "",
"FileVersionNumber": "",
"UninitializedDataSize": "",
"LanguageCode": "",
"InternalName": "",
"ImageFileCharacteristics": "",
"CharacterSet": "",
"InitializedDataSize": "",
"EntryPoint": "",
"OriginalFileName": "",
"MIMEType": "",
"Subsystem": "",
"FileVersion": "",
"TimeStamp": "",
"FileType": "",
"PEType": "",
"FileFlagsMask": "",
"ProductVersion": "",
"SubsystemVersion": "",
"OSVersion": "",
"FileOS": "",
"LegalCopyright": "",
"MachineType": "",
"CodeSize": "",
"FileSubtype": "",
"ProductVersionNumber": "",
"FileTypeExtension": "",
"ObjectFileType": ""
},
"trid": [
{
"file_type": "",
"probability": ""
}
],
"signature_info": {
"description": "",
"copyright": "",
"internal name": "",
"file version": "",
"original name": ""
},
"creation_date": "",
"names": [],
"dot_net_guids": {
"mvid": ""
},
"last_modification_date": "",
"type_tag": "",
"times_submitted": "",
"total_votes": {
"harmless": "",
"malicious": ""
},
"size": "",
"type_extension": "",
"authentihash": "",
"last_submission_date": "",
"meaningful_name": "",
"downloadable": "",
"sha256": "",
"tags": [],
"last_analysis_date": "",
"unique_sources": "",
"first_submission_date": "",
"sha1": "",
"ssdeep": "",
"md5": "",
"dot_net_assembly": {
"external_modules": [],
"tables_rows_map_log": "",
"type_definition_list": [
{
"type_definitions": [],
"namespace": ""
}
],
"external_assemblies": {},
"tables_rows_map": "",
"assembly_name": "",
"streams": {},
"tables_present": "",
"clr_version": "",
"assembly_data": {
"majorversion": "",
"minorversion": "",
"hashalgid": "",
"flags_text": "",
"buildnumber": "",
"culture": "",
"flags": "",
"pubkey": "",
"revisionnumber": ""
},
"tables_present_map": "",
"clr_meta_version": ""
},
"pe_info": {
"resource_details": [
{
"lang": "",
"entropy": "",
"chi2": "",
"filetype": "",
"sha256": "",
"type": ""
}
],
"resource_types": {
"RT_VERSION": ""
},
"imphash": "",
"resource_langs": {
"NEUTRAL": ""
},
"machine_type": "",
"timestamp": "",
"entry_point": "",
"sections": [
{
"name": "",
"chi2": "",
"virtual_address": "",
"entropy": "",
"raw_size": "",
"flags": "rx",
"virtual_size": "",
"md5": ""
}
],
"import_list": [
{
"library_name": "",
"imported_functions": []
}
]
},
"magic": "",
"last_analysis_stats": {
"harmless": "",
"type-unsupported": "",
"suspicious": "",
"confirmed-timeout": "",
"timeout": "",
"failure": "",
"malicious": "",
"undetected": ""
},
"last_analysis_results": {},
"reputation": ""
},
"type": "",
"id": "",
"links": {
"self": ""
},
"context_attributes": {
"notification_id": "",
"notification_source_key": "",
"notification_tags": [],
"ruleset_name": "",
"notification_source_country": "",
"rule_name": "",
"notification_snippet": "",
"ruleset_id": "",
"rule_tags": [],
"notification_date": "",
"match_in_subfile": ""
}
}
],
"links": {
"self": "",
"next": ""
}
}

operation: Get Livehunt Notifications Details

Input parameters

Parameter	Description
Notification ID	Specify the ID of the livehunt notification for which you want to retrieve details from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"attributes": {
"tags": [],
"snippet": "",
"rule_name": "",
"date": "",
"rule_tags": [],
"match_in_subfile": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}

operation: Get Livehunt Rule Files List

Input parameters

Parameter	Description
Ruleset ID	Specify the ID of the ruleset for which you want to retrieve the associated hunting livehunt ruleset from VirusTotal by hunting notification files relationship in VirusTotal.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": "",
"cursor": ""
},
"data": [
{
"type": "",
"id": "",
"context_attributes": {
"notification_id": "",
"notification_source_key": "",
"notification_tags": [],
"ruleset_name": "",
"notification_source_country": "",
"rule_name": "",
"notification_snippet": "",
"ruleset_id": "",
"rule_tags": [],
"notification_date": "",
"match_in_subfile": ""
}
}
],
"links": {
"self": "",
"related": "",
"next": ""
}
}

operation: Create Retrohunt Job

Input parameters

Parameter	Description
Rules	Specify the rules based on which you want to create the Retrohunt job in VirustTotal.
Notification Emails	(Optional) Specify the list of comma-separated notification emails using which you want to create the Retrohunt job in VirusTotal.
Corpus	(Optional) Select the dataset you want to scan with the job that you want to create in VirusTotal. You can between Main or GoodWare.
Start Time	(Optional) Specify the starting DateTime from when you want to create the Retrohunt job in VirusTotal.
End time	(Optional) Specify the ending DateTime till when you want to create the Retrohunt job in VirusTotal.

Output

The output contains the following populated JSON schema:
{
"attributes": {
"status": "",
"rules": "",
"num_matches_outside_time_range": "",
"scanned_bytes": "",
"creation_date": "",
"progress": "",
"num_matches": "",
"notification_email": "",
"corpus": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}

operation: Abort Retrohunt Job

Input parameters

Parameter	Description
Job ID	Specify the ID of the Retrohunt job that you want to abort in VirusTotal.

Output

The output contains a non-dictionary value.

operation: Get Retrohunt jobs List

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all Retrohunt jobs is returned.

Parameter	Description
Filter	(Optional) Specify the filter using values of certain attributes, for example, filter=tag:my_rule, based on which you want to filter the Retrohunt jobs retrieved from VirusTotal.
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": ""
},
"data": [
{
"attributes": {
"status": "",
"rules": "",
"num_matches_outside_time_range": "",
"corpus": "",
"scanned_bytes": "",
"eta_seconds": "",
"num_matches": "",
"progress": "",
"notification_email": "",
"creation_date": "",
"start_date": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}
],
"links": {
"self": ""
}
}

operation: Get Retrohunt Job Details

Input parameters

Parameter	Description
Job ID	Specify the ID of the Retrohunt job for which you want to retrieve details from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"data": {
"attributes": {
"status": "",
"finish_date": "",
"rules": "",
"num_matches_outside_time_range": "",
"scanned_bytes": "",
"creation_date": "",
"num_matches": "",
"progress": "",
"notification_email": "",
"corpus": ""
},
"type": "",
"id": "",
"links": {
"self": ""
}
}
}

operation: Get Retrohunt Job Matching Files

Input parameters

Parameter	Description
Limit	(Optional) Specify the maximum number of results this operation should return, per page, in the response. By default, this is set as 10.
Cursor	(Optional) The 'Cursor' parameter is used only if a previous operation had returned a partial result. If a previous response contains a cursor element, then the value of the cursor element includes a cursor parameter that specifies a starting point to use for subsequent calls.

Output

The output contains the following populated JSON schema:
{
"meta": {
"count": "",
"cursor": ""
},
"data": [
{
"attributes": {
"type_description": "",
"tlsh": "",
"vhash": "",
"exiftool": {
"ZipRequiredVersion": "",
"MIMEType": "",
"ZipCRC": "",
"FileType": "",
"ZipCompression": "",
"ZipUncompressedSize": "",
"ZipCompressedSize": "",
"FileTypeExtension": "",
"ZipFileName": "",
"ZipBitFlag": "",
"ZipModifyDate": ""
},
"trid": [
{
"file_type": "",
"probability": ""
}
],
"names": [],
"last_modification_date": "",
"type_tag": "",
"times_submitted": "",
"total_votes": {
"harmless": "",
"malicious": ""
},
"size": "",
"type_extension": "",
"last_submission_date": "",
"last_analysis_results": {},
"downloadable": "",
"sha256": "",
"tags": [],
"last_analysis_date": "",
"unique_sources": "",
"first_submission_date": "",
"sha1": "",
"ssdeep": "",
"bundle_info": {
"highest_datetime": "",
"lowest_datetime": "",
"num_children": "",
"extensions": {
"xml": "",
"dex": "",
"so": "",
"png": ""
},
"file_types": {
"XML": "",
"DEX": "",
"ELF": "",
"PNG": "",
"unknown": ""
},
"type": "",
"uncompressed_size": ""
},
"md5": "",
"androguard": {
"VTAndroidInfo": "",
"Libraries": [],
"AndroidApplicationError": "",
"MinSdkVersion": "",
"AndroguardVersion": "",
"Activities": [],
"certificate": {
"Subject": {
"DN": "",
"C": "",
"CN": "",
"L": "",
"O": "",
"ST": "",
"OU": ""
},
"validto": "",
"serialnumber": "",
"thumbprint": "",
"validfrom": "",
"Issuer": {
"DN": "",
"C": "",
"CN": "",
"L": "",
"O": "",
"ST": "",
"OU": ""
}
},
"AndroidApplication": "",
"RiskIndicator": {
"APK": {
"DEX": "",
"SHARED LIBRARIES": ""
},
"PERM": {
"INSTANT": "",
"PRIVACY": "",
"DANGEROUS": "",
"NORMAL": "",
"INTERNET": "",
"GPS": ""
}
},
"Services": [],
"AndroidVersionCode": "",
"main_activity": "",
"Package": "",
"intent_filters": {
"Services": {},
"Activities": {},
"Receivers": {}
},
"AndroidVersionName": "",
"TargetSdkVersion": "",
"AndroidApplicationInfo": "",
"Providers": [],
"permission_details": {},
"Receivers": [],
"StringsInformation": []
},
"magic": "",
"main_icon": {
"raw_md5": "",
"dhash": ""
},
"last_analysis_stats": {
"harmless": "",
"type-unsupported": "",
"suspicious": "",
"confirmed-timeout": "",
"timeout": "",
"failure": "",
"malicious": "",
"undetected": ""
},
"meaningful_name": "",
"reputation": ""
},
"type": "",
"id": "",
"links": {
"self": ""
},
"context_attributes": {
"rule_name": "",
"match_in_subfile": ""
}
}
],
"links": {
"self": "",
"next": ""
}
}

operation: Delete Retrohunt Job

Input parameters

Parameter	Description
Job ID	Specify the ID of the Retrohunt job that you want to delete from VirusTotal.

Output

The output contains the following populated JSON schema:
{
"message": ""
}

Included playbooks

The Sample - Virustotal Premium - 1.0.0 playbook collection comes bundled with the VirusTotal Premium connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the VirusTotal Premium connector.

• Abort Retrohunt Job
• Create Livehunt Ruleset
• Create Retrohunt Job
• Create ZIP File
• Delete Livehunt Ruleset
• Delete Retrohunt Job
• Domain > VirusTotal Premium > Enrichment
• Download File
• Download ZIP File
• File Hash > VirusTotal Premium > Enrichment
• Get Livehunt Notifications Details
• Get Livehunt Notifications Files List
• Get Livehunt Notifications List
• Get Livehunt Rule Files List
• Get Livehunt Ruleset Details
• Get Livehunt Rulesets List
• Get PCAP File Behaviour
• Get Retrohunt Job Details
• Get Retrohunt Job Matching Files
• Get Retrohunt jobs List
• Get ZIP File Status
• Get ZIP File URL
• IP Address > VirusTotal Premium> Enrichment
• Search Intelligence
• Update Livehunt Ruleset
• URL > VirusTotal Premium > Enrichment

Note: If you plan 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 the connector upgrade and delete.

Pluggable Enrichment

The Sample - VirusTotal Premium - 1.0.0 playbook collection contains pluggable enrichment playbooks that are used to provide verdicts for indicator types IP Address, File Hash, URL, and Domain. The pluggable enrichment playbooks are in the format: '<indicator type> > VirusTotal Premium > Enrichment' format. For example, 'IP > VirusTotal Premium > Enrichment'.

The 'Configuration' step in all the pluggable enrichment playbooks contains variables that have default values for calculating the 'Verdict' for various indicator types.

Default variables for all supported indicator types

The VirusTotal Premium integration API response returns the verdict, cti_score, and enrichment_summary and other variables as listed in the following table:

Variable Name	Description	Return Value
verdict	This connector returns a high-reliability value called 'verdict'. Use this verdict to find the reputation of the various types of indicators.	if the value in last_analysis_stats.malicious > 0 then the verdict returned is Malicious if the value in last_analysis_stats.suspicious > 0 then the verdict returned is Suspicious if the value in last_analysis_stats.harmless > 0 then the verdict returned is Good For any other value, return the verdict as No Reputation Available
cti_name	The name of the connector is called the CTI (Cyber Threat Intelligence) name	VirusTotal Premium
cti_score	The verdict value is returned by the integration API.	Returns the value contained in last_analysis_stats.malicious Returns the value in last_analysis_stats.suspicious if last_analysis_stats.malicious is empty Returns 0 if both are empty.
source_data	The source_data response is returned by the integration API.	A JSON response object containing the source data of the threat intelligence integration.
field_mapping	The mapping of the FortiSOAR 'indicator' module fields with the VirusTotal Premium response fields.	A JSON response object containing the field mapping of the threat intelligence integration.
enrichment_summary	The contents are added, in the HTML format, in the 'Description' field of the specified FortiSOAR indicator record.	The following values are returned in the HTML format: Malicious Suspicious Harmless Community Votes The following image displays a sample of the populated 'Description' field in a FortiSOAR indicator record: