Fortinet Document Library

Version:


Table of Contents

1.0.0
Copy Link

About the connector

VMRAY provides a service that analyses suspicious files and URLs and facilitates the quick detection of viruses, worms, trojans, and all kinds of malware.

This document provides information about the VMRAY connector, which facilitates automated interactions, with a VMRAY Cloud Analyzer server using FortiSOAR™ playbooks. Add the VMRAY connector as a step in FortiSOAR™ playbooks and perform automated operations, such as scanning and analyzing suspicious files and URLs and retrieving reports from VMRAY for submitted sample files and domains.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with VMRay Versions: 2.1.0 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL of the VMRAY Cloud Analyzer server to which you will connect and perform the automated operations and the API key to access that server.
  • 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 VMRAY connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL of the VMRAY Cloud Analyzer server to which you will connect and perform the automated operations.
API Key API key configured for your account to access the VMRAY Cloud Analyzer 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 from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Submit Sample Scans and analyzes files that are submitted from the Attachment module in FortiSOAR™ to VMRAY to determine if they are suspicious. detonate_file
Investigation
Submit Sample URL Scans and analyzes files that are submitted from a web server to VMRAY to determine if they are suspicious. detonate_file
Investigation
Submit URL Scans and analyzes URLs that are submitted to VMRAY to determine if they are suspicious. detonate_url
Investigation
Get Samples Retrieves details of all samples in the system or retrieves details of samples based on the parameters you have specified. get_samples
Investigation
Get Submissions Retrieves details of all submissions in the system or retrieves details of submissions based on the parameters you have specified. get_submissions
Investigation
Get Prescripts Retrieves details of all prescripts in the system or retrieves details of prescripts based on the parameters you have specified. get_prescripts
Investigation
Get Analysis Retrieves details of all analyses in the system or retrieves details of analyses based on the parameters you have specified. get_analysis
Investigation
Get Reputation Lookups Retrieves details of all reputation lookups in the system or retrieves details of reputation lookups based on the parameters you have specified. get_reputation_lookups
Investigation
Get Metadefender Analysis Retrieves details of all Metadefender analysis in the system or retrieves details of Metadefender Analysis based on the parameters you have specified. get_md_analysis
Investigation
Get VirusTotal Analysis Retrieves details of all VirusTotal analysis in the system or retrieves details of VirusTotal Analysis based on the parameters you have specified. get_vt_analysis
Investigation
Get Job Analysis Retrieves details of all analyzer jobs in the system or retrieves details of analyzer jobs based on the parameters you have specified. get_job
Investigation
Get Reputation Jobs Retrieves details of all reputation jobs in the system or retrieves details of reputation jobs based on the parameters you have specified. get_reputation_jobs
Investigation
Get Metadefender Jobs Retrieves details of all Metadefender jobs in the system or retrieves details of Metadefender jobs based on the parameters you have specified. get_md_jobs
Investigation
Get VirusTotal Jobs Retrieves details of all VirusTotal jobs in the system or retrieves details of VirusTotal jobs based on the parameters you have specified. get_vt_jobs
Investigation
Get Tags Retrieves details of all tags in the system or retrieves details of tags based on the parameters you have specified. get_tags
Investigation
Get System Information Retrieves system-wide information, such as the VMRAY Analyzer version of the running VMRAY server. get_system_info
Investigation
Delete Job Deletes the VMRAY Analyzer job based on the job ID you have specified. delete_job
Investigation
Delete Submission Deletes the VMRAY Analyzer submission based on the submission ID you have specified. delete_submission
Investigation

 

operation: Submit Sample

Input parameters

Note: Only the File IRI parameter is mandatory.

 

Parameter Description
File IRI IRI of the file that is present in the Attachment module in FortiSOAR™ that you want to submit VMRAY for scanning and analysis.
Sample Type List of officially supported VMRAY Analyzer sample types.
Sharable with VirusTotal and Metadefender (MD) Select this option to make this file shareable with VirusTotal and Metadefender, i.e. this file can be submitted to VirusTotal and Metadefender.
Custom Jobrule By default, submitted files create new jobs according to the default jobrules of the sample type. Use the jobrule_entries parameter to specify alternative jobrules for this submission.
Reanalyze Select this option to specify that new jobs should be created even if analyses already exist for this sample.
Max job Limits the number of jobs that can be created by jobrules for this submission.
In the case of an activated billing system, this parameter allows you to control the consumption of the quota of jobs.
Tags (Comma separated if multiple) Used to specify a comma-separated list of tags for this submission.

 

Output

The JSON output contains the analysis_id for the file that you have submitted to VMRAY. You can use this analysis_id in future to query and retrieve analysis reports from VMRAY for this file.

Following image displays a sample output:
 

Sample output of the Submit Sample operation

 

operation: Submit Sample URL

Input parameters

Note: Only the Sample Url parameter is mandatory.

 

Parameter Description
Sample Url Name of the file that is present on a web server that you want to submit VMRAY for scanning and analysis.
Sample Type List of officially supported VMRAY Analyzer sample types.
Sharable with VirusTotal and Metadefender (MD) Select this option to make this file shareable with VirusTotal and Metadefender, i.e. this file can be submitted to VirusTotal and Metadefender.
Custom Jobrule By default, submitted files create new jobs according to the default jobrules of the sample type. Use the jobrule_entries parameter to specify alternative jobrules for this submission.
Reanalyze Select this option to specify that new jobs should be created even if analyses already exist for this sample.
Max job Limits the amount of jobs that can be created by jobrules for this submission.
In the case of an activated billing system, this parameter allows you to control the consumption of the quota of jobs.
Tags (Comma separated if multiple) Used to specify a comma-separated list of tags for this submission.

 

Output

The JSON output contains the analysis_id for the file that you have submitted to VMRAY. You can use this analysis_id in future to query and retrieve analysis reports from VMRAY for this file.

Following image displays a sample output:
 

Sample output of the Submit Sample URL operation

 

operation: Submit URL

Input parameters

 

Parameter Description
URL URL that you want to submit VMRAY for scanning and analysis.

 

Output

The JSON output contains the report from VMRAY for the submitted URL. You can use this report to determine if the submitted URL is suspicious.

Following image displays a sample output:
 

Sample output of the Submit URL operation

 

operation: Get Samples

Input parameters

 

Parameter Description
Parameters Specify parameters based on which sample details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all samples in the system.
ID: Retrieves details of samples in the system based on the sample ID you specify.
Created: Retrieves details of samples in the system based on the date the samples were created.
Filesize: Retrieves details of samples in the system based on the filesize (in bytes) you specify. All samples below the specified filesize are retrieved from the system.
Md5: Retrieves details of samples in the system based on the MD hash you specify.
Sha1: Retrieves details of samples in the system based on the SHA1 hash you specify.
Sha256: Retrieves details of samples in the system based on the SHA256 hash you specify.
Type: Retrieves details of samples in the system based on the type you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which samples were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all samples in the system or for samples you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Samples operation

 

operation: Get Submissions

Input parameters

 

Parameter Description
Parameters Specify parameters based on which submission details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all submissions in the system.
ID: Retrieves details of submissions in the system based on the submission ID you specify.
Created: Retrieves details of submissions in the system based on the date the submissions were created.
Finish_Time: Retrieves details of submissions in the system based on the time VMRAY completed analyses on the submission.
Prescript: Retrieves details of submissions in the system based on the Prescript ID you specify.
Priority: Retrieves details of submissions in the system based on the priority you specify. All submissions that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of submissions in the system based on the sample ID you specify.
Type: Retrieves details of submissions in the system based on the type (API or WEB) you specify.
Sample: Retrieves details of submissions in the system based on the user ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which submissions were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all submissions in the system or for submissions you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Submissions operation

 

operation: Get Prescripts

Input parameters

 

Parameter Description
Parameters Specify parameters based on which prescripts details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all prescripts in the system.
ID: Retrieves details of prescripts in the system based on the prescript ID you specify.
Created: Retrieves details of prescripts in the system based on the date the prescripts were created.
Filesize: Retrieves details of prescripts in the system based on the filesize (in bytes) you specify. All prescripts below the specified filesize are retrieved from the system.
Md5: Retrieves details of prescripts in the system based on the MD hash you specify.
Sha1: Retrieves details of prescripts in the system based on the SHA1 hash you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which prescripts were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all prescripts in the system or for prescripts you have specified using parameters.

Following image displays a sample output:

 

Sample output of the Get Prescripts operation

 

operation: Get Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which analyses details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all analyses in the system.
ID: Retrieves details of analyses in the system based on the analyses ID you specify.
Analyzer: Retrieves details of analyses in the system based on the analyzer ID you specify.
Configuration: Retrieves details of analyses in the system based on the configuration ID you specify.
Created: Retrieves details of analyses in the system based on the date the analyses were created.
Job: Retrieves details of analyses in the system based on the job ID you specify.
Jobrule: Retrieves details of analyses in the system based on the jobrule ID you specify.
Job_Started: Retrieves details of analyses in the system based on the date the jobs were started.
Prescript: Retrieves details of analyses in the system based on the prescript ID you specify.
Result_Code: Retrieves details of analyses in the system based on the result code you specify.
Sample: Retrieves details of analyses in the system based on the sample ID you specify.
Size: Retrieves details of analyses in the system based on the size of the analysis archive you specify.
Snapshot: Retrieves details of analyses in the system based on the snapshot ID you specify.
Submission: Retrieves details of analyses in the system based on the submission ID you specify.
User: Retrieves details of analyses in the system based on the User ID you specify.
Vm: Retrieves details of analyses in the system based on the Virtual Machine (VM) ID you specify.
Vmhost: Retrieves details of analyses in the system based on the VM Host ID you specify.
Vti_Score: Retrieves details of analyses in the system that has the VTI score you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all analyses in the system or for analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Analysis operation

 

operation: Get Reputation Lookups

Input parameters

 

Parameter Description
Parameters Specify parameters based on which reputation lookup details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all reputation lookups in the system.
ID: Retrieves details of reputation lookup in the system based on the reputation lookup ID you specify.
Created: Retrieves details of reputation lookups in the system based on the date the reputation lookup were created.
Job: Retrieves details of reputation lookups in the system based on the job ID you specify.
Result_Code: Retrieves details of reputation lookups in the system based on the result code you specify.
Sample: Retrieves details of reputation lookups in the system based on the sample ID you specify.
Severity: Retrieves details of reputation lookups in the system based on the severity you specify. All reputation lookups that are above or equal to the severity you specify are retrieved from the system.
Submission: Retrieves details of reputation lookups in the system based on the submission ID you specify.
User: Retrieves details of reputation lookups in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which reputation lookups were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all reputation lookups in the system or for reputation lookups you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Reputation Lookups operation

 

operation: Get Metadefender Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of Metadefender analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all Metadefender analyses in the system.
ID: Retrieves details of Metadefender analyses in the system based on the Metadefender analysis ID you specify.
Created: Retrieves details of Metadefender analyses in the system based on the date Metadefender analyses were created.
Job: Retrieves details of Metadefender analyses in the system based on the job ID you specify.
Num_Positives: Retrieves details of Metadefender analyses in the system, which are equal to the number you specify in Num_Positives.
Num_Negatives: Retrieves details of Metadefender analyses in the system, which are equal to the number you specify in Num_Negatives.
Result_Code: Retrieves details of Metadefender analyses in the system based on the result code you specify.
Sample: Retrieves details of Metadefender analyses in the system based on the sample ID you specify.
Score: Retrieves details of Metadefender analyses in the system with the score you specify.
Submission: Retrieves details of Metadefender analyses in the system based on the submission ID you specify.
User: Retrieves details of Metadefender analyses in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which Metadefender analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all metadefender analyses in the system or for metadefender analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Analysis operation

 

operation: Get VirusTotal Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of VirusTotal analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all VirusTotal analyses in the system.
ID: Retrieves details of VirusTotal analyses in the system based on the VirusTotal analysis ID you specify.
Created: Retrieves details of VirusTotal analyses in the system based on the date VirusTotal analyses were created.
Job: Retrieves details of VirusTotal analyses in the system based on the job ID you specify.
Num_Positives: Retrieves details of VirusTotal analyses in the system, which are equal to the number you specify in Num_Positives.
Num_Negatives: Retrieves details of VirusTotal analyses in the system, which are equal to the number you specify in Num_Negatives.
Result_Code: Retrieves details of VirusTotal analyses in the system based on the result code you specify.
Sample: Retrieves details of VirusTotal analyses in the system based on the sample ID you specify.
Score: Retrieves details of VirusTotal analyses in the system with the score you specify.
Submission: Retrieves details of VirusTotal analyses in the system based on the submission ID you specify.
User: Retrieves details of VirusTotal analyses in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which VirusTotal analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all VirusTotal analyses in the system or for VirusTotal analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Analysis operation

 

operation: Get Job Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of job analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all job analyses in the system.
ID: Retrieves details of job analyses in the system based on the job ID you specify.
Configuration: Retrieves details of job analyses in the system based on the configuration ID you specify.
Created: Retrieves details of job analyses in the system based on the date job analyses were created.
Jobrule: Retrieves details of job analyses in the system based on the jobrule ID you specify.
Prescript: Retrieves details of job analyses in the system based on the prescript ID you specify.
Priority: Retrieves details of job analyses in the system based on the priority you specify. All job analyses that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of job analyses in the system based on the sample ID you specify.
Snapshot: Retrieves details of job analyses in the system based on the snapshot ID you specify.
Status: Retrieves details of job analyses in the system with the status you specify.
Statuschanged: Retrieves details of job analyses in the system with the Statuschanged you specify.
Submission: Retrieves details of job analyses in the system based on the submission ID you specify.
User: Retrieves details of job analyses in the system based on the User ID you specify.
Vm: Retrieves details of job analyses in the system based on the VM ID you specify.
Vmhost: Retrieves details of job analyses in the system based on the VM Host ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which job analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all job analyses in the system or for job analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Job Analysis operation

 

operation: Get Reputation Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of reputation jobs are retrieved from VMRAY. Choose from the following options:
All: Retrieves details of all reputation jobs in the system.
ID: Retrieves details of reputation jobs in the system based on the reputation job ID you specify.
Created: Retrieves details of reputation jobs in the system based on the date reputation jobs were created.
Priority: Retrieves details of reputation jobs in the system based on the priority you specify. All reputation jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of reputation jobs in the system based on the sample ID you specify.
Status: Retrieves details of reputation jobs in the system with the status you specify.
Statuschanged: Retrieves details of reputation jobs in the system with the Statuschanged you specify.
User: Retrieves details of reputation jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which reputation jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all reputation jobs in the system or for reputation jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Reputation Jobs operation

 

operation: Get Metadefender Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of Metadefender jobs are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all Metadefender jobs in the system.
ID: Retrieves details of Metadefender jobs in the system based on the Metadefender job ID you specify.
Created: Retrieves details of Metadefender jobs in the system based on the date Metadefender jobs were created.
Priority: Retrieves details of Metadefender jobs in the system based on the priority you specify. All Metadefender jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of Metadefender jobs in the system based on the sample ID you specify.
Status: Retrieves details of Metadefender jobs in the system with the status you specify.
Statuschanged: Retrieves details of Metadefender jobs in the system with the Statuschanged you specify.
User: Retrieves details of Metadefender jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which Metadefender jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all Metadefender jobs in the system or for Metadefender jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Jobs operation

 

operation: Get VirusTotal Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of VirusTotal jobs are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all VirusTotal jobs in the system.
ID: Retrieves details of VirusTotal jobs in the system based on the VirusTotal job ID you specify.
Created: Retrieves details of VirusTotal jobs in the system based on the date Metadefender jobs were created.
Priority: Retrieves details of VirusTotal jobs in the system based on the priority you specify. All VirusTotal jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of VirusTotal jobs in the system based on the sample ID you specify.
Status: Retrieves details of VirusTotal jobs in the system with the status you specify.
Statuschanged: Retrieves details of VirusTotal jobs in the system with the Statuschanged you specify.
User: Retrieves details of VirusTotal jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which VirusTotal jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all VirusTotal jobs in the system or for VirusTotal jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get VirusTotal Jobs operation

 

operation: Get Tags

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of tags are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all tags in the system.
Name: Retrieves details of tags in the system based on the name of the tag you specify.
Value Specify the value of the parameter you select.
For example, if you select Name, then you have to specify the name of the tag for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all tags in the system or for the tag you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Tags operation

 

operation: Get System Information

Input parameters

None.

Output

The JSON output contains the report from VMRAY that returns system-wide information, such as the VMRAY Analyzer version of the running VMRAY server.

Following image displays a sample output:
 

Sample output of the Get System Information operation

 

operation: Delete Job

Input parameters

 

Parameter Description
Parameters Specify parameters based on which a job is deleted from VMRAY.
For this operation, select ID.
Value Specify the ID of the job that you want to delete from the VMRAY.

 

Output

The JSON output returns a Success message if VMRAY successfully deletes the job specified or an Error message containing the reason for failure.

operation: Delete Submission

Input parameters

 

Parameter Description
Parameters Specify parameters based on which a submission is deleted from VMRAY.
For this operation, select ID.
Value Specify the ID of the submission that you want to delete from the VMRAY.

 

Output

The JSON output returns a Success message if VMRAY successfully deletes the submission specified or an Error message containing the reason for failure.

Following image displays a sample output:
 

Sample output of the Delete Submission operation

 

Included playbooks

The Sample-VMRAY-1.0.0 playbook collection comes bundled with the VMRAY 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 VMRAY connector.

  • Delete Job
  • Delete Submission
  • Get Analysis
  • Get Jobs
  • Get Metadefender Analysis
  • Get Metadefender Jobs
  • Get Prescripts
  • Get Reputation Jobs
  • Get Reputation Lookups
  • Get Samples
  • Get Submissions
  • Get System Information
  • Get Tags
  • Get VirusTotal Analysis
  • Get VirusTotal Jobs
  • Submit Sample
  • Submit Sample Url
  • 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.

 

About the connector

VMRAY provides a service that analyses suspicious files and URLs and facilitates the quick detection of viruses, worms, trojans, and all kinds of malware.

This document provides information about the VMRAY connector, which facilitates automated interactions, with a VMRAY Cloud Analyzer server using FortiSOAR™ playbooks. Add the VMRAY connector as a step in FortiSOAR™ playbooks and perform automated operations, such as scanning and analyzing suspicious files and URLs and retrieving reports from VMRAY for submitted sample files and domains.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.9.0.0-708 and later

Compatibility with VMRay Versions: 2.1.0 and later

 

Installing the connector

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 VMRAY connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL URL of the VMRAY Cloud Analyzer server to which you will connect and perform the automated operations.
API Key API key configured for your account to access the VMRAY Cloud Analyzer 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 from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Submit Sample Scans and analyzes files that are submitted from the Attachment module in FortiSOAR™ to VMRAY to determine if they are suspicious. detonate_file
Investigation
Submit Sample URL Scans and analyzes files that are submitted from a web server to VMRAY to determine if they are suspicious. detonate_file
Investigation
Submit URL Scans and analyzes URLs that are submitted to VMRAY to determine if they are suspicious. detonate_url
Investigation
Get Samples Retrieves details of all samples in the system or retrieves details of samples based on the parameters you have specified. get_samples
Investigation
Get Submissions Retrieves details of all submissions in the system or retrieves details of submissions based on the parameters you have specified. get_submissions
Investigation
Get Prescripts Retrieves details of all prescripts in the system or retrieves details of prescripts based on the parameters you have specified. get_prescripts
Investigation
Get Analysis Retrieves details of all analyses in the system or retrieves details of analyses based on the parameters you have specified. get_analysis
Investigation
Get Reputation Lookups Retrieves details of all reputation lookups in the system or retrieves details of reputation lookups based on the parameters you have specified. get_reputation_lookups
Investigation
Get Metadefender Analysis Retrieves details of all Metadefender analysis in the system or retrieves details of Metadefender Analysis based on the parameters you have specified. get_md_analysis
Investigation
Get VirusTotal Analysis Retrieves details of all VirusTotal analysis in the system or retrieves details of VirusTotal Analysis based on the parameters you have specified. get_vt_analysis
Investigation
Get Job Analysis Retrieves details of all analyzer jobs in the system or retrieves details of analyzer jobs based on the parameters you have specified. get_job
Investigation
Get Reputation Jobs Retrieves details of all reputation jobs in the system or retrieves details of reputation jobs based on the parameters you have specified. get_reputation_jobs
Investigation
Get Metadefender Jobs Retrieves details of all Metadefender jobs in the system or retrieves details of Metadefender jobs based on the parameters you have specified. get_md_jobs
Investigation
Get VirusTotal Jobs Retrieves details of all VirusTotal jobs in the system or retrieves details of VirusTotal jobs based on the parameters you have specified. get_vt_jobs
Investigation
Get Tags Retrieves details of all tags in the system or retrieves details of tags based on the parameters you have specified. get_tags
Investigation
Get System Information Retrieves system-wide information, such as the VMRAY Analyzer version of the running VMRAY server. get_system_info
Investigation
Delete Job Deletes the VMRAY Analyzer job based on the job ID you have specified. delete_job
Investigation
Delete Submission Deletes the VMRAY Analyzer submission based on the submission ID you have specified. delete_submission
Investigation

 

operation: Submit Sample

Input parameters

Note: Only the File IRI parameter is mandatory.

 

Parameter Description
File IRI IRI of the file that is present in the Attachment module in FortiSOAR™ that you want to submit VMRAY for scanning and analysis.
Sample Type List of officially supported VMRAY Analyzer sample types.
Sharable with VirusTotal and Metadefender (MD) Select this option to make this file shareable with VirusTotal and Metadefender, i.e. this file can be submitted to VirusTotal and Metadefender.
Custom Jobrule By default, submitted files create new jobs according to the default jobrules of the sample type. Use the jobrule_entries parameter to specify alternative jobrules for this submission.
Reanalyze Select this option to specify that new jobs should be created even if analyses already exist for this sample.
Max job Limits the number of jobs that can be created by jobrules for this submission.
In the case of an activated billing system, this parameter allows you to control the consumption of the quota of jobs.
Tags (Comma separated if multiple) Used to specify a comma-separated list of tags for this submission.

 

Output

The JSON output contains the analysis_id for the file that you have submitted to VMRAY. You can use this analysis_id in future to query and retrieve analysis reports from VMRAY for this file.

Following image displays a sample output:
 

Sample output of the Submit Sample operation

 

operation: Submit Sample URL

Input parameters

Note: Only the Sample Url parameter is mandatory.

 

Parameter Description
Sample Url Name of the file that is present on a web server that you want to submit VMRAY for scanning and analysis.
Sample Type List of officially supported VMRAY Analyzer sample types.
Sharable with VirusTotal and Metadefender (MD) Select this option to make this file shareable with VirusTotal and Metadefender, i.e. this file can be submitted to VirusTotal and Metadefender.
Custom Jobrule By default, submitted files create new jobs according to the default jobrules of the sample type. Use the jobrule_entries parameter to specify alternative jobrules for this submission.
Reanalyze Select this option to specify that new jobs should be created even if analyses already exist for this sample.
Max job Limits the amount of jobs that can be created by jobrules for this submission.
In the case of an activated billing system, this parameter allows you to control the consumption of the quota of jobs.
Tags (Comma separated if multiple) Used to specify a comma-separated list of tags for this submission.

 

Output

The JSON output contains the analysis_id for the file that you have submitted to VMRAY. You can use this analysis_id in future to query and retrieve analysis reports from VMRAY for this file.

Following image displays a sample output:
 

Sample output of the Submit Sample URL operation

 

operation: Submit URL

Input parameters

 

Parameter Description
URL URL that you want to submit VMRAY for scanning and analysis.

 

Output

The JSON output contains the report from VMRAY for the submitted URL. You can use this report to determine if the submitted URL is suspicious.

Following image displays a sample output:
 

Sample output of the Submit URL operation

 

operation: Get Samples

Input parameters

 

Parameter Description
Parameters Specify parameters based on which sample details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all samples in the system.
ID: Retrieves details of samples in the system based on the sample ID you specify.
Created: Retrieves details of samples in the system based on the date the samples were created.
Filesize: Retrieves details of samples in the system based on the filesize (in bytes) you specify. All samples below the specified filesize are retrieved from the system.
Md5: Retrieves details of samples in the system based on the MD hash you specify.
Sha1: Retrieves details of samples in the system based on the SHA1 hash you specify.
Sha256: Retrieves details of samples in the system based on the SHA256 hash you specify.
Type: Retrieves details of samples in the system based on the type you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which samples were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all samples in the system or for samples you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Samples operation

 

operation: Get Submissions

Input parameters

 

Parameter Description
Parameters Specify parameters based on which submission details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all submissions in the system.
ID: Retrieves details of submissions in the system based on the submission ID you specify.
Created: Retrieves details of submissions in the system based on the date the submissions were created.
Finish_Time: Retrieves details of submissions in the system based on the time VMRAY completed analyses on the submission.
Prescript: Retrieves details of submissions in the system based on the Prescript ID you specify.
Priority: Retrieves details of submissions in the system based on the priority you specify. All submissions that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of submissions in the system based on the sample ID you specify.
Type: Retrieves details of submissions in the system based on the type (API or WEB) you specify.
Sample: Retrieves details of submissions in the system based on the user ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which submissions were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all submissions in the system or for submissions you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Submissions operation

 

operation: Get Prescripts

Input parameters

 

Parameter Description
Parameters Specify parameters based on which prescripts details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all prescripts in the system.
ID: Retrieves details of prescripts in the system based on the prescript ID you specify.
Created: Retrieves details of prescripts in the system based on the date the prescripts were created.
Filesize: Retrieves details of prescripts in the system based on the filesize (in bytes) you specify. All prescripts below the specified filesize are retrieved from the system.
Md5: Retrieves details of prescripts in the system based on the MD hash you specify.
Sha1: Retrieves details of prescripts in the system based on the SHA1 hash you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which prescripts were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all prescripts in the system or for prescripts you have specified using parameters.

Following image displays a sample output:

 

Sample output of the Get Prescripts operation

 

operation: Get Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which analyses details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all analyses in the system.
ID: Retrieves details of analyses in the system based on the analyses ID you specify.
Analyzer: Retrieves details of analyses in the system based on the analyzer ID you specify.
Configuration: Retrieves details of analyses in the system based on the configuration ID you specify.
Created: Retrieves details of analyses in the system based on the date the analyses were created.
Job: Retrieves details of analyses in the system based on the job ID you specify.
Jobrule: Retrieves details of analyses in the system based on the jobrule ID you specify.
Job_Started: Retrieves details of analyses in the system based on the date the jobs were started.
Prescript: Retrieves details of analyses in the system based on the prescript ID you specify.
Result_Code: Retrieves details of analyses in the system based on the result code you specify.
Sample: Retrieves details of analyses in the system based on the sample ID you specify.
Size: Retrieves details of analyses in the system based on the size of the analysis archive you specify.
Snapshot: Retrieves details of analyses in the system based on the snapshot ID you specify.
Submission: Retrieves details of analyses in the system based on the submission ID you specify.
User: Retrieves details of analyses in the system based on the User ID you specify.
Vm: Retrieves details of analyses in the system based on the Virtual Machine (VM) ID you specify.
Vmhost: Retrieves details of analyses in the system based on the VM Host ID you specify.
Vti_Score: Retrieves details of analyses in the system that has the VTI score you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all analyses in the system or for analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Analysis operation

 

operation: Get Reputation Lookups

Input parameters

 

Parameter Description
Parameters Specify parameters based on which reputation lookup details are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all reputation lookups in the system.
ID: Retrieves details of reputation lookup in the system based on the reputation lookup ID you specify.
Created: Retrieves details of reputation lookups in the system based on the date the reputation lookup were created.
Job: Retrieves details of reputation lookups in the system based on the job ID you specify.
Result_Code: Retrieves details of reputation lookups in the system based on the result code you specify.
Sample: Retrieves details of reputation lookups in the system based on the sample ID you specify.
Severity: Retrieves details of reputation lookups in the system based on the severity you specify. All reputation lookups that are above or equal to the severity you specify are retrieved from the system.
Submission: Retrieves details of reputation lookups in the system based on the submission ID you specify.
User: Retrieves details of reputation lookups in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which reputation lookups were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all reputation lookups in the system or for reputation lookups you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Reputation Lookups operation

 

operation: Get Metadefender Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of Metadefender analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all Metadefender analyses in the system.
ID: Retrieves details of Metadefender analyses in the system based on the Metadefender analysis ID you specify.
Created: Retrieves details of Metadefender analyses in the system based on the date Metadefender analyses were created.
Job: Retrieves details of Metadefender analyses in the system based on the job ID you specify.
Num_Positives: Retrieves details of Metadefender analyses in the system, which are equal to the number you specify in Num_Positives.
Num_Negatives: Retrieves details of Metadefender analyses in the system, which are equal to the number you specify in Num_Negatives.
Result_Code: Retrieves details of Metadefender analyses in the system based on the result code you specify.
Sample: Retrieves details of Metadefender analyses in the system based on the sample ID you specify.
Score: Retrieves details of Metadefender analyses in the system with the score you specify.
Submission: Retrieves details of Metadefender analyses in the system based on the submission ID you specify.
User: Retrieves details of Metadefender analyses in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which Metadefender analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all metadefender analyses in the system or for metadefender analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Analysis operation

 

operation: Get VirusTotal Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of VirusTotal analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all VirusTotal analyses in the system.
ID: Retrieves details of VirusTotal analyses in the system based on the VirusTotal analysis ID you specify.
Created: Retrieves details of VirusTotal analyses in the system based on the date VirusTotal analyses were created.
Job: Retrieves details of VirusTotal analyses in the system based on the job ID you specify.
Num_Positives: Retrieves details of VirusTotal analyses in the system, which are equal to the number you specify in Num_Positives.
Num_Negatives: Retrieves details of VirusTotal analyses in the system, which are equal to the number you specify in Num_Negatives.
Result_Code: Retrieves details of VirusTotal analyses in the system based on the result code you specify.
Sample: Retrieves details of VirusTotal analyses in the system based on the sample ID you specify.
Score: Retrieves details of VirusTotal analyses in the system with the score you specify.
Submission: Retrieves details of VirusTotal analyses in the system based on the submission ID you specify.
User: Retrieves details of VirusTotal analyses in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which VirusTotal analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all VirusTotal analyses in the system or for VirusTotal analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Analysis operation

 

operation: Get Job Analysis

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of job analyses are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all job analyses in the system.
ID: Retrieves details of job analyses in the system based on the job ID you specify.
Configuration: Retrieves details of job analyses in the system based on the configuration ID you specify.
Created: Retrieves details of job analyses in the system based on the date job analyses were created.
Jobrule: Retrieves details of job analyses in the system based on the jobrule ID you specify.
Prescript: Retrieves details of job analyses in the system based on the prescript ID you specify.
Priority: Retrieves details of job analyses in the system based on the priority you specify. All job analyses that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of job analyses in the system based on the sample ID you specify.
Snapshot: Retrieves details of job analyses in the system based on the snapshot ID you specify.
Status: Retrieves details of job analyses in the system with the status you specify.
Statuschanged: Retrieves details of job analyses in the system with the Statuschanged you specify.
Submission: Retrieves details of job analyses in the system based on the submission ID you specify.
User: Retrieves details of job analyses in the system based on the User ID you specify.
Vm: Retrieves details of job analyses in the system based on the VM ID you specify.
Vmhost: Retrieves details of job analyses in the system based on the VM Host ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which job analyses were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all job analyses in the system or for job analyses you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Job Analysis operation

 

operation: Get Reputation Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of reputation jobs are retrieved from VMRAY. Choose from the following options:
All: Retrieves details of all reputation jobs in the system.
ID: Retrieves details of reputation jobs in the system based on the reputation job ID you specify.
Created: Retrieves details of reputation jobs in the system based on the date reputation jobs were created.
Priority: Retrieves details of reputation jobs in the system based on the priority you specify. All reputation jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of reputation jobs in the system based on the sample ID you specify.
Status: Retrieves details of reputation jobs in the system with the status you specify.
Statuschanged: Retrieves details of reputation jobs in the system with the Statuschanged you specify.
User: Retrieves details of reputation jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which reputation jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all reputation jobs in the system or for reputation jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Reputation Jobs operation

 

operation: Get Metadefender Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of Metadefender jobs are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all Metadefender jobs in the system.
ID: Retrieves details of Metadefender jobs in the system based on the Metadefender job ID you specify.
Created: Retrieves details of Metadefender jobs in the system based on the date Metadefender jobs were created.
Priority: Retrieves details of Metadefender jobs in the system based on the priority you specify. All Metadefender jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of Metadefender jobs in the system based on the sample ID you specify.
Status: Retrieves details of Metadefender jobs in the system with the status you specify.
Statuschanged: Retrieves details of Metadefender jobs in the system with the Statuschanged you specify.
User: Retrieves details of Metadefender jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which Metadefender jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all Metadefender jobs in the system or for Metadefender jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Metadefender Jobs operation

 

operation: Get VirusTotal Jobs

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of VirusTotal jobs are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all VirusTotal jobs in the system.
ID: Retrieves details of VirusTotal jobs in the system based on the VirusTotal job ID you specify.
Created: Retrieves details of VirusTotal jobs in the system based on the date Metadefender jobs were created.
Priority: Retrieves details of VirusTotal jobs in the system based on the priority you specify. All VirusTotal jobs that are above or equal to the priority you specify are retrieved from the system.
Sample: Retrieves details of VirusTotal jobs in the system based on the sample ID you specify.
Status: Retrieves details of VirusTotal jobs in the system with the status you specify.
Statuschanged: Retrieves details of VirusTotal jobs in the system with the Statuschanged you specify.
User: Retrieves details of VirusTotal jobs in the system based on the User ID you specify.
Value Specify the value of the parameter you select.
For example, if you select Created, then you have to specify the date on which VirusTotal jobs were created for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all VirusTotal jobs in the system or for VirusTotal jobs you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get VirusTotal Jobs operation

 

operation: Get Tags

Input parameters

 

Parameter Description
Parameters Specify parameters based on which details of tags are retrieved from VMRAY.
Choose from the following options:
All: Retrieves details of all tags in the system.
Name: Retrieves details of tags in the system based on the name of the tag you specify.
Value Specify the value of the parameter you select.
For example, if you select Name, then you have to specify the name of the tag for which you want to retrieve details from VMRAY.
Note: If you specify All then you do not have to specify a value.

 

Output

The JSON output contains the report from VMRAY for all tags in the system or for the tag you have specified using parameters.

Following image displays a sample output:
 

Sample output of the Get Tags operation

 

operation: Get System Information

Input parameters

None.

Output

The JSON output contains the report from VMRAY that returns system-wide information, such as the VMRAY Analyzer version of the running VMRAY server.

Following image displays a sample output:
 

Sample output of the Get System Information operation

 

operation: Delete Job

Input parameters

 

Parameter Description
Parameters Specify parameters based on which a job is deleted from VMRAY.
For this operation, select ID.
Value Specify the ID of the job that you want to delete from the VMRAY.

 

Output

The JSON output returns a Success message if VMRAY successfully deletes the job specified or an Error message containing the reason for failure.

operation: Delete Submission

Input parameters

 

Parameter Description
Parameters Specify parameters based on which a submission is deleted from VMRAY.
For this operation, select ID.
Value Specify the ID of the submission that you want to delete from the VMRAY.

 

Output

The JSON output returns a Success message if VMRAY successfully deletes the submission specified or an Error message containing the reason for failure.

Following image displays a sample output:
 

Sample output of the Delete Submission operation

 

Included playbooks

The Sample-VMRAY-1.0.0 playbook collection comes bundled with the VMRAY 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 VMRAY 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.