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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
