Vmray

VMRay is an advanced threat detection platform that provides dynamic malware analysis and threat intelligence.

VMRay is a leading platform for advanced threat detection and analysis, specializing in dynamic malware analysis and threat intelligence. The VMRay connector for Swimlane Turbine enables seamless integration, allowing users to automate the submission and analysis of files and URLs, retrieve detailed reports, and access threat intelligence data. This integration empowers security teams to enhance their incident response capabilities, streamline threat investigation processes, and improve overall security posture by leveraging VMRay's comprehensive analysis and detection capabilities.

Prerequisites

Before you can use the VMRay connector for Turbine, you'll need access to the VMRay API. This requires the following:

an API key authentication using the following parameters:

URL: The endpoint URL for accessing VMRay services.

API Key: A unique key provided by VMRay for authenticating API requests.

Capabilities

This connector provides the following capabilities:

Email Threat Defender

Get Analysis Report

Get Analysis Results

Get Sample by ID

Get Sample PDF

Get Sample IOCs by Sample ID

Get Sample VMRay Threat Identifiers

Get Submission by ID

MD5 Lookup

Submit URL

Submit File

Additional Information about Capabilities

File Upload requires a valid Sample Type in-order for analysis to be conducted. These are the possible Sample Types:

Unknown

Custom

Excel Document

HTML Application

HTML Application (Shell Link)

HTML Document

JScript

Java Archive

Java Class

MSI Setup

Macromedia Flash

Microsoft Access Database

Microsoft Publisher Document

PDF Document

PowerShell Script ... and so on

About Email Threat Defender fields

You can select which fields to return in the response using the _fields parameter. It takes a list of fields (comma-delimited and in parentheses). Certain fields can also be followed by a list of their subfields. For example, to return only the message ID, verdict, filenames of attachments and verdicts of attachment, use the following parameter:

_fields=(email_message_id,email_verdict,email_attachments(attachment_filename,attachment_verdict))

The following fields and subfields are available:

email_vmray_uuid

email_message_id

email_sent

email_received

email_sensor_id

email_verdict

email_verdict_reached

email_sender

email_recipients

email_subject

email_webif_url

email_headers

header_name

header_value

email_plain_body ... and so on

In order to access the email_plain_body and email_html_body fields, the user has to have the corresponding permission.

Additional Documentation

Vmray Connector Documentation

Vmray API Documentation

Vmray Authentication Guide

Configurations

VMRay API Key Authentication

Authenticates using an API Key

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
x-apikey	API key	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Email Threat Defender

Integrate with VMRay's Email Threat Defender to analyze and mitigate email-based security threats effectively.

Endpoint

URL: /rest/email

Method: GET

Input

Argument Name	Type	Required	Description
parameters._fields	string	Optional	Parameters for the Email Threat Defender action

Input Example

{"parameters":{"_fields":"(email_message_id)"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Get File Analysis Report

Retrieve a detailed file analysis report from VMRay using the provided unique identifier.

Endpoint

URL: /rest/analysis/{{id}}/archive/logs/summary.json

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get File Analysis Report action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Get File Analysis Results

Retrieve detailed file analysis results from VMRay using the provided unique identifier.

Endpoint

URL: /rest/analysis/sample/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get File Analysis Results action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Get Sample by ID

Retrieve a specific malware sample from VMRay using the provided Sample ID.

Endpoint

URL: /rest/sample/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get Sample by ID action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Get Sample IOCs by Sample ID

Retrieve Indicators of Compromise (IOCs) for a specific sample ID from VMRay using the required 'sample_id' path parameter.

Endpoint

URL: /rest/sample/{{sample_id}}/iocs

Method: GET

Input

Argument Name	Type	Required	Description
parameters.all_artifacts	boolean	Optional	Parameters for the Get Sample IOCs by Sample ID action
parameters.ioc_severity	string	Optional	Parameters for the Get Sample IOCs by Sample ID action
parameters.ioc_type	string	Optional	Parameters for the Get Sample IOCs by Sample ID action
parameters.ioc_verdict	string	Optional	Parameters for the Get Sample IOCs by Sample ID action
path_parameters.sample_id	number	Required	Parameters for the Get Sample IOCs by Sample ID action

Input Example

{"parameters":{"all_artifacts":true,"ioc_severity":"","ioc_type":"files","ioc_verdict":"malicious"},"path_parameters":{"sample_id":123}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 06 March 2025 20:11:44 GMT","Content-Type":"application/json","Content-Length":"144"},"reason":"OK","json_body":{}}

Get Sample PDF

Retrieve a PDF report for a specific sample in VMRay using the provided Sample ID.

Endpoint

URL: /rest/sample/{{id}}/report

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get Sample PDF action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
file	object	Attachments
file.file	string	Output field: file.file
file.file_name	string	Name of the resource
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Get Sample VMRay Threat Identifiers

Retrieve threat identifiers for a specific sample in VMRay using the provided sample ID.

Endpoint

URL: /rest/sample/{{sample_id}}/vtis

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.sample_id	number	Required	Parameters for the Get Sample VMRay Threat Identifiers action

Input Example

{"path_parameters":{"sample_id":123}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{"Date":"Mon, 06 March 2025 20:11:44 GMT","Content-Type":"application/json","Content-Length":"144"},"reason":"OK","json_body":{}}

Get Submission by ID

Retrieve detailed data for a specific submission in VMRay using the provided unique Submission ID.

Endpoint

URL: /rest/submission/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get Submission by ID action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

MD5 Lookup

Retrieve a sample associated with a specified MD5 hash from VMRay using the 'id' path parameter.

Endpoint

URL: /rest/sample/md5/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the MD5 Lookup action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Submit File

Submit a file to VMRay for detailed analysis, specifying submission type and reanalysis options with required JSON body and file attachment.

Endpoint

URL: /rest/sample/submit

Method: POST

Input

Argument Name	Type	Required	Description
files	array	Required	File to be uploaded
files.file	string	Optional	Parameter for Submit File
files.file_name	string	Optional	Name of the resource
submission_type	string	Optional	Type of the resource
reanalyze	boolean	Optional	Parameter for Submit File

Input Example

{"json_body":{"submission_type":"string","reanalyze":false}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.errors	array	Response data
data.jobs	array	Response data
data.jobs.job_account_id	number	Response data
data.jobs.job_analyzer_id	number	Response data
data.jobs.job_analyzer_name	string	Response data
data.jobs.job_bill_id	number	Response data
data.jobs.job_bill_type	string	Response data
data.jobs.job_configuration_description	string	Response data
data.jobs.job_configuration_id	number	Response data
data.jobs.job_configuration_name	string	Response data
data.jobs.job_created	string	Response data
data.jobs.job_document_password	object	Response data
data.jobs.job_enable_custom_av	boolean	Response data
data.jobs.job_enable_local_av	boolean	Response data
data.jobs.job_id	number	Response data
data.jobs.job_jobrule_id	number	Response data
data.jobs.job_jobrule_sampletype	string	Response data
data.jobs.job_parent_analysis_id	object	Response data
data.jobs.job_prescript_force_admin	boolean	Response data
data.jobs.job_prescript_id	object	Response data
data.jobs.job_priority	number	Response data
data.jobs.job_quota_type	string	Response data

Output Example

{"data":{"errors":["string"],"jobs":[{}],"md_jobs":["string"],"reputation_jobs":["string"],"samples":[{}],"static_jobs":[{}],"submissions":[{}],"vt_jobs":["string"],"whois_jobs":["string"]},"result":"string"}

Submit URL

Submit a URL to VMRay for analysis and categorize the content based on the provided sample type and URL.

Endpoint

URL: /rest/sample/submit

Method: POST

Input

Argument Name	Type	Required	Description
sample_url	string	Optional	URL endpoint for the request
sample_type	string	Optional	Type of the resource

Input Example

{"sample_url":"string","sample_type":"url"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{}}

Response Headers

Header	Description	Example
Connection	HTTP response header: Connection
Content-Length	The length of the response body in bytes	144
Content-Security-Policy	HTTP response header: Content-Security-Policy
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Mon, 06 March 2025 20:11:44 GMT
Referrer-Policy	HTTP response header: Referrer-Policy
Server	Information about the software used by the origin server
Set-Cookie	HTTP response header: Set-Cookie
Strict-Transport-Security	HTTP response header: Strict-Transport-Security
Vary	HTTP response header: Vary
X-Content-Type-Options	HTTP response header: X-Content-Type-Options
X-Frame-Options	HTTP response header: X-Frame-Options
X-XSS-Protection	HTTP response header: X-XSS-Protection