Skip to main content
API docs by Redocly

Spectra Intelligence API reference (5.0.0)

Download OpenAPI specification:Download

ReversingLabs: support@reversinglabs.com License: ReversingLabs End-User Software License Agreement

ReversingLabs Spectra Intelligence offers REST web services providing file reputation, file analysis, malware hunting and network indicator information. These can be used for incident response triage, malware analysis, threat intelligence augmentation, and other uses. The output format of API results is either XML or JSON.

Complete documentation

File Threat Intelligence

Get file reputation insights from ReversingLabs

TCA-0101: File Reputation (single query)

The File Reputation (Malware Presence) API provides file reputation status calculated by a proprietary ReversingLabs algorithm for the requested sample. The status can be: MALICIOUS, SUSPICIOUS, KNOWN (non-malicious or benign), UNKNOWN. Additional classification-related metadata and hashes can be requested using optional parameters.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

extended
boolean
Default: false
Example: extended=true

Optional parameter that specifies whether additional classification metadata for the requested sample should be returned in the response. Additional metadata includes information such as trust factor and threat level values; malware type, family name, and platform; first and last seen times, and more. If the parameter is not provided in the request, the default value is false (additional metadata is not returned).

show_hashes
boolean
Default: false
Example: show_hashes=true

Optional parameter that specifies whether MD5, SHA1, and SHA256 hashes should be returned in the response for the requested sample, in addition to the rest of the Malware Presence information. If the parameter is not provided in the request, the default value is false (hashes are not returned).

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/databrowser/malware_presence/query/sha1/2cfbb1d2ee28644934bbd3baf6a6667905eee27b?extended=true&show_hashes=true&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0101: File Reputation (bulk query)

The File Reputation (Malware Presence) Bulk API provides file reputation status calculated by a proprietary ReversingLabs algorithm for the requested samples. Up to 100 hashes can be submitted in one request. The status can be: MALICIOUS, SUSPICIOUS, KNOWN (non-malicious or benign), UNKNOWN. Additional classification-related metadata and hashes can be requested using optional parameters.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

extended
boolean
Default: false
Example: extended=true

Optional parameter that specifies whether additional classification metadata for the requested sample should be returned in the response. Additional metadata includes information such as trust factor and threat level values; malware type, family name, and platform; first and last seen times, and more. If the parameter is not provided in the request, the default value is false (additional metadata is not returned).

show_hashes
boolean
Default: false
Example: show_hashes=true

Optional parameter that specifies whether MD5, SHA1, and SHA256 hashes should be returned in the response for the requested sample, in addition to the rest of the Malware Presence information. If the parameter is not provided in the request, the default value is false (hashes are not returned).

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0102: File Reputation Override

The File Reputation Override (Malware Presence) API enables file reputation status override for the requested samples. Up to 100 hashes can be submitted in one request. The status can be: MALICIOUS, SUSPICIOUS, or KNOWN (non-malicious or benign). Additional classification-related metadata and can be specified using optional parameters.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Request Body schema: application/json
required

override_samples is an array of samples to override. Each sample must be defined by sha1, md5, and sha256, and include new status for those hashes and may include threat_name, threat_level and trust_factor depending on the status value. remove_override is an array of samples which already have an override that should be removed. Each sample must be defined by sha1, md5 and sha256. Up to 100 hashes can be submitted in one request.

required
object
required
object
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0102: File Reputation Override (list)

The File Reputation Override (list) API lists all existing file reputation status overrides for the requested user. The hashes are sorted. Up to 1000 hashes will be returned. If there are more than 1000 active overrides, next_hash value in the previous response may be provided as the start_hash of the subsequent request to enumerate all hashes. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "xml" "json"

Required parameter that defines the type of hash to be returned. Supported options are sha1, md5, and sha256.

query Parameters
start_hash
string
Example: start_hash=9865c7ecda437034e1513cc43ae9a1f6f334bb7f

Optional parameter that specified the first hash in the response to be returned. Enables pagination.

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/databrowser/malware_presence/user_override/list_hashes/sha1?start_hash=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0103: Historic Multi-AV Scan Records (single query)

The Historic Multi-AV Scan Records (XREF) API provides cross-reference data (AV scanner scanning information, first and last seen date-time (UTC), sample type and size, first and last scanned date, etc.) for the requested sample. An optional parameter history can be used in requests to this API to retrieve historical XREF record changes for the sample (if available).

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

history
boolean
Default: false
Example: history=true

Optional parameter that defines whether the response should contain a history of XREF records for a sample (when true) or the latest record only (when false). The default is false.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json&history=true' --user <username>:<password>

Response samples

Content type
application/json
No sample

TCA-0103: Historic Multi-AV Scan Records (bulk query)

The Historic Multi-AV Scan Records Bulk API provides cross-reference data (AV scanner scanning information, first and last seen date-time (UTC), sample type and size, first and last scanned date, etc.) for up to 100 requested samples. An optional parameter history can be used in requests to this API to retrieve historical XREF record changes for each sample (if available).

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

history
boolean
Default: false
Example: history=true

Optional parameter that defines whether the response should contain a history of XREF records for a sample (when true) or the latest record only (when false). The default is false.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
{
  • "rl": {
    }
}

TCA-0104: File Analysis - Hash (single query)

The File Analysis - Hash [RLDATA] API provides analysis results for the requested hash. The extent of analysis data returned in the response varies based on the file type. Note that the dynamic analysis report is only available with additional permissions.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/databrowser/rldata/query/sha1/a45ab18fb7a06dd5ecb44bf6c221a951f974059f?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0104: File Analysis - Hash (bulk query)

The File Analysis - Hash [RLDATA] Bulk API provides analysis results for up to 100 requested hashes in a single response. The extent of analysis data returned in the response varies based on the file type. Note that the dynamic analysis report is only available with additional permissions. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0105: File Analysis - Non-Malicious (single query)

The File Analysis - Non-Malicious [RLDATA Goodware] API provides sample hashes, trust factor, relationships, size, and sources for benign samples only. If a malicious hash is queried, a 404 (Not Found) HTTP response will be returned.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json' --user <username>:<password> --header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0105: File Analysis - Non-Malicious (bulk query)

The File Analysis - Non-Malicious [RLDATA Goodware] Bulk API provides sample hashes, trust factor, relationships, size, and sources for benign samples only. Up to 100 hashes can be submitted in one request. If a malicious hash is queried, a 404 (Not Found) HTTP response will be returned. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

Certificate Threat Intelligence

Get file certificate insights from ReversingLabs

TCA-0501: Certificate Index

The Certificate Index API provides a list of samples that are signed with the requested certificate. The certificate should be requested using its thumbprint value as a SHA1, SHA256, or MD5 hash. Only one certificate thumbprint can be submitted in one request. Optional parameters can be used in the request to retrieve additional sample metadata and filter the results by classification status.

Authorizations:
BasicAuth
path Parameters
thumbprint
required
string

Required parameter that specifies the thumbprint of the certificate for which the user is requesting data from the service. The thumbprint value should be provided as a valid hash. Supported hash types are: MD5, SHA1, SHA256.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=50

Optional parameter; specifies the maximum number of sample SHA1 hashes to include in the response. This value has to be an integer in the range from 1 and 100. When the parameter is not included in the request, 100 hashes are returned by default.

extended
boolean
Default: false
Example: extended=true

If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata: certificate validation status, classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform; SHA1, MD5, PE_SHA1, PE_SHA256 and SHA256 hashes; sample size, sample type, download availability, first and last seen dates (UTC).

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/certificate/index/v1/query/thumbprint/A909502DD82AE41433E6F83886B00D4277A32A7B?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0501: Certificate Index (paginated)

The Certificate Index API provides a list of samples that are signed with the requested certificate. The certificate should be requested using its thumbprint value as a SHA1, SHA256, or MD5 hash. Only one certificate thumbprint can be submitted in one request. Optional parameters can be used in the request to retrieve additional sample metadata and filter the results by classification status.

Authorizations:
BasicAuth
path Parameters
thumbprint
required
string

Required parameter that specifies the thumbprint of the certificate for which the user is requesting data from the service. The thumbprint value should be provided as a valid hash. Supported hash types are: MD5, SHA1, SHA256.

page
string

Optional parameter used for pagination. To get the next page of results from the API, use the next_page value from the response with this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=50

Optional parameter; specifies the maximum number of sample SHA1 hashes to include in the response. This value has to be an integer in the range from 1 and 100. When the parameter is not included in the request, 100 hashes are returned by default.

extended
boolean
Default: false
Example: extended=true

If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata: certificate validation status, classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform; SHA1, MD5, PE_SHA1, PE_SHA256 and SHA256 hashes; sample size, sample type, download availability, first and last seen dates (UTC).

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/certificate/index/v1/query/thumbprint/A909502DD82AE41433E6F83886B00D4277A32A7B?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0502: Certificate Analytics

The Certificate Analytics API provides certificate analytics for the requested certificate and its chain of trust. The certificate should be requested using its thumbprint value as a SHA1, SHA256, or MD5 hash. Sending requests using the GET method allows only one thumbprint per request, while the POST method accepts up to 100 thumbprints in one request. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
thumbprint
required
string

Required parameter that specifies the thumbprint of the certificate for which the user is requesting data from the service. The thumbprint value should be provided as a valid hash. Supported hash types are: MD5, SHA1, SHA256.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/certificate/analytics/v1/query/thumbprint/18254B1DC375B74E339EB99ABFE31AF0D735CB5A3B535570731175811D735B0D?format=json' --user <username>:<password> --header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0502: Certificate Analytics

The Certificate Analytics API provides certificate analytics for the requested certificate and its chain of trust. The certificate should be requested using its thumbprint value as a SHA1, SHA256, or MD5 hash. Sending requests using the GET method allows only one thumbprint per request, while the POST method accepts up to 100 thumbprints in one request. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
thumbprint
required
string
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required

thumbprints is a required parameter that specifies a list of certificate thumbprints for which the user is requesting data from the service. Each thumbprint value should be provided as a valid hash. Supported hash types are: MD5, SHA1, SHA256. Up to 100 thumbprints can be submitted in one request.

required
object
required
object
thumbprints
required
Array of objects
format
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0503: Certificate Thumbprint Search

The Certificate Thumbprint Search API allows users to find certificate thumbprints by using the full or partial certificate common name as the search keyword. The results contain thumbprints of certificates that match the requested common name. Those thumbprints can be used with the TCA-0501 and TCA-0502 APIs to obtain a list of certificate-signed samples and certificate analytics, respectively.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
common_name
required
string

common_name is a required parameter that supports partial matching with * as the wildcard character. limit is an optional parameter that specifies the maximum number of thumbprints to return in the response (1-100, with 100 as the default).

limit
integer [ 1 .. 100 ]
Default: 100

Maximum number of certificate thumbprints to be returned.

page_common_name
string

An optional pagination parameter for retrieving the next page of the results. Pagination value for the next page is provided in the previous request response as next_page_common_name.

page_thumbprint
string

An optional pagination parameter for retrieving the next page of the results. Pagination value for the next page is provided in the previous request response as next_page_thumbprint.

response_format
string
Default: "xml"
Enum: "xml" "json"

response_format is an optional parameter that allows choosing the response format (XML or JSON; XML is the default).

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Network Threat Intelligence

Find files in Spectra Intelligence using network indicator metadata

TCA-0401: URI to Hash Search

The URI to Hash Search API provides a list of all available SHA1 hashes associated with the requested URI. The following URI types are supported: email, URL, IPv4 address, domain. Only one URI can be submitted in one request. Sending requests using the GET method requires the SHA1 value of the URI string, while the POST method accepts the URI string value in plain text.

Authorizations:
BasicAuth
path Parameters
hash
required
string

SHA1 hash value of the URI string for which the user is requesting data from the service. The user should generate a SHA1 hash of the URI string prior to submitting a request.

query Parameters
classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/uri_index/v1/query/c2208abde9668e8e9815c3690855edd1e63abeac?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0401: URI to Hash Search (paginated)

The URI to Hash Search API provides a list of all available SHA1 hashes associated with the requested URI. The following URI types are supported: email, URL, IPv4 address, domain. Only one URI can be submitted in one request. Sending requests using the GET method requires the SHA1 value of the URI string, while the POST method accepts the URI string value in plain text. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash
required
string

Next page hash value.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

header Parameters
Content-Type:
required
string
Enum: "application/json" "text/xml"

Required parameter that defines the POST payload format.

Request Body schema: application/json
required
object
object
uri
required
string

uri is a required parameter used to submit a plain text URI for which the user is requesting data from the service. Only one URI can be submitted in one request. Supported URI types are: email (e.g., user@domain.com), URL (e.g., http://domain.com/download/picture.jpg), IPv4 address (e.g., 127.0.0.1), domain (e.g., domain.com).

next_page_sha1
string

next_page_sha1 is an optional parameter used for pagination. To get the next page of results from the API, use the next_page_sha1 value from the response with this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0401: URI to Hash Search

The URI to Hash Search service provides a list of all available SHA1 hashes associated with the requested URI. This service takes into account network IOCs extracted during file static analysis and uses that data to correlate URIs with samples. The following URI types are supported: email, URL, IPv4 address, and domain. Only one URI can be submitted in one request. Find more information in the official API documentation.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

header Parameters
Content-Type:
required
string
Enum: "application/json" "text/xml"

Required parameter that defines the POST payload format.

Request Body schema: application/json
required
object
object
uri
required
string

uri is a required parameter used to submit a plain text URI for which the user is requesting data from the service. Only one URI can be submitted in one request. Supported URI types are: email (e.g., user@domain.com), URL (e.g., http://domain.com/download/picture.jpg), IPv4 address (e.g., 127.0.0.1), domain (e.g., domain.com).

next_page_sha1
string

next_page_sha1 is an optional parameter used for pagination. To get the next page of results from the API, use the next_page_sha1 value from the response with this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0401: URI to Hash Search (paginated)

The URI to Hash Search API provides a list of all available SHA1 hashes associated with the requested URI. The following URI types are supported: email, URL, IPv4 address, domain. Only one URI can be submitted in one request. Sending requests using the GET method requires the SHA1 value of the URI string, while the POST method accepts the URI string value in plain text.

Authorizations:
BasicAuth
path Parameters
uri_sha1
required
string

The SHA1 hash value of the URI string

next_page_sha1
required
string

Optional path parameter used for pagination. To get the next page of results from the API, use the next_page_sha1 value from the response in place of this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

query Parameters
classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/uri_index/v1/query/c2208abde9668e8e9815c3690855edd1e63abeac?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0402: URI Statistics

The URI Statistics API provides statistical information on how many known, malicious, and suspicious samples are associated with a particular URI. The following URI types are supported: email, URL, IPv4 address, domain. Only one URI can be submitted in one request. This service accepts only SHA1 values of URI strings. Requested URI strings cannot be in plain text. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
uri_sha1
required
string

The SHA1 hash value of the URI string for which the user is requesting data from the service. The user should generate a SHA1 hash of the URI string prior to submitting a request. Supported URI types are: email (e.g., user@domain.com), URL (e.g., http://domain.com/download/picture.jpg), IPv4 address (e.g., 127.0.0.1), domain (e.g., domain.com).

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/uri/statistics/uri_state/sha1/234988566c9a0a9cf952cec82b143bf9c207ac16?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0403: URL Threat Intelligence (report)

This service returns the report for the submitted URL. The report contains the ReversingLabs URL classification status, URL reputation from various reputation sources, metadata for performed URL analyses, statistics of files found on the submitted URL mapped to their classification, and an overview of the most common threats.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
url
required
string <uri>
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0403: URL Threat Intelligence (downloaded files)

This service provides a list of hashes for files downloaded from the submitted URL, across all analyses, during the last analysis, or those downloaded during a specific analysis.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
url
string <uri>

Cannot be used in combination with analysis_id.

analysis_id
string

Cannot be used in combination with url.

last_analysis
boolean
Default: false
response_format
string
Default: "xml"
Enum: "json" "xml"
limit
integer
Default: 1000
classification
string
Enum: "KNOWN" "SUSPICIOUS" "MALICIOUS" "UNKNOWN"
extended
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0403: URL Threat Intelligence (notifications) (time range)

This service provides a continuous list of completed analyses. The records enter the feed once the submitted URL is analyzed to completion and the report is ready.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string <Unix timestamp OR date-time>

Accepts values formatted according to the format set in the time_format parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Specifies the maximum number of reports to return in the response.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/networking/url/v1/notifications/query/latest?limit=1' --user <username>:<password>

Response samples

Content type
application/json
{}

TCA-0403: URL Threat Intelligence (notifications) (time range) (paginated)

This service provides a continuous list of completed analyses. The records enter the feed once the submitted URL is analyzed to completion and the report is ready.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string

Accepts values formatted according to the format set in the time_format parameter.

page
required
string

The pagination value for the next page is provided in the previous request response

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Specifies the maximum number of reports to return in the response.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/networking/url/v1/notifications/query/latest?limit=1' --user <username>:<password>

Response samples

Content type
application/json
{}

TCA-0403: URL Threat Intelligence (notifications) (latest)

This service provides a continuous list of completed analyses. The records enter the feed once the submitted URL is analyzed to completion and the report is ready.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Specifies the maximum number of reports to return in the response.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/networking/url/v1/notifications/query/latest?limit=1' --user <username>:<password>

Response samples

Content type
application/json
{}

TCA-0403: URL Threat Intelligence (notifications) (latest) (paginated)

This service provides a continuous list of completed analyses. The records enter the feed once the submitted URL is analyzed to completion and the report is ready.

Authorizations:
BasicAuth
path Parameters
page
required
string
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Specifies the maximum number of reports to return in the response.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/networking/url/v1/notifications/query/latest?limit=1' --user <username>:<password>

Response samples

Content type
application/json
{}

TCA-0404: Analyze URL

This service allows users to submit a URL for analysis. The analysis is a crawling process that will start looking for files to download from the submitted URL. When downloaded, the files are sent for analysis to the ReversingLabs file processing pipeline.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST body format.

header Parameters
Content-Type
required
string
Value: "application/octet-stream"

Required parameter that defines the POST payload format.

Request Body schema: application/json
required
object
object
url
required
string <uri>
response_format
required
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

TCA-0405 Domain Threat Intelligence (resolutions)

This service provides a list of domain-to-IP mappings for the requested domain.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
domain
string
limit
integer
Default: 1000
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0405 Domain Threat Intelligence (URLs)

This service provides a list of URLs associated with the requested domain.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
domain
string
response_format
string
limit
integer

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0405 Domain Threat Intelligence (report)

This service returns threat intelligence data for the submitted domain. The report contains domain reputation from various reputation sources, classification statistics for files downloaded from the domain, the most common threats found on the domain DNS information about the domain, and parent domain information.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
domain
string
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0405 Domain Threat Intelligence (downloaded files)

This service provides a list of hashes for files downloaded from the submitted domain.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
domain
string
limit
integer
extended
boolean
classification
string
response_format
string

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0406 IP Threat Intelligence (resolutions)

This service provides a list of IP-to-domain mappings for the specified IP.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
ip
string
limit
integer
Default: 1000
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0406 IP Threat Intelligence (URLs)

This service provides a list of URLs associated with the requested IP. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
ip
string
limit
integer
Default: 1000
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0406 IP Threat Intelligence (report)

This service returns threat intelligence data for the submitted IP. The report contains IP reputation from various reputation sources, classification statistics for files downloaded from the IP, and the top threats hosted on the submitted IP.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
ip
string
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0406 IP Threat Intelligence (downloaded files)

This service provides a list of hashes for files downloaded from the submitted IP address.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
required
object
required
object
ip
required
string
limit
integer
Default: 1000
response_format
string
Default: "xml"
Enum: "json" "xml"
classification
string
Enum: "KNOWN" "SUSPICIOUS" "MALICIOUS" "UNKNOWN"
extended
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0407: Network Reputation API

The Network Reputation service provides information regarding the reputation of a requested URL, domain, or IP address. When a URL is submitted, the service provides its ReversingLabs classification, along with an overview of detections from our partners. It also includes the category of the URL (for example phishing, gambling, adult content) and indicates whether we have encountered any malware samples associated with the submitted URL.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
object
object
required
Array of objects <= 100 items
response_format
string
Default: "xml"
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0408: Network Reputation User Override

The Network Reputation User Override service enables URL classification overrides. Any URL can be overridden to malicious, suspicious, or known. Overrides are visible to all users within the same organization. The service also supports listing existing overrides.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required
object
object
response_format
string
Enum: "json" "xml"

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0408: List User Overrides

The Network Reputation User Override service enables URL classification overrides. Any URL can be overridden to malicious, suspicious, or known. Overrides are visible to all users within the same organization. The service also supports listing existing overrides.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

next_network_location
string <sha1>

Optional parameter used for pagination. To get the next page of results from the API, use the next_network_location value from the response in place of this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/networking/user_override/v1/query/list_overrides?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Automation

Manage files in Spectra Intelligence

TCA-0201: File Download Request

The External Sample Exchange Service allows users to download files from ReversingLabs Spectra Intelligence. This query returns the contents of a file matching the requested hash. The contents are returned as a byte stream. Only one file can be downloaded per request.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/spex/download/v2/query/sha1/a45ab18fb7a06dd5ecb44bf6c221a951f974059f' --user <username>:<password>

TCA-0201: File Download Status Request

The External Sample Exchange Service allows users to download files from ReversingLabs Spectra Intelligence. This query returns the file size of samples matching the requested hash values, but only if they are available for download. If the requested samples are not available for download, their size is represented as -1 in the response. Up to 1000 hashes can be submitted in one download status request.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl -X POST --url 'https://data.reversinglabs.com/api/spex/download/v2/status/bulk_query/json' --header 'Content-Type: application/json' --data '{
  "rl": {
    "query": {
      "hash_type": "sha1",
      "hashes": [
        "a7afddb68260a60f86c02a021efba7f216c2e7cf",
        "ca03064987d3c4465f91552ba8b6a883eecfd3e5",
        "b363713a938afcd3c74603827fab79e935b2b09b"
      ]
    }
  }
}' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0202/0203: File Upload Request

The External Sample Exchange Service allows users to upload files to Spectra Intelligence. This query uploads the file contents using a byte stream and the SHA1 hash of the file provided in the request. The file metadata must be uploaded after the file contents in a separate request for file processing to occur. Depending on the user's Spectra Intelligence account configuration, files are uploaded as public (sent to TCA-0202), or private (sent to TCA-0203).

Authorizations:
BasicAuth
path Parameters
hash_value
required
string

Must be a valid SHA1 hash of the uploaded file.

Request Body schema: application/octet-stream
required
string <binary>

Responses

Request samples 

curl --request POST 'https://data.reversinglabs.com/api/spex/upload/3715b867a6ce91aec3ce21d3703c68f80cf1cbc6' --data-binary @example_file.tar.gz --user <username>:<password>

TCA-0202/0203: File Metadata Upload Request

The External Sample Exchange Service allows users to upload files from ReversingLabs Spectra Intelligence. This query uploads the metadata of the file that matches the SHA1 hash provided in the request. Metadata must be provided in the XML format. The file metadata must be uploaded after the file contents in a separate request for file processing to occur. Depending on the user's Spectra Intelligence account configuration, files are uploaded as public (sent to TCA-0202), or private (sent to TCA-0203).

Authorizations:
BasicAuth
path Parameters
hash_value
required
string

Must be a valid SHA1 hash of a previously uploaded file.

query Parameters
subscribe
string
Value: "data_change"

Optional parameter. If set, adds the file to the user's data_change feed subscription list.

Request Body schema: application/octet-stream
required

Metadata must be provided in the XML format, while the request for the metadata must be sent using the Content-Type: application/octet-stream header. Metadata must contain the domain field and at least one property field. When submitting an archive for upload, it is recommended to include the archive object when uploading sample metadata. If not included, the sample will be processed as a regular sample and not as an archive, therefore it is possible that the content of the zip will not be processed completely.

The domain name should represent the web domain where the sample was found/downloaded. If the domain name is not known, the domain name should be set to an empty string.

The property_name and property_value can be any kind of string. They can represent some properties of the sample, such as its application name, version, file name of the sample, or tags.

The archive_type specifies the compression algorithm used to create the archive, and is a mandatory field if the archive field is provided. The archive_password is the password used to extract the content, and is optional.

object
required
object
domain
required
string
object

Responses

Request samples

Content type
application/octet-stream
<rl>
  <properties>
    <property>
      <name>application</name>
      <value>TestApplication</value>
    </property>
    <property>
      <name>author</name>
      <value>Test_Author</value>
    </property>
  </properties>
  <domain>testdomain.com</domain>
  <archive>
    <archive_type>zip</archive_type>
    <archive_password>password123</archive_password>
  </archive>
</rl>

TCA-0204: Delete File Single Query

The Delete File API provides the functionality of deleting files submitted and owned exclusively by the user sending the request. This query allows the user to delete a single file.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

delete_on
string
Example: delete_on=1437464369

Optional parameter that specifies when the file will be deleted, allowing users to schedule file removal for a specific time. Expressed as a Unix timestamp in seconds.

Responses

Request samples 

curl --request DELETE --url 'https://data.reversinglabs.com/api/delete/sample/v1/query/sha1/bc7a6c7bba614456412fcd11d870f207be1bf6a5' --user <username>:<password>

TCA-0204: Delete File Bulk Query

The Delete File API provides the functionality of deleting files submitted and owned exclusively by the user sending the request. Up to 100 hashes can be submitted in one request.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0205: Re-Analyze File Single Query

The Rescan API allows users to submit files for re-analysis in the ReversingLabs Spectra Intelligence system. Re-analysis includes all components of the ReversingLabs Classification Algorithm: Spectra Intelligence antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/rescan/v1/query/sha1/289512144b8b4e9e25e7a7d6250da24cda02eee0' --user <username>:<password>

TCA-0205: Re-Analyze File Bulk Query

The Rescan API allows users to submit files for (re)analysis in the ReversingLabs Spectra Intelligence system. Up to 100 hashes can be submitted in one request. Re-analysis includes all components of the ReversingLabs Classification Algorithm: Spectra Intelligence antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0206: Alert Subscribe Query

This query is used for subscribing to a list of samples and URLs for which the changed sections (if there are any) will be delivered in the Data Change Feed. To subscribe to a list of samples or URLs, the user should submit the sample or URL hashes in a POST request. All hashes in a request should be of the same type. The maximum amount of hashes that can be submitted in one request is 100.

Subscriptions never expire on their own. Users need to manually unsubscribe using the TCA-0206 Unsubscribe Query. Note: Samples or URLs that have not yet been seen can be subscribed to only using SHA1 hash values.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0206: Alert Unsubscribe Query

This query is used for unsubscribing from a list of samples that the user was previously subscribed to. Submitting a sample hash in a POST request to this endpoint removes the associated sample from the list of user's subscriptions.

The maximum amount of hashes that can be submitted in one request is 100. Changes for unsubscribed samples will no longer be delivered in the Data Change Feed.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0206: Data Change Feed Start Query

This query sets the starting timestamp for TCA-0206 Data Change Feed Pull Query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter; accepts these options: timestamp, utc. timestamp is the number of seconds since 1970-01-01 00:00:00. utc is the date and time in format YYYY-MM-DDThh:mm:ss

time_value
required
string

Required parameter; Accepts values defined by the time_format parameter

Responses

Request samples 

curl --request PUT --url 'https://data.reversinglabs.com/api/feed/data_change/v3/start/timestamp/1640991600' --user <username>:<password>

TCA-0206: Data Change Feed Pull Query

This query returns the next recordset with samples and URLs to which the user is subscribed. The starting point for this query is defined using the TCA-0206 Start Query.

If the user has not previously requested this query or called the START query, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended.

Unless the limit parameter is specified, the query returns a maximum of 1000 records, or a little bit more than 1000 if there are records with the same timestamp. This ensures that all the records with the same timestamp will be included in the recordset. The limit parameter must not be greater than 1000.

This endpoint is built to be queried by a single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled.

Authorizations:
BasicAuth
query Parameters
events
string
Default: "default"
Enum: "default" "sections"

Optional parameter that accepts a list of sections that should be included in the response, delimited by commas. Supported values: default - all events will be included in the response; sections - include info, sources, xref, analysis, sample_available, malware_presence, sample_became_shareable, dynamic_analysis

format
string
Default: "xml"
Enum: "xml" "json" "tsv"

Optional parameter; Specifies the response format. Supported values: xml (default), json, tsv (Tab Separated Values, delimiter character \t 0x09)

limit
integer [ 1 .. 1000 ]
Default: 1000

Optional parameter; Specifies the number of records to return in the response. The maximum value is 1000. Note that the response may include a little more than the requested number of records to ensure that all the records with the same timestamp are returned.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0206: Data Change Continuous Feed Query

This query returns a recordset with samples and URLs that the user is subscribed to from the requested timestamp onwards. The feed will return 1000 records at most, or a little bit more than 1000 if there are some records with the same timestamp. The response also contains the latest timestamp up to which the events are included in the response.

To fetch the next recordset, use the the last_timestamp value from the response, increase it by 1 and submit it in a new request.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter; accepts these options: timestamp, utc. timestamp is the number of seconds since 1970-01-01 00:00:00. utc is the date and time in format YYYY-MM-DDThh:mm:ss

time_value
required
string

Required parameter; Accepts values defined by the time_format parameter

query Parameters
events
string
Default: "default"
Enum: "default" "sections"

Optional parameter that accepts a list of sections that should be included in the response, delimited by commas. Supported values: default - all events will be included in the response; sections - include info, sources, xref, analysis, sample_available, malware_presence, sample_became_shareable, dynamic_analysis

format
string
Default: "xml"
Enum: "xml" "json" "tsv"

Optional parameter; Specifies the response format. Supported values: xml (default), json, tsv (Tab Separated Values, delimiter character \t 0x09)

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/feed/data_change/v3/query/utc/2022-01-01T13:00:00?format=json&events=xref' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

Dynamic Analysis (ReversingLabs Cloud Sandbox)

Detonate files in ReversingLabs Cloud Sandbox and retrieve reports

TCA-0106: Dynamic Analysis Report

The File and URL Dynamic Analysis Report service allows users to retrieve dynamic analysis reports for files and URLs executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Value: "sha1"

Required parameter. Specifies which hash type will be used in the request. Supported values: sha1.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

artifacts_url
string
Value: true

Optional parameter that includes artifact links for specific reports in the history part of the merged report. Supported values: True.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/query/sha1/cac61424fb5414d589687bfd35452a351604ef11?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0106: File/URL Dynamic Analysis Report (specific report)

The File and URL Dynamic Analysis Report service allows users to retrieve dynamic analysis reports for files and URLs executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Value: "sha1"

Required parameter. Specifies which hash type will be used in the request. Supported values: sha1.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

required
string or string

If added at the end of the request, the response will contain either the latest dynamic analysis report, or the report matching the provided analysis_id. These two parameters are mutually exclusive.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/query/sha1/cac61424fb5414d589687bfd35452a351604ef11/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0106: URL Dynamic Analysis Report (BASE64)

The URL Dynamic Analysis Report (BASE64) service allows users to retrieve dynamic analysis reports for URLs executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
base64_value
required
string

Required parameter. This parameter expects a base64-encoded URL to generate a report of the analyzed URLs.

string or string

If added at the end of the request, the response will contain either the latest dynamic analysis report, or the report matching the provided analysis_id. These two parameters are mutually exclusive.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/query/url/base64/aHR0cDovL3d3dy5nb29nbGUuY29t' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0106: URL Dynamic Analysis Report (SHA1)

The URL Dynamic Analysis Report (SHA1) service allows users to retrieve dynamic analysis reports for URLs executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
sha1_value
required
string

Required parameter. This parameter expects a SHA1 hash value to generate a report of the analyzed URLs.

string or string

If added at the end of the request, the response will contain either the latest dynamic analysis report, or the report matching the provided analysis_id. These two parameters are mutually exclusive.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/query/url/sha1/171ba7127cf28cc63ea1fef74be9746842f5093f' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0106: Dynamic Analysis Report (archives)

The Dynamic Analysis Report service allows users to retrieve dynamic analysis reports for files executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Value: "sha1"

Required parameter. Specifies which hash type will be used in the request. Supported values: sha1.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/archive/query/sha1/54bdccd42f89242ba21fd1a48fcb438a2a2c1829?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0106: Dynamic Analysis Report (archives) (specific report)

The Dynamic Analysis Report service allows users to retrieve dynamic analysis reports for files executed in the cloud sandbox. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Value: "sha1"

Required parameter. Specifies which hash type will be used in the request. Supported values: sha1.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

required
string or string

If added at the end of the request, the response will contain either the latest dynamic analysis report, or the report matching the provided analysis_id. These two parameters are mutually exclusive.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/dynamic/analysis/report/v1/archive/query/sha1/54bdccd42f89242ba21fd1a48fcb438a2a2c1829?format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0207: File/URL Dynamic Analysis

The File and URL Dynamic Analysis service allows users to detonate a file and URL in the ReversingLabs cloud sandbox. Several different sandbox profiles are available:

  1. Win10 x64 (MS Office 2007, Java 8, update 261, Adobe Reader 2020.012.20048, Firefox 62.0.3, Google Chrome 69.0.3497.100, Microsoft Edge 42.17134.1.0, Internet Explorer 11)
  2. Win7 x64 (build 760, MS Office 2007, Java 7, update 45, Adobe Reader 8.1.2, Firefox 37, Google Chrome 51.0.2704.84, Internet Explorer 8)
  3. macOS 11 (MacOS Big Sur; Safari 14.1.2; Acrobat Reader 22.003.20258) The report about the performed analysis and file behavior can be retrieved using the TCA-0106 Dynamic Analysis Report service. Find more information in the official API documentation.
Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required

Up to 100 hashes can be submitted in one request.

required
File upload (object) or URL upload (object) or URL Base64 upload (object)
One of
sha1
string = 40 characters

SHA1 hash of a file present in Spectra Intelligence. It must match a previously uploaded sample of a supported file type.

platform
string non-empty
Enum: "windows7" "windows10" "macos11"
response_format
string [ 3 .. 4 ] characters
Default: "json"
Enum: "xml" "json"
optional_parameters
string

Additional optional parameters to send with the request. Optional parameters are supported only for file analyses.

internet_simulation=[true/false]: Available only for the SHA1 hash submissions. If internet_simulation is set to true, dynamic analysis will be performed without connecting to the internet and will use a simulated network instead. Setting it to false is the same as omitting it from the request. HTTPS traffic information will not be monitored within the report when using the internet_simulation parameter.

sample_name: Available only for the SHA1 hash submissions. Specifies a custom file name and/or extension for the sample. Custom extensions impact which application will be used to open and run the file.

geolocation: Geographic location associated with the sample's network activity, reflecting the configured country from which the network traffic is egressed, set via VPN or similar routing methods. Supported geographic location values are: us (default), uk, in, br, de, jp, sg, it, es, fr, tor.

locale: Locale setting reflecting the configured OS language, region, and keyboard layout to simulate a specific country or environment for anti-evasion or targeted analysis purposes. Supported locale values are: en-US (default), en-GB, pt-BR, de-DE, ja-JP, it-IT, es-ES, fr-FR.

Responses

Request samples

Content type
application/json
Example
{
  • "rl": {
    }
}

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0207: Dynamic Analysis (archives)

The Dynamic Analysis service allows users to detonate a file in the ReversingLabs cloud sandbox. Several different sandbox profiles are available:

  1. Win10 x64 (MS Office 2007, Java 8, update 261, Adobe Reader 2020.012.20048, Firefox 62.0.3, Google Chrome 69.0.3497.100, Microsoft Edge 42.17134.1.0, Internet Explorer 11)
  2. Win7 x64 (build 760, MS Office 2007, Java 7, update 45, Adobe Reader 8.1.2, Firefox 37, Google Chrome 51.0.2704.84, Internet Explorer 8)
  3. macOS 11 (MacOS Big Sur; Safari 14.1.2; Acrobat Reader 22.003.20258) The report about the performed analysis and file behavior can be retrieved using the TCA-0106 Dynamic Analysis Report service. Find more information in the official API documentation.
Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required

hash_type is a required parameter that specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value is a required parameter that specifies the hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
sha1
required
string = 40 characters

SHA1 hash of a file present in Spectra Intelligence.

platform
required
string non-empty
Enum: "windows7" "windows10" "macos11"
response_format
string [ 3 .. 4 ] characters
Default: "json"
Enum: "xml" "json"
optional_parameters
string

Additional optional parameters to send with the request. Optional parameters are supported only for file analyses.

internet_simulation=[true/false]: Available only for the SHA1 hash submissions. If internet_simulation is set to true, dynamic analysis will be performed without connecting to the internet and will use a simulated network instead. Setting it to false is the same as omitting it from the request. HTTPS traffic information will not be monitored within the report when using the internet_simulation parameter.

sample_name: Available only for the SHA1 hash submissions. Specifies a custom file name and/or extension for the sample. Custom extensions impact which application will be used to open and run the file.

geolocation: Geographic location associated with the sample's network activity, reflecting the configured country from which the network traffic is egressed, set via VPN or similar routing methods. Supported geographic location values are: us (default), uk, in, br, de, jp, sg, it, es, fr, tor.

locale: Locale setting reflecting the configured OS language, region, and keyboard layout to simulate a specific country or environment for anti-evasion or targeted analysis purposes. Supported locale values are: en-US (default), en-GB, pt-BR, de-DE, ja-JP, it-IT, es-ES, fr-FR.

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Malware Hunting

Look up various malware types by multiple criteria

TCA-0301: Group By RHA1 Single Query

The RHA Functional Similarity [Group by RHA1] API provides a list of SHA1 hashes of files that are functionally similar to the requested file (SHA1 hash) at the selected precision level. The files are grouped by their RHA1 hash.

Authorizations:
BasicAuth
path Parameters
rha1_type
required
string

Required parameter. A measure of RHA1 precision level; represents the degree to which a file is functionally similar to another file. A higher precision level will match fewer files, but the files will have more functional similarity. The following precision levels are supported - 25% for PE, MachO and ELF files (expressed as pe01, elf01, machO01), and 50% for PE files (expressed as pe02). This parameter accepts one of the following values: pe01, elf01, machO01, pe02

hash_value
required
string

Required parameter. The value must be a valid SHA1 hash of the sample for which the user is requesting a list of functionally similar samples.

next_page_sha1
required
string

Optional path parameter used for pagination. To get the next page of results from the API, use the next_page_sha1 value from the response in place of this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
integer [ 1 .. 1000 ]
Default: 1000
Example: limit=50

Optional parameter that specifies the maximum number of sample SHA1 hashes to return in the response. This value has to be an integer in the range from 1 and 1000. When the parameter is not included in the request, 1000 hashes are returned in the response.

extended
boolean
Default: "false"
Example: extended=true

Optional parameter. Supported values are true (sends the extended data set in the response) and false (sends only the list of SHA1 hashes). The default is false. If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata: classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform; SHA1, MD5, and SHA256 hashes; sample size, sample type, download availability, first and last seen dates (UTC).

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0302: ImpHash Similarity

The ImpHash Similarity API provides a list of all available SHA1 hashes for the requested import hash (imphash).

Authorizations:
BasicAuth
path Parameters
hash_value
required
string

Required parameter. The value must be a valid ImpHash hash for which the user is requesting a list of SHA1 hashes.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/imphash_index/v1/query/0931e97555ac33eb10aa9539fe890070' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0302: ImpHash Similarity (paginated)

The ImpHash Similarity API provides a list of all available SHA1 hashes for the requested import hash (imphash).

Authorizations:
BasicAuth
path Parameters
hash_value
required
string

Required parameter. The value must be a valid ImpHash hash for which the user is requesting a list of SHA1 hashes.

next_page_sha1
required
string

Optional path parameter used for pagination. To get the next page of results from the API, use the next_page_sha1 value from the response with this parameter in a new request. When the parameter is not included in the request, only the first page of results is returned.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/imphash_index/v1/query/0931e97555ac33eb10aa9539fe890070' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0303: Create a YARA Ruleset

The YARA Ruleset Administration API allows the authenticated user to manage their collection of YARA rulesets in ReversingLabs Spectra Intelligence. All user-submitted rulesets go through a validation phase where they are tested for correctness and efficacy. A ruleset can be declared invalid even if it is syntactically correct, e.g. if it is too broad, and would generate an inordinate amount of matches.

Authorizations:
BasicAuth
Request Body schema: application/json
required
sample_available
boolean
ruleset_name
string
ruleset_sha1
string

Responses

Request samples

Content type
application/json
{
  • "ruleset_name": "string",
  • "text": "string",
  • "sample_available": true
}

Response samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders",
  • "ruleset_sha1": "359ce0caae50b7d35ab21e93589a87e806b536b9",
  • "sample_available": true
}

TCA-0303: Delete a YARA Ruleset

The YARA Ruleset Administration API allows the authenticated user to manage their collection of YARA rulesets in ReversingLabs Spectra Intelligence. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$

Parameter used for getting the information about the specified YARA ruleset. Only one ruleset name can be submitted in each request.

Responses

Request samples 

curl --request DELETE --url 'https://data.reversinglabs.com/api/yara/admin/v1/ruleset/ExampleRulesetName' --user <username>:<password>

TCA-0303: Get Ruleset Information

The YARA Ruleset Administration API allows the authenticated user to manage their collection of YARA rulesets in ReversingLabs Spectra Intelligence. If no parameter is specified, this API will return all the user's YARA rulesets.

Authorizations:
BasicAuth
path Parameters
ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$

Parameter used for getting the information about the specified YARA ruleset. Only one ruleset name can be submitted in each request.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/yara/admin/v1/ruleset/ExampleRulesetName' --user <username>:<password>

Response samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders",
  • "valid": true,
  • "approved": null
}

TCA-0303: Get Ruleset Text

The YARA Ruleset Administration API allows the authenticated user to manage their collection of YARA rulesets in ReversingLabs Spectra Intelligence. If no parameter is specified, this API will return all the user's YARA rulesets.

Authorizations:
BasicAuth
path Parameters
ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$

Parameter used for getting the information about the specified YARA ruleset. Only one ruleset name can be submitted in each request.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/yara/admin/v1/ruleset/ExampleRulesetName' --user <username>:<password>

Response samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders",
  • "valid": true,
  • "approved": null
}

TCA-0303: YARA Matches Feed

The YARA Matches Feed API returns a recordset of YARA ruleset matches in the requested time range for the authenticated user. The feed will return at most 1000 records, starting from the earliest one. However, if a single second contains more than 1000 matches, all of them will be returned in a single query. If a sample was matched by several rulesets, each will produce its own entry in the response.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string

Period between the time specified by this parameter and the request time. The earliest supported time value is May 20 2016 00:00h UTC (timestamp 1463702400). The latest supported time value is 10 seconds before the request time. The value must be in the format specified by the time_format parameter. To get the next page of results, increase the last_timestamp value from the response of the previous request by 1 and use it as the time_value in the next request. The maximum time span for a single request is limited to 24 hours.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/feed/yara/v1/query/timestamp/1463702400?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0305: Malware Family Detection Single Query

The Malware Family Detection API takes a file hash and returns all malware families to which that sample belongs, based on the detections from the latest AV scan.

Authorizations:
BasicAuth
path Parameters
hash_type
required
string
Enum: "md5" "sha1" "sha256"

Required parameter. Specifies which hash type will be used in the request. Supported values: md5, sha1, sha256.

hash_value
required
string

Required parameter. Hash of the file for which the user is requesting data from the service. The value must be a valid hash of the same type specified by the hash_type parameter.

query Parameters
format
string
Default: "json"
Enum: "json" "xml"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, defaults to json.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/malware/family/detection/v1/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0305: Malware Family Detection Bulk Query

The Malware Family Detection API takes a file hash and returns all malware families to which that sample belongs, based on the detections from the latest AV scan. Up to 100 hashes can be submitted in one request. Find more information in the official API documentation.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

query Parameters
format
string
Enum: "xml" "json"

Optional parameter that allows choosing the response format. Supported values: json, xml. When the parameter is not included in the request, the response is in the same format specified by the post_format parameter.

Request Body schema: application/json
required

hashes is an array of valid hashes of the same type as specified in the hash_type parameter.

Up to 100 hashes can be submitted in one request.

required
object
required
object
hash_type
required
string
Enum: "md5" "sha1" "sha256"
hashes
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/octet-stream
{
  "rl": {
    "unknown_hashes": [
      "ca03064987d3c4465f91552ba8b6a883eecfd3e5"
    ],
    "invalid_hashes": [
      "example_of_a_wrong_hash"
    ],
    "entries": [
      {
        "sample": {
          "sha1": "a7afddb68260a60f86c02a021efba7f216c2e7cf",
          "family": {
            "entries": []
          }
        }
      },
      {
        "sample": {
          "sha1": "b363713a938afcd3c74603827fab79e935b2b09b",
          "family": {
            "entries": []
          }
        }
      },
      {
        "sample": {
          "sha1": "1a7f5ebe53169942cd5913844f86d4be857d82d3",
          "family": {
            "entries": [
              "00576ff21",
              "AD",
              "Agent",
              "PossibleThreat PALLAS",
              "BScope Chanitor",
              "WacatacIH S18376626",
              "EmotetCrypt PEF MTB",
              "Agent FCJD",
              "Kryptik D1D3",
              "Emotet 1100"
            ]
          }
        }
      }
    ]
  }
}

TCA-0306: Expression Search Query (time range)

The Expression Search API allows users to find samples in ReversingLabs Spectra Intelligence that match the requested criteria. The service returns only new samples - either samples that were first seen on the requested date, or samples from the last 24 hours - and does not include old or rescanned samples in the response. At least 2 search criteria must be provided in each request. Every request returns a maximum of 1000 results. If more than 1000 samples match the requested criteria, the response includes a next_page field to indicate this. The user can then request the next page with up to 1000 results.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc" "date"

Required parameter that specifies the time format for the time_value parameter.

time_value
required
string <Unix timestamp OR date-time OR date>

Required parameter that specifies the date and time for which the user is requesting data from the service.

query Parameters
status
string
Enum: "KNOWN" "MALICIOUS" "SUSPICIOUS"
threat_level
integer [ 0 .. 5 ]

0-5, with 5 indicating highest severity. Applies only to malicious and suspicious samples.

trust_factor
integer [ 0 .. 5 ]

0-5, with 0 indicating highest trust. Applies only to known samples.

threat_name
string^\w+-\w*\.\w+\.\w+$

Complete malware threat name. Conforms to ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious samples only.

platform
string

Platform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

subplatform
string

Subplatform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_type
string

Type part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_family
string

Family part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

sample_type
string

Sample type string as detected by ReversingLabs Spectra Core.

sample_size
integer

Sample size in bytes.

scanner_detections
integer

Number of antivirus scanners that have detected the sample as malicious.

page
integer
Example: page=2

Optional parameter that specifies which page of results should be returned when there are more than 1000 samples in the list of results. When this parameter is not included in the request, only the first page of results is returned.

format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sha1
string

Hexadecimal hash value of the sample

sha256
string

Hexadecimal hash value of the sample

md5
string

Hexadecimal hash value of the sample

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/sample/search/download/v1/query/date/2018-07-03?status=malicious&platform=bytecode&threat_level=5&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0306: Expression Search Query (latest)

The Expression Search API allows users to find samples in ReversingLabs Spectra Intelligence that match the requested criteria. The service returns only new samples - either samples that were first seen on the requested date, or samples from the last 24 hours - and does not include old or rescanned samples in the response. At least 2 search criteria must be provided in each request. Every request returns a maximum of 1000 results. If more than 1000 samples match the requested criteria, the response includes a next_page field to indicate this. The user can then request the next page with up to 1000 results.

Authorizations:
BasicAuth
query Parameters
status
string
Enum: "KNOWN" "MALICIOUS" "SUSPICIOUS"
threat_level
integer [ 0 .. 5 ]

0-5, with 5 indicating highest severity. Applies only to malicious and suspicious samples.

trust_factor
integer [ 0 .. 5 ]

0-5, with 0 indicating highest trust. Applies only to known samples.

threat_name
string^\w+-\w*\.\w+\.\w+$

Complete malware threat name. Conforms to ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious samples only.

platform
string

Platform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

subplatform
string

Subplatform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_type
string

Type part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_family
string

Family part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

sample_type
string

Sample type string as detected by ReversingLabs Spectra Core.

sample_size
integer

Sample size in bytes.

scanner_detections
integer

Number of antivirus scanners that have detected the sample as malicious.

page
integer
Example: page=2

Optional parameter that specifies which page of results should be returned when there are more than 1000 samples in the list of results. When this parameter is not included in the request, only the first page of results is returned.

format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/sample/search/download/v1/query/date/2018-07-03?status=malicious&platform=bytecode&threat_level=5&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0306: Expression Search Statistics Query (time range)

The Expression Search Statistics API returns aggregated statistics about new samples in ReversingLabs Spectra Intelligence that match the requested criteria. The service returns only new samples - either samples that were first seen on the requested date, or samples from the last 24 hours - and does not include old or rescanned samples in the response. At least 2 search criteria must be provided in each request. Every request returns a maximum of 1000 results. If more than 1000 samples match the requested criteria, the response includes a next_page field to indicate this. The user can then request the next page with up to 1000 results.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc" "date"

Required parameter that specifies the time format for the time_value parameter.

time_value
required
string <Unix timestamp OR date-time OR date>

Required parameter that specifies the date and time for which the user is requesting data from the service.

query Parameters
status
string
Enum: "KNOWN" "MALICIOUS" "SUSPICIOUS"
threat_level
integer [ 0 .. 5 ]

0-5, with 5 indicating highest severity. Applies only to malicious and suspicious samples.

trust_factor
integer [ 0 .. 5 ]

0-5, with 0 indicating highest trust. Applies only to known samples.

threat_name
string^\w+-\w*\.\w+\.\w+$

Complete malware threat name. Conforms to ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious samples only.

platform
string

Platform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

subplatform
string

Subplatform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_type
string

Type part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_family
string

Family part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

sample_type
string

Sample type string as detected by ReversingLabs Spectra Core.

sample_size
integer

Sample size in bytes.

scanner_detections
integer

Number of antivirus scanners that have detected the sample as malicious.

page
integer
Example: page=2

Optional parameter that specifies which page of results should be returned when there are more than 1000 samples in the list of results. When this parameter is not included in the request, only the first page of results is returned.

format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/sample/search/download/v1/statistics/date/2017-06-08?status=malicious&threat_level=5&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0306: Expression Search Statistics Query (latest)

The Expression Search Statistics API returns aggregated statistics about new samples in ReversingLabs Spectra Intelligence that match the requested criteria. The service returns only new samples - either samples that were first seen on the requested date, or samples from the last 24 hours - and does not include old or rescanned samples in the response. At least 2 search criteria must be provided in each request. Every request returns a maximum of 1000 results. If more than 1000 samples match the requested criteria, the response includes a next_page field to indicate this. The user can then request the next page with up to 1000 results.

Authorizations:
BasicAuth
query Parameters
status
string
Enum: "KNOWN" "MALICIOUS" "SUSPICIOUS"
threat_level
integer [ 0 .. 5 ]

0-5, with 5 indicating highest severity. Applies only to malicious and suspicious samples.

trust_factor
integer [ 0 .. 5 ]

0-5, with 0 indicating highest trust. Applies only to known samples.

threat_name
string^\w+-\w*\.\w+\.\w+$

Complete malware threat name. Conforms to ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious samples only.

platform
string

Platform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

subplatform
string

Subplatform part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_type
string

Type part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

malware_family
string

Family part of the malware threat name (platform-subplatform.type.familyname). Applies to malicious samples only.

sample_type
string

Sample type string as detected by ReversingLabs Spectra Core.

sample_size
integer

Sample size in bytes.

scanner_detections
integer

Number of antivirus scanners that have detected the sample as malicious.

page
integer
Example: page=2

Optional parameter that specifies which page of results should be returned when there are more than 1000 samples in the list of results. When this parameter is not included in the request, only the first page of results is returned.

format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/sample/search/download/v1/statistics/date/2017-06-08?status=malicious&threat_level=5&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0307-0311, 0317: Vertical Feeds Statistics

The Vertical Feeds Statistics API provides information about new malware samples detected in Spectra Intelligence, filtered by category. The service can return a list of malware family names newly added to each category; the number of unique new samples added for each malware family in a category; and a list of top 20 malware families per category.

Authorizations:
BasicAuth
path Parameters
category
required
string
Enum: "financial" "retail" "ransomware" "apt" "exploit" "configuration"

Required parameter that corresponds to the vertical feed category the user is requesting to access. Only one category can be requested in each query. Note that the response for the exploit category contains additional scanner_coverage data not found in other categories.

filter
required
string
Enum: "first_seen" "counts" "top_list"
  • first_seen: list of family names newly added to the requested category, and the times when they were added
  • counts: number of unique new samples added for each malware family in the requested category
  • top_list: top 20 family names and their unique hash counts for the requested category
query Parameters
weeks
integer [ 0 .. 30 ]
Default: 0
Example: weeks=2

Optional parameter that specifies the number of weeks for which the data will be returned in the response. When the parameter is not included in the request, all available data is returned. The same happens when setting the weeks value to zero, using the all_time parameter instead, or omitting both weeks and all_time from the request altogether. When this parameter is used in the query, all_time cannot be used in the same request.

all_time
boolean

Optional flag parameter that instructs the service to return all available data for the requested category. The same happens when the weeks value is set to zero. When neither this parameter nor the weeks parameter are included in the request, all available data is returned by default. When this parameter is used in the query, weeks cannot be used in the same request.

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/feed/malware/detection/family/v2/statistics/category/financial/first_seen?weeks=2&format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-0312-0316, TCA-0318: Vertical Feeds Search (latest)

The Vertical Feeds Search API allows users to get hashes of new malware samples from ReversingLabs Targeted and Industry-Specific File Indicator Feeds by searching for malware family names. Samples are included in the response based on the time when they were added to a particular feed. The results include additional metadata about each sample.

Authorizations:
BasicAuth
path Parameters
family_name
required
string

Case-sensitive parameter; accepts a malware family name or a CVE identifier.

query Parameters
count
integer [ 1 .. 1000 ]
Default: 100

Optional parameter that specifies the number of hashes to return in the response. Setting this value too low may result in identical from and to timestamps, which will cause a response loop.

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/feed/malware/detection/family/v2/index/family_name/search/Stuxnet/from/utc/2024-1-1T00:00:00?count=20&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0319: Start YARA Retro Hunt

The YARA Retro Hunting Administration API allows users to manage their own YARA retro hunts and retroactively match YARA rules against files from ReversingLabs Spectra Intelligence.

Authorizations:
BasicAuth
Request Body schema: application/json
required

ruleset_name is a required parameter that specifies the name of the YARA ruleset for which the user is requesting an action from the service. The value must be a string containing the name of a YARA ruleset previously uploaded by the user. Only one ruleset name can be submitted in each request.

ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$

Responses

Request samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders"
}

Response samples

Content type
application/json
{
  • "ruleset_name": "Name of the requested YARA ruleset; corresponds to the string specified in the request",
  • "ruleset_sha1": "SHA1 hash of the requested ruleset content"
}

TCA-0319: Cancel YARA Retro Hunt

The YARA Retro Hunting Administration API allows users to manage their own YARA retro hunts and retroactively match YARA rules against files from ReversingLabs Spectra Intelligence.

Authorizations:
BasicAuth
Request Body schema: application/json
required

ruleset_name is a required parameter that specifies the name of the YARA ruleset for which the user is requesting an action from the service. The value must be a string containing the name of a YARA ruleset previously uploaded by the user. Only one ruleset name can be submitted in each request.

ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$

Responses

Request samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders"
}

Response samples

Content type
application/json
{
  • "ruleset_name": "Name of the requested YARA ruleset; corresponds to the string specified in the request",
  • "ruleset_sha1": "SHA1 hash of the requested ruleset content"
}

TCA-0319: YARA Retro Hunting Status

The YARA Retro Hunting Administration API allows users to manage their own YARA retro hunts and retroactively match YARA rules against files from ReversingLabs Spectra Intelligence.

Authorizations:
BasicAuth
path Parameters
ruleset_name
required
string [ 3 .. 48 ] characters ^[a-z,A-Z,0-9,_-]*$
Example: RAT_Ratdecoders

Required parameter used for checking the retro hunt status for the specified YARA ruleset. Only one ruleset name can be submitted in each request.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/yara/admin/v1/ruleset/ExampleRulesetName/status-retro-hunt' --user <username>:<password>

Response samples

Content type
application/json
{
  • "ruleset_name": "RAT_Ratdecoders",
  • "retro_status": "IN_VALIDATION",
  • "reason": "Description of the reason for the current status (if applicable)",
  • "progress": "0",
  • "start_time": "YYYY-MM-DDThh:mm:ss",
  • "finish_time": "YYYY-MM-DDThh:mm:ss",
  • "estimated_finish_time": "YYYY-MM-DDThh:mm:ss"
}

TCA-0319: YARA Retro Matches Feed

The YARA Retro Matches Feed API returns a recordset of YARA ruleset matches in the requested time range for the authenticated user. The feed will return at most 1000 records, starting from the earliest one. However, if a single second contains more than 1000 matches, all of them will be returned in a single query. When a ruleset reaches 10 000 matches, it will be capped and will no longer store new matches. To continue collecting new matches, the ruleset has to be created again under a new name.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string

Period between the time specified by this parameter and the time when the request is made. The earliest supported time value is May 20 2016 00:00h UTC (timestamp 1463702400). The latest supported time value is 10 seconds before the current time. The value must be in the format specified by the time_format parameter. To get the next page of results, use the last_timestamp value from the response of the previous request as the time_value in the next request. The maximum time span for a single request is limited to 24 hours.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/feed/yara/retro/v1/query/timestamp/1463702400?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0320: Advanced Search

The Advanced Search API allows users to find samples in ReversingLabs Spectra Intelligence by combining various search keywords. Some queries can be performed without using search keywords (non-keyword search), and bulk hash lookup is supported for hash-related keywords. The search is performed on a static data set that is updated daily. If no records are available for the requested search query, an empty response is returned. Note that the API implements limitations as to how many samples can be returned for a search query in one request and in total.

Authorizations:
BasicAuth
Request Body schema: application/json
required
string or object
page
integer
Default: 1
records_per_page
integer
Default: 10000
format
string
Default: "xml"
Enum: "xml" "json"

Specifies the format for the response.

sort
string
Default: "firstseen desc"

Sort by one of these fields: sha1, firstseen, threatname, sampletype, filecount, size. Append asc for ascending and desc for descending order, e.g. threatname asc.

Responses

Request samples

Content type
application/json
Example
{
  • "query": "firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z] classification:[malicious, suspicious] threatname:win32",
  • "page": 2,
  • "format": "json",
  • "records_per_page": 100,
  • "sort": "threatname desc"
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0321: RHA1 Analytics Single Query

The RHA1 Analytics API provides real-time statistics (counters) for malicious, suspicious and known samples that are functionally similar to the requested SHA1 hash at the requested precision level.

Authorizations:
BasicAuth
path Parameters
rha1_type
required
string
Enum: "pe01" "elf01" "machO01" "pe02"

Required parameter. A measure of RHA1 precision level; represents the degree to which a file is functionally similar to another file. The following precision levels are supported - 25% for PE, MachO and ELF files (expressed as pe01, elf01, machO01), and 50% for PE files (expressed as pe02).

sha1
required
string

Must be a valid SHA1 hash.

query Parameters
extended
boolean
Default: "false"

Optional parameter. Supported values are true (sends the extended data set in the response) and false (sends only the list of SHA1 hashes). The default is false. If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata: classification, threat level, trust factor, malware family name, threat name, malware type, targeted platform and subplatform; SHA1, MD5, and SHA256 hashes; sample size, sample type, download availability, first and last seen dates (UTC).

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/rha1/analytics/v1/query/elf01/9c489fcaee9abedd736b474d7f9076d23ea2bb9b?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-0321: RHA1 Analytics Bulk Query

The RHA1 Analytics API provides real-time statistics (counters) for malicious, suspicious and known samples that are functionally similar to the requested SHA1 hash at the requested precision level.

Authorizations:
BasicAuth
path Parameters
post_format
required
string
Enum: "xml" "json"

Required parameter that defines the POST payload format. Supported options are xml and json. By default, the response format matches the format defined by this parameter.

Request Body schema: application/json
required

Up to 1000 hashes can be submitted in one request.

required
object
required
object
rha1_type
required
string non-empty
extended
required
boolean
response_format
required
string >= 3 characters
Enum: "json" "xml"
hashes
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "rl": {
    }
}

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Customer Usage

Monitor your usage of ReversingLabs Spectra Intelligence services

TCA-9999: Customer Usage Single User Query

The Customer Usage Single User API allows ReversingLabs customers to track their usage of Spectra Intelligence services provisioned to their account. It returns the number of queries made in the requested date range for the current user account (the one that is sending the request). Some products may specify usage quotas in bytes instead of requests. In that case the number of used bytes is returned alongside the number of requests. Provisioned services with no registered usage in the requested date range are not included in the response.

Authorizations:
BasicAuth
path Parameters
type
required
string
Enum: "daily" "date_range" "monthly" "yara"
Example: daily

Selects the type of query to run. daily and monthly show usage in the selected time period, date_range shows usage for accounts with product licences that have a fixed expiration date. yara returns information about the number of active YARA rulesets.

query Parameters
date
string <date>
Example: date=2020-04-28

Supported only when /daily is used in the endpoint path. Optional parameter that specifies the date for which customer usage information should be returned. Users can submit one value per request in the YYYY-MM-DD format. This parameter is incompatible and mutually exclusive with from&to.

month
string
Example: month=2020-04

Supported only when /monthly is used in the endpoint path. Optional parameter that specifies the month for which customer usage information should be returned. Users can submit one value per request in the YYYY-MM format. This parameter is incompatible and mutually exclusive with from&to.

from
string <date>
Example: from=2020-01-17

Optional parameter that specifies the start date for the customer usage report. Must be used together with to. When used with /daily, the value should be in the YYYY-MM-DD format. When used with /monthly, the value should be in the YYYY-MM format. This parameter is incompatible and mutually exclusive with month and date parameters.

to
string <date>
Example: to=2020-06-03

Optional parameter that specifies the end date for the customer usage report. Must be used together with from. When used with /daily, the value should be in the YYYY-MM-DD format. When used with /monthly, the value should be in the YYYY-MM format. This parameter is incompatible and mutually exclusive with month and date parameters.

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/customer_usage/v1/usage/daily?from=2020-01-17&to=2020-06-03&format=json' --user <username>:<password>

Response samples

Content type
application/json
Example
{
  • "rl": {
    }
}

TCA-9999: Customer Usage Company Query

The Customer Usage Company API allows ReversingLabs customers to track the usage of Spectra Intelligence services provisioned to all accounts in a company. It returns the combined usage for all accounts within the company the current user belongs to. Provisioned services with no registered usage in the requested date range are not included in the response.

Authorizations:
BasicAuth
path Parameters
type
required
string
Enum: "daily" "monthly" "date_range"
Example: daily

Selects the type of query to run. daily and monthly show usage in the selected time period, date_range shows usage for accounts with product licences that have a fixed expiration date.

query Parameters
date
string <date>
Example: date=2020-04-28

Supported only when /daily is used in the endpoint path. Optional parameter that specifies the date for which customer usage information should be returned. Users can submit one value per request in the YYYY-MM-DD format. This parameter is incompatible and mutually exclusive with from&to.

month
string
Example: month=2020-04

Supported only when /monthly is used in the endpoint path. Optional parameter that specifies the month for which customer usage information should be returned. Users can submit one value per request in the YYYY-MM format. This parameter is incompatible and mutually exclusive with from&to.

from
string <date>
Example: from=2020-01-17

Optional parameter that specifies the start date for the customer usage report. Must be used together with to. When used with /daily, the value should be in the YYYY-MM-DD format. When used with /monthly, the value should be in the YYYY-MM format. This parameter is incompatible and mutually exclusive with month and date parameters.

to
string <date>
Example: to=2020-01-17

Optional parameter that specifies the end date for the customer usage report. Must be used together with from. When used with /daily, the value should be in the YYYY-MM-DD format. When used with /monthly, the value should be in the YYYY-MM format. This parameter is incompatible and mutually exclusive with month and date parameters.

format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/customer_usage/v1/usage/company/daily?from=2020-01-17&to=2020-06-03&format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-9999: Quota Limits (single user)

This query returns current quota limits for APIs accessible to the authenticated user or users belonging to the authenticated user's company. Products are grouped into one object if they share the usage quota and access rights. This means that the same users and products can appear multiple times in the response.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/customer_usage/v1/limits?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCA-9999: Quota Limits (company)

This query returns current quota limits for APIs accessible to the authenticated user or users belonging to the authenticated user's company. Products are grouped into one object if they share the usage quota and access rights. This means that the same users and products can appear multiple times in the response.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl --url 'https://data.reversinglabs.com/api/customer_usage/v1/limits/company?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Malicious File Indicators

Get file threat intelligence

TCF-0101 New Malware - Files

This query returns malware detections from the requested timestamp. The feed will return 1000 records at most, or a little bit more than 1000 if there are some records with the same timestamp.

To fetch the next batch of records, use the timestamp from the response increased by 1.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0102 - 0106 New Malware - Platform Filtered

This service provides information about new malware samples with detections in the Spectra Intelligence system. The samples are filtered by platform.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

platform
string
Enum: "Android" "Boot" "ByteCode" "Document" "DOS" "Firmware" "FreeBSD" "iOS" "Linux" "MacOS" "OS2" "Palm" "Script" "Symbian" "Unix" "Unknown" "Win32" "Win64"
Example: platform=Android&platform=Linux

One or more values from the list of supported platform names.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/platform/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0102 - 0106 New Malware - Platform Filtered (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com/api/feed/malware/detection/platform/v1/query/start/utc/2024-01-01T00:00:00' --user <username>:<password>

TCF-0102 - 0106 New Malware - Platform Filtered (Pull)

This service provides information about new malware samples with detections in the Spectra Intelligence system, starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/platform/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0107 Files Scanned for the First Time (Continuous)

This service provides a continuous list of hashes for samples collected from various sources and scanned with the VTEST AV scanning system for the first time in Spectra Intelligence system.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/first_scan/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0107 Files Scanned for the First Time (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com/api/feed/malware/first_scan/v1/query/start/utc/2024-01-01T00:00:00' --user <username>:<password>

TCF-0107 Files Scanned for the First Time (Pull)

This query returns a list of hashes for samples scanned for the first time, starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/first_scan/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0108 New Files - First and Re-Scan (Continuous)

This service provides a continuous list of samples in the Spectra Intelligence system which have been scanned for the first time or rescanned with the VTEST AV scanner system.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/scan/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0108 New Files - First and Re-Scan (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com/api/feed/malware/scan/v1/query/start/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

TCF-0108 New Files - First and Re-Scan (Pull)

This query returns a list of hashes for scanned samples (first time or rescan), starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/scan/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0109 Files with Detection Changes (Continuous)

This service provides a continuous list of records about samples in the Spectra Intelligence system that show detection changes in their VTEST reports.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/scan/change/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0109 Files with Detection Changes (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com/api/feed/malware/scan/change/v1/query/start/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

TCF-0109 Files with Detection Changes (Pull)

This query returns a list of hashes for scanned samples (first time scan or detection change), starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/scan/change/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0111 MWP Change Events Feed (Continuous)

This service provides a continuous list of records about samples in the Spectra Intelligence system that show detection changes in their VTEST reports.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com//api/feed/mwp_change_events/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0111 MWP Change Events Feed (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com//api/feed/mwp_change_events/v1/query/start/utc/2024-01-01T00:00:00' --user <username>:<password>

TCF-0111 MWP Change Events Feed (Pull)

This query returns a list of hashes for scanned samples (first time scan or detection change), starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/mwp_change_events/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Certificate Indicators

Find out more about certificates used to sign files

TCF-0601 Certificate Feed API (time range)

This service provides certificate information alongside the information about associated samples signed with the certificate(s). The feed includes valid certificates and self-signed certificates used in impersonation attempts. The information is delivered as a feed. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
number [ 1 .. 100 ]
Default: 100

The maximum number of records to return in the certificate feed.

extended
boolean
Default: false
Enum: true false
Example: extended=false

The extended data set contains more metadata for samples.

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/certificate/v1/query/from/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0601 Certificate Feed API (time range) (paginated)

This service provides certificate information alongside the information about associated samples signed with the certificate(s). The feed includes valid certificates and self-signed certificates used in impersonation attempts. The information is delivered as a feed. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

page
required
string

The pagination value for the next page is provided in the previous request response.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
number [ 1 .. 100 ]
Default: 100

The maximum number of records to return in the certificate feed.

extended
boolean
Default: false
Enum: true false
Example: extended=false

The extended data set contains more metadata for samples.

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/certificate/v1/query/from/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0601 Certificate Feed API (latest)

This service provides certificate information alongside the information about associated samples signed with the certificate(s). The feed includes valid certificates and self-signed certificates used in impersonation attempts. The information is delivered as a feed. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
number [ 1 .. 100 ]
Default: 100

The maximum number of records to return in the certificate feed.

extended
boolean
Default: false
Enum: true false
Example: extended=false

The extended data set contains more metadata for samples.

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/certificate/v1/query/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0601 Certificate Feed API (latest) (paginated)

This service provides certificate information alongside the information about associated samples signed with the certificate(s). The feed includes valid certificates and self-signed certificates used in impersonation attempts. The information is delivered as a feed. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
path Parameters
page
required
string

The pagination value for the next page is provided in the previous request response

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

limit
number [ 1 .. 100 ]
Default: 100

The maximum number of records to return in the certificate feed.

extended
boolean
Default: false
Enum: true false
Example: extended=false

The extended data set contains more metadata for samples.

classification
string
Enum: "known" "malicious" "suspicious" "unknown"
Example: classification=malicious

Optional parameter that allows filtering the results by their classification status. If this parameter is provided in the request, the response will include only those samples that match the requested status. Supported values are: known, malicious, suspicious, unknown (case-insensitive).

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/certificate/v1/query/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Network Indicators

Inspect IP addresses, URLs, and emails linked to malware

TCF-0301 Network IOCs Feed

Returns information about malicious URLs from 3rd party sources and URLs from which we have downloaded malicious files.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware_uri/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0301 Network IOCs Feed (latest)

Returns information about malicious URLs from 3rd party sources and URLs from which we have downloaded malicious files.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware_uri/v1/query/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

CVE and In-the-Wild Exploits

List detected CVEs and exploits

TCF-0201 CVEs Exploited in the Wild (by date)

This query returns a document containing a list of all detected CVE identifiers for the requested day.

Authorizations:
BasicAuth
path Parameters
date
required
string <date>
Example: 2020-04-20

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/cve/v1/2024-01-01' --user <username>:<password>

Response samples

Content type
text/plain
2021-04-20
CVE-2021-3156
CVE-2021-27065
CVE-2021-26855
CVE-2021-26411
CVE-2021-21206
CVE-2021-1732
CVE-2021-1647
CVE-2020-7961
CVE-2020-3153
CVE-2020-16040
CVE-2020-1472
CVE-2020-1054
CVE-2020-1048
CVE-2020-0796
CVE-2019-7123
CVE-2019-2725
CVE-2019-1405
CVE-2019-1132
CVE-2019-0841

TCF-0201 CVEs Exploited in the Wild (latest)

Use the “latest” endpoint to retrieve results from the latest day for which we have data.

Authorizations:
BasicAuth

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/cve/v1/latest' --user <username>:<password>

Response samples

Content type
text/plain
2021-04-20
CVE-2021-3156
CVE-2021-27065
CVE-2021-26855
CVE-2021-26411
CVE-2021-21206
CVE-2021-1732
CVE-2021-1647
CVE-2020-7961
CVE-2020-3153
CVE-2020-16040
CVE-2020-1472
CVE-2020-1054
CVE-2020-1048
CVE-2020-0796
CVE-2019-7123
CVE-2019-2725
CVE-2019-1405
CVE-2019-1132
CVE-2019-0841

TCF-0201 CVEs Exploited in the Wild (all)

Use this query to fetch all CVE identifiers detected since the creation of this feed.

Authorizations:
BasicAuth

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/cve/v1/all_cves' --user <username>:<password>

Response samples

Content type
text/plain
2021-04-20
CVE-2021-3156
CVE-2021-27065
CVE-2021-26855
CVE-2021-26411
CVE-2021-21206
CVE-2021-1732
CVE-2021-1647
CVE-2020-7961
CVE-2020-3153
CVE-2020-16040
CVE-2020-1472
CVE-2020-1054
CVE-2020-1048
CVE-2020-0796
CVE-2019-7123
CVE-2019-2725
CVE-2019-1405
CVE-2019-1132
CVE-2019-0841

TCF-0202 Reports on CVEs Exploited in the Wild

This query returns a document containing the list of malware hashes (SHA1, SHA256, MD5), threat names, and threat counts associated with CVE identifiers for the requested day.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "utc" "date"
Example: date

Specifies the time format for the time_value parameter.

time_value
required
string

Accepts values formatted according to the format set in the time_format parameter.

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/report/cve/daily/v1/query/date/2024-01-01?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0202 Reports on CVEs Exploited in the Wild (latest)

This query returns a document containing the list of malware hashes (SHA1, SHA256, MD5), threat names, and threat counts associated with CVE identifiers for the latest day for which we have data.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/report/cve/daily/v1/query/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0203 New Exploit or CVE Samples Found In-the-Wild (Hourly List)

This service provides a list of new file hashes that contain CVE or Exploit Identification and that are detected within the requested one-hour period in the Spectra Intelligence system.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

active_cve
boolean
Default: true
Enum: true false
Example: active_cve=true

When true (default), returns only exploits with active CVE identifiers. When false, returns only exploit candidates.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/exploit/hourly/v2/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0203 New Exploit or CVE Samples Found In-the-Wild (Hourly List) - latest

This query returns the results from the latest hour for which we have data.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

active_cve
boolean
Default: true
Enum: true false
Example: active_cve=true

When true (default), returns only exploits with active CVE identifiers. When false, returns only exploit candidates.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/exploit/hourly/v2/query/latest?format=json&sample_available=true' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0204 New Exploit and CVE Samples Found In-the-Wild (Daily List)

This service provides per-day information about new file hashes in the Spectra Intelligence system that contain CVE or Exploit identifications.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "utc" "date"
Example: date

Specifies the time format for the time_value parameter.

time_value
required
string

Accepts values formatted according to the format set in the time_format parameter.

query Parameters
sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

format
string
Default: "xml"
Enum: "xml" "json" "htsv"

Specifies the format in which the resulting data will be returned.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/exploit/daily/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0204 New Exploit and CVE Samples Found In-the-Wild (Daily List) - latest

Use the “latest” endpoint to retrieve results from the latest day for which we have data.

Authorizations:
BasicAuth
query Parameters
sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

format
string
Default: "xml"
Enum: "xml" "json" "htsv"
Example: format=json

Specifies the format in which the resulting data will be returned.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/exploit/daily/v1/query/latest?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Whitelist File Indicators

Obtain lists of currently or previously whitelisted files

TCF-0501 Whitelisted Files - New

This query returns a list of newly whitelisted samples since the requested time.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/whitelisted/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0501 Whitelisted Files - New (Start)

This query sets the starting timestamp for the pull query.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

Responses

Request samples 

curl --location --request PUT 'https://data.reversinglabs.com/api/feed/whitelisted/v1/query/start/utc/2024-01-01T00:00:00' --user <username>:<password>

TCF-0501 Whitelisted Files - New (Pull)

This query returns a list of newly whitelisted samples, starting with the timestamp defined with the start query.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

sample_available
boolean
Default: false
Enum: true false
Example: sample_available=true

If true, only samples available for download will be returned. If false, all samples will be returned.

limit
number [ 0 .. 1000 ]
Default: 1000
Example: limit=1000

The number of records to return in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/whitelisted/v1/query/pull?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0502 Whitelisted Files - Changes

This query returns the samples which changed their whitelist status since the requested time.

Authorizations:
BasicAuth
path Parameters
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/whitelisted_change/v1/query/utc/2024-01-01T00:00:00?format=json' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0502 Whitelisted Files - Changes (latest)

This query returns the 1000 latest samples which changed their whitelist status.

Authorizations:
BasicAuth
query Parameters
format
string
Default: "xml"
Enum: "xml" "json" "tsv"
Example: format=tsv

Optional parameter that allows choosing the response format. Supported values: xml, json, tsv. When the parameter is not included in the request, defaults to xml.

Responses

Response samples

Content type
application/json
{
  • "rl": {
    }
}

Targeted and Industry-Specific Indicators

Explore specialized types of malware

TCF-0401-0406 (time range)

ReversingLabs Targeted and Industry-Specific Indicators are early-warning feeds that provide information about new malware samples detected in the ReversingLabs Spectra Intelligence system. The samples are filtered by category. Every category corresponds to one feed. The feeds are specialized collections of malware families that are known to have significant impact within specific industries (Retail, Financial), as well as of malware families that share a common trait (exploits, ransomware). ReversingLabs carefully selects malware families for each feed based on public and internal research. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
path Parameters
category
required
string
Enum: "apt" "financial" "ransomware" "retail" "exploit" "configuration"
Example: apt
  • TCF-0401: Advanced Persistent Threats (APT)
  • TCF-0402: Financial Services Malware
  • TCF-0403: Ransomware
  • TCF-0404: Retail Sector Malware
  • TCF-0405: CVE Exploits
  • TCF-0406: Malware Configuration
time_format
required
string
Enum: "timestamp" "utc"

Required parameter that specifies the time format for the time_value parameter. Supported values: timestamp (Unix epoch time as the number of seconds since 1970-01-01 00:00:00); utc (YYYY-MM-DDThh:mm:ss).

time_value
required
string
Example: 2020-04-20T00:00:00

Accepts values in the format set by time_format

query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

count
number [ 1 .. 1000 ]
Default: 100

Allows specifying how many of the latest hashes in the selected category should be returned in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/family/v2/query/apt/utc/2024-01-01T00:00:00?format=json&count=200' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}

TCF-0401-0406 (latest)

ReversingLabs Targeted and Industry-Specific Indicators are early-warning feeds that provide information about new malware samples detected in the ReversingLabs Spectra Intelligence system. The samples are filtered by category. Every category corresponds to one feed. The feeds are specialized collections of malware families that are known to have significant impact within specific industries (Retail, Financial), as well as of malware families that share a common trait (exploits, ransomware). ReversingLabs carefully selects malware families for each feed based on public and internal research. The feed stores records for the last 365 days.

Authorizations:
BasicAuth
path Parameters
category
required
string
Enum: "apt" "financial" "ransomware" "retail" "exploit" "configuration"
Example: apt
  • TCF-0401: Advanced Persistent Threats (APT)
  • TCF-0402: Financial Services Malware
  • TCF-0403: Ransomware
  • TCF-0404: Retail Sector Malware
  • TCF-0405: CVE Exploits
  • TCF-0406: Malware Configuration
query Parameters
format
string
Default: "xml"
Enum: "xml" "json"
Example: format=json

Optional parameter that allows choosing the response format. Supported values: xml, json. When the parameter is not included in the request, defaults to xml.

count
number [ 1 .. 1000 ]
Default: 100

Allows specifying how many of the latest hashes in the selected category should be returned in the response.

Responses

Request samples 

curl 'https://data.reversinglabs.com/api/feed/malware/detection/family/v2/query/apt/latest?format=json&count=200' --user <username>:<password>

Response samples

Content type
application/json
{
  • "rl": {
    }
}