# Spectra Intelligence Documentation > Cloud threat intelligence API and feed documentation. This file contains all documentation content in a single document following the llmstxt.org standard. ## Spectra Intelligence Quick Start — First API Call in Minutes # Getting started with Spectra Intelligence This guide walks you through your first Spectra Intelligence API call — a file reputation lookup by hash. You will authenticate, send a request, and interpret the response. **What you'll accomplish:** - Obtain your API credentials - Make your first file reputation request - Parse and understand the response ## Prerequisites Before you begin: - A Spectra Intelligence account with API access - Your API credentials (username and password) - `curl` or Python 3 installed on your machine If you do not have an account, contact [ReversingLabs sales](https://www.reversinglabs.com/contact) to request access or an evaluation. ## Step 1: Get your API credentials Your Spectra Intelligence API credentials (username and password) are provided by [ReversingLabs Support](mailto:support@reversinglabs.com) when your account is activated. These credentials are used for HTTP Basic Authentication on all API requests. All API requests must be made over HTTPS to `data.reversinglabs.com`. ## Step 2: Make your first file reputation request The simplest API call is a file hash reputation lookup using the [TCA-0101](/SpectraIntelligence/API/FileThreatIntel/) endpoint. It accepts an MD5, SHA1, or SHA256 hash and returns a classification verdict instantly. **Using curl:** ```bash curl -u "your-username:your-password" \ "https://data.reversinglabs.com/api/databrowser/rl_data/query/sha1/list?format=json" \ -H "Content-Type: application/json" \ -d '{"rl": {"query": {"hash_type": "sha1", "hashes": ["3395856ce81f2b7382dee72602f798b642f14d45"]}}}' ``` **Using Python:** ```python username = "your-username" password = "your-password" hashes = ["3395856ce81f2b7382dee72602f798b642f14d45"] url = "https://data.reversinglabs.com/api/databrowser/rl_data/query/sha1/list?format=json" payload = {"rl": {"query": {"hash_type": "sha1", "hashes": hashes}}} response = requests.post(url, auth=(username, password), json=payload) print(response.json()) ``` You can also use the [ReversingLabs Python SDK](https://pypi.org/project/reversinglabs-sdk-py3/) for a higher-level interface to all Spectra Intelligence APIs. ## Step 3: Parse the response A successful response returns a JSON object with the file classification: ```json { "rl": { "entries": [ { "hash_type": "sha1", "hash_value": "3395856ce81f2b7382dee72602f798b642f14d45", "classification": { "classification": "MALICIOUS", "factor": 5, "scan_results": [] } } ] } } ``` **Key fields:** - `classification.classification` — `MALICIOUS`, `SUSPICIOUS`, `GOODWARE`, or `UNKNOWN` - `classification.factor` — Confidence level (1–5, where 5 is highest) - `scan_results` — Detections from individual AV engines If the hash is not in the database, the response returns `UNKNOWN`. ## Troubleshooting If your request fails, check the HTTP status code: - **401 Unauthorized** — Invalid credentials. Verify your username and password. - **403 Forbidden** — Your account does not have access to this endpoint. Contact support. - **429 Too Many Requests** — Daily or monthly quota exceeded. Daily quotas reset at 00:00 UTC. For a complete list of response codes and error handling, see [General Information](/SpectraIntelligence/#response-status-codes). ## Next steps Now that you've made your first API call, explore the full capabilities of Spectra Intelligence: - **[File Threat Intelligence API](/SpectraIntelligence/API/FileThreatIntel/)** — Full file analysis reports, not just reputation - **[Malware Hunting API](/SpectraIntelligence/API/MalwareHunting/)** — Search across the threat intelligence database - **[TAXII Feeds](/SpectraIntelligence/Feed/TAXII/tctf-0003/)** — Consume threat intelligence as structured feeds - **[OpenAPI Reference](/SpectraIntelligence/API-reference)** — Complete API specification - **[General Information](/SpectraIntelligence/)** — Limits, quotas, and technical reference --- ## Spectra Intelligence API — Authentication, Rate Limits & Endpoints # Spectra Intelligence API — Authentication, Rate Limits & Endpoints This section provides technical reference documentation for **Spectra Intelligence APIs and Feeds**. Each individual API reference page explains what the service does and documents available endpoints, supported query types, data formats, and response structures, along with service-specific details such as rate limits, required permissions, and field explanations. If you're looking for product overviews and datasheets, visit the [Spectra Intelligence product page](https://www.reversinglabs.com/products/spectra-intelligence). ## Introduction This section provides technical reference documentation for **Spectra Intelligence APIs and Feeds**. Each individual API reference page explains what the service does and documents available endpoints, supported query types, data formats, and response structures, along with service-specific details such as rate limits, required permissions, and field explanations. If you're looking for product overviews and datasheets, visit the [Spectra Intelligence product page](https://www.reversinglabs.com/products/spectra-intelligence). ## Spectra Intelligence API Reference Spectra Intelligence documentation is also available as an [OpenAPI Specification](/SpectraIntelligence/API-reference). ## Sending requests Requests addressed to Spectra Intelligence must use the *https* protocol. The server is `data.reversinglabs.com`. All APIs require the HTTP *Authorization* header with basic authentication. If not provided, the service will respond with status 401. ## Limits and quotas The limiting system counts the HTTP response code events for queries to ReversingLabs APIs. The limits are determined in customer contracts and are deducted only in these cases: **Single queries** – Only when HTTP code 200 is returned. **Bulk queries** - Applies only to services that support bulk queries. When HTTP code 200 is returned, the quota is deducted for each valid item sent within the bulk request. For example, a bulk request containing 100 hashes, 3 of which are invalid, will count as 97. **Next page queries** - Services that support pagination will count every successful next page query as a separate request. In case you reach the daily or monthly quota limit, the API will return HTTP code 429 and send an automated alert message to the previously provided contact email address. Daily quotas reset at 00:00 UTC, and monthly quotas reset on the first day of the month at 00:00 UTC. Customers can check their usage via the Customer Usage API or get in touch with the [Support Team](mailto:support@reversinglabs.com) to verify current API entitlements and quota limits. Use the [ReversingLabs Python SDK](https://pypi.org/project/reversinglabs-sdk-py3/) for easier programmatic interaction with the API. ## XML body The documentation provides request and response body examples in JSON, but all APIs also support XML request bodies. For **arrays in XML** , individual elements (such as objects or strings) will be wrapped inside `` tags in the response (and conversely, need to be wrapped inside `` in a request body). For example, the following JSON: ```json { "rl": { "entries": [ { "foo": "bar", "life_meaning": 42 } ] } } ``` ...should look like this in XML: ```xml bar 42 ``` ## Response status codes This table lists possible HTTP response codes, with descriptions. Individual APIs may have additional specific messages or codes. In those cases, see their documentation. Code | Description -----|--------------------------- 200 | The request has succeeded. 400 | The request could not be understood by the server due to malformed syntax. A possible reason might be that the request contains Unicode characters that cannot be processed. 401 | The request requires user authentication. The request MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource. 403 | The server understood the request, but is refusing to fulfill it. 404 | The server has not found anything matching the Request-URI. 405 | The method is known by the server but is not supported by the target resource. 409 | The request could not be completed due to a conflict with the current state of the resource. 413 | The request contained more than the maximum allowed amount of hashes (100). 429 | The daily/monthly quota has been reached, or the API rate limit exceeded (in this case, the service will return an additional "Rate limit exceeded" error message). 500 | The server encountered an unexpected condition which prevented it from fulfilling the request. 502 | The server received an invalid response from another server. 503 | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. --- ## Spectra Intelligence Automation API — Upload, Download & Monitor The Automation APIs enable programmatic management of samples in the Spectra Intelligence repository, including uploading, downloading, deleting, and monitoring files for changes. ## Common Use Cases ### Upload and manage samples 1. **[File upload (TCA-0202-0203)](tca-0202-0203.md)** - Upload samples and metadata to Spectra Intelligence for analysis 2. **[Reanalyze file (TCA-0205)](tca-0205.md)** - Trigger rescanning of existing samples with updated AV signatures 3. **[Delete file (TCA-0204)](tca-0204.md)** - Remove samples you own from the repository ### Download samples - **[File download (TCA-0201)](tca-0201.md)** - Download samples from the repository by hash (MD5, SHA1, SHA256) ### Monitor for changes - **[Reputation and metadata alerts (TCA-0206)](tca-0206.md)** - Subscribe to samples and receive notifications when their classification or metadata changes ## All Automation APIs --- ## File Download API (tca-0201) — Spectra Intelligence # File download (TCA-0201) This service allows a user to download a sample from the Spectra Intelligence repository. The download request requires the MD5/SHA1/SHA256 value of the sample to download, and receives a byte stream containing the requested sample. Faster downloads are supported through multithreading. It is suggested to use at most 4 parallel threads. If there is a need for additional threads, contact your sales representative. **This API is rate limited to 100 requests per minute.** ## Sample Download This query returns the contents of a sample matching the requested hash. The contents are returned as a byte stream. ### Request ``` GET /api/spex/download/v2/query/{hash_type}/{hash_value} ``` #### Path parameters - **hash_type** must be one of the following: **md5**, **sha1**, **sha256** - **hash_value** must be a valid hash of the sample that should be downloaded ## Sample Download Status 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 in the response will be returned as `-1`. Sample download status requests don't count towards the API usage quota and can be sent as long as the sample download quota isn't exceeded. Invalid and unknown hashes will be grouped into separate `unknown_hashes` and `invalid_hashes` objects in the report. `unknown_hashes` may include files that have been deleted. ### Request ``` POST /api/spex/download/v2/status/bulk_query/{post_format}[?format={xml|json}] ``` #### Path parameters - `post_format` - Defines the request format (`xml` or `json`) #### Query parameters - `format` - Defines the response format (`xml` or `json`) #### Headers - Headers must contain `Content-Type: application/octet-stream` #### Request body - The request must contain a list of at most 1000 valid hashes matching the `valid_hash_type` specified in the request - MD5, SHA1, SHA256. ``` json { "rl": { "query": { "hash_type": "string", "hashes": [ "string", "string" ] } } } ``` ### Response - the default response format is **xml** - sizes of samples that are unavailable for download are reported as `-1` - unknown and invalid hashes are grouped in `unknown_hashes` and `invalid_hashes` objects, respectively - sample size is expressed in bytes (integer) ``` json { "rl": { "entries": [], "unknown_hashes": [ "string" ], "invalid_hashes": [ "string" ] } } ``` `rl.entries[]`: ```json { "sha1": "string", "size": "string" } ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 403 | The sample is private and therefore not available for download. You can use the [TCA-0206 Alert on Reputation and Metadata](./tca-0206.md) API to get the notification when the sample becomes available. This error can also occur when the account doesn't have the necessary access rights. If this error persists, contact ReversingLabs support. | | 409 | Can't complete the request. Try to resume upload. | --- ## File Upload API (tca-0202/tca-0203) — Spectra Intelligence # File upload (TCA-0202-0203) This service allows users to upload a sample and its associated metadata to the Spectra Intelligence repository. Once uploaded, the sample is automatically analyzed by the ReversingLabs processing pipeline. The upload process involves two separate requests: 1. The first request uploads the file contents. 2. The second request uploads the metadata. ### Submitting Archives If the submission is an archive using a custom password, the password must be included in the metadata upload request. If the archive uses one of the standard passwords (`infected`, `password`, `1234`), the password does not need to be specified. If the archive will later be forwarded to the [TCA-0207](../DynamicAnalysis/tca-0207.md) service for dynamic analysis, it must comply with the size and file count limits described in the [TCA-0207 Dynamic Analysis User Guide](../DynamicAnalysis/tca-0207.md). These limits do not apply to standard pipeline processing. ### Privacy Whether submitted files will be shared with other ReversingLabs customers or not depends on the role configured for the Spectra Intelligence account used to upload files. If the account is configured to upload all files as shareable (not private), then other ReversingLabs customers will be able to download the files and access their analysis results (metadata) through other ReversingLabs solutions. If the account is configured to upload all files as not shareable (private), then other ReversingLabs customers may only be able to access analysis results for the files, but not retrieve the actual contents of the files. However, if the same files are uploaded to Spectra Intelligence as shareable from another source, they will cease to be treated as private. In that case, other ReversingLabs customers may be able to download the files. ### Processing limits While there is no file size limit for the uploaded samples, larger files will take longer to upload and analyze, and may have less available metadata. Files up to 400 MB are fully analyzed. Their metadata can be retrieved using the [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md), [TCA-0103 Historic Multi-AV Scan Records](../FileThreatIntel/tca-0103.md), [TCA-0104 File Analysis](../FileThreatIntel/tca-0104.md) services, and [TCA-0106 File Dynamic Analysis Report](../DynamicAnalysis/tca-0106.md). The complete metadata record includes, but is not limited to: classification, static analysis reports, behavior reports, dynamic analysis information, AV detections, container information, and file relationships. For more information, consult the official documentation for each of these services. Files between 400 MB and 2 GB have a reduced metadata set: classification information from the [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md) service, AV detections from the [TCA-0103 Historic Multi-AV Scan Records](../FileThreatIntel/tca-0103.md) service, and source info from the [TCA-0104 File Analysis](../FileThreatIntel/tca-0104.md) service. Files over 2 GB in size only have information about the file size and its source. If they came from a trusted source, [TCA-0101 File Reputation](../FileThreatIntel/tca-0101.md) classifies them as "KNOWN". **This API is rate limited to 10 requests per second.** **Tip: Production best practices** For reliable high-volume uploads, configure HTTP timeouts to 300 seconds and implement retry logic with exponential backoff to handle transient errors (408, 503). See [Upload API timeouts and retries](../../troubleshooting.md#upload-api-timeouts-and-retries) for details. ## Sample upload request ### Request ``` POST /api/spex/upload/{sha1_value} ``` This request is used to upload a sample. To upload a sample, you first need to get its SHA1 hash. ``` bash sha1sum example_file.tar.gz ``` Then, pass that hash as a **path parameter** (`sha1_value` in the URL above). The hash value must be lowercase. **Note: Querying Results for Recently Uploaded Files** When querying results for recently uploaded files, use the **SHA1 hash**. SHA256 and other hash types become available only after the file analysis is complete. HTTP headers should contain `Content-Type: application/octet-stream` and the file must be sent as a stream of raw bytes in the body of the HTTP request. ## Metadata upload request This request is used to upload metadata for the previously uploaded sample. If no metadata is uploaded, the sample won't be processed. You can see the uploaded metadata in the `rl.sample.sources` field in the response of our file analysis services ([TCA-0104](../FileThreatIntel/tca-0104.md) and [TCA-0105](../FileThreatIntel/tca-0105.md)). ### Request ``` POST /api/spex/upload/{sha1_value}/meta[?subscribe=data_change] ``` #### Path parameters - `sha1_value` - Must be a valid SHA1 hash of the sample that the metadata belongs to. The sample must be previously successfully uploaded. The hash value must be lowercase. #### Query parameters - `subscribe` - If set, adds the sample to the user's **data_change** feed subscription list. The only accepted value for this parameter is `data_change`. #### Headers - `Content-Type: application/octet-stream` #### Request body 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. The metadata may include an optional XML declaration in the beginning, such as ``. Metadata must contain the `domain` field and at least one `property` field. 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. For consistent results when using the [TCA-0207 Dynamic Analysis](../DynamicAnalysis/tca-0207.md) API, you must include a `filename` field in the metadata submission. **Note: You can add metadata multiple times. If you add a metadata field and assign it some value X, but then change this value to Y in a new request, that field will not be overwritten. Instead, every metadata addition results in a new metadata entry, and you will see both X and Y in the response for that sample. The maximum number of metadata response fields is 10, and they are not sorted by the latest entry.** ``` xml string string string string string ``` #### XML POST body example ``` xml application_name MyApplication application_version 7.0.3 url http://myapplications.com/apps/utilities filename MyApplication_7.0.3_English.exe tags application, utilities myapplications.com password123 ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 413 | The request contained more than the maximum allowed amount of hashes (100). | --- ## Delete File API (tca-0204) — Spectra Intelligence # Delete file (TCA-0204) The Delete Sample service provides the functionality of deleting samples submitted and owned exclusively by the requester. The service supports single and bulk queries. **This API is rate limited to 400 requests per second.** ## General Info about Requests/Responses - All requests support the **format** query field which supports two options: **xml** or **json** - Default response format is xml, except for bulk queries, where the default format is the same as the **post_format** - All bulk query rules will accept post payload of the same format (described below) - The number of hashes in a bulk request must not be larger than a 100 - POST requests must set in HTTP header field **Content-Type: application/octet-stream** ## Sample Delete Sample This query deletes a single sample defined by the hash value. ### Request ``` DELETE /api/delete/sample/v1/query/{hash_type}/{hash_value}[?delete_on={timestamp}] ``` #### Path parameters - `hash_type` - accepts these options: `md5`, `sha1`, `sha256` - `hash_value` - must be a valid hash defined by the `hash_type` parameter #### Query parameters - `delete_on` - optional query parameter that specifies when the sample will be deleted, expressed as a timestamp in seconds ### Response - Response code 404 is returned with a message **"requested data was not found"** when the hash is not found in the database - Response code 200 is returned when the sample is successfully deleted ## Sample Delete Bulk This query deletes multiple samples at once defined by the list of hash values in the request payload. It is more network-efficient compared to consecutive single queries. ### Request ``` DELETE /api/delete/sample/v1/bulk_query/{format} ``` #### Path parameters - `format` - Defines the request body format and supports **xml** and **json** #### Request body ``` json { "rl": { "query": { "hash_type": "string", "delete_on": "string", "hashes": [ "string", "string", "string" ] } } } ``` - `hash_type` will be accepted if it matches one of the following options: `md5`, `sha1`, `sha256` - `hash_value` must be a valid hash defined by the `hash_type` parameter - `delete_on` is an optional parameter that specifies when the sample will be deleted, expressed as a timestamp in seconds ### Response ``` json { "rl": { "deleted_hashes": [ "string" ], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" ], "forbidden_hashes": [ "string" ] } } ``` - `deleted_hashes` - A list of hashes of deleted samples - `invalid_hashes` - A list of ill-formatted hashes provided in the request - `unknown_hashes` - A list of hashes from the request that were not found in the database - `forbidden_hashes` - A list of hashes the user is not allowed to delete ## Examples ### Format query field These examples use a different query response format: ``` /api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json /api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml ``` ### Hash type path variable These examples use a different hash type: ``` /api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b /api/delete/sample/v1/query/sha256/b2bad07d6a3df4b0ec0c8d5f9a4905c289f9348e9e18d41d1b6033576ddf655cf80bc405e059ded6742947d78e0bfeb8 ``` ### Delete sample, bulk_query These examples use a different post format: ``` /api/delete/sample/v1/bulk_query/xml /api/delete/sample/v1/bulk_query/json ``` ### delete_on query field ``` /api/delete/sample/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?delete_on=1437566446 ``` ### Bulk JSON ``` /api/delete/sample/v1/bulk_query/json ``` ``` json { "rl": { "query": { "hash_type": "md5", "hashes": [ "4bb64c06b1a72539e6d3476891daf17b", "6353de8f339b7dcc6b25356f5fbffa4e", "59cb087c4c3d251474ded9e156964d5d" ] } } } ``` --- ## Reanalyze File API (tca-0205) — Spectra Intelligence # Reanalyze file (TCA-0205) The Rescan API provides a means to send sample(s) for rescanning. The service supports single and bulk queries. **This API is rate limited to 10 requests per second.** ## General Info about Requests/Responses - The bulk query request supports the **format** query field which supports two options: **xml** and **json** - Default bulk query response format is the same as the **post_format**. - All bulk query rules will accept post payload of the same format (described below) - The number of hashes in a bulk request must not be larger than a 100 - POST requests must set in HTTP header field **Content-Type: application/octet-stream**. ## Rescan Single Query This query sends a sample with the requested hash for rescanning. ### Request ``` GET /api/rescan/v1/query/{hash_type}/{hash_value} ``` #### Path parameters - **hash_type** accepts these options: `md5`, `sha1`, `sha256` - **hash_value** must be a valid hash defined by the **hash_type** parameter ### Response - Response code 404 is returned with data *"Requested sample unavailable"* when the sample with the given hash isn't available. - Response code 200 is returned with data *"Sample sent for rescanning"* when the sample with the requested hash is found in storage. ## Rescan bulk query A bulk query will send multiple samples with requested hashes in a single request. There are also additional document elements describing ill-formatted hashes and hashes not found by the service. ### Request ``` POST /api/rescan/v1/bulk_query/{post_format}[?format=xml|json] ``` #### Path parameters - **post_format** defines the request's payload format #### Query parameters - **format** accepts the options *xml* or *json* and defines the return format #### Request body ``` json { "rl": { "query": { "hash_type": "string", "hashes": [ "string" ] } } } ``` - **hash_type** value will be accepted if it matches one of the following options: `md5`, `sha1`, `sha256` ### Response ``` json { "rl": { "sent_for_rescan": [ "string" ], "sample_unavailable": [ "string" ], "unknown_hashes": [ "string" ], "invalid_hashes": [ "string" ] } } ``` - `sent_for_rescan` - A list of hashes of samples sent for rescanning - `sample_unavailable` - A list of hashes of samples that are not available - `unknown_hashes` - A list of unknown hashes - `invalid_hashes` - A list of ill-formatted hashes provided in the request ## Examples ### Rescan single query request These examples use different hash types: ``` /api/rescan/v1/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b /api/rescan/v1/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd /api/rescan/v1/query/md5/ca083f61113e1fb8f539ecfa7c725fc8 ``` ### Rescan bulk query request These examples use different request body formats: ``` /api/rescan/v1/bulk_query/json /api/rescan/v1/bulk_query/xml ``` With bulk queries, the output format will default to the post format. If you want the output format to be different from the post format, add the **format** query field: ``` /api/rescan/v1/bulk_query/xml?format=json ``` ### Bulk JSON request ``` /api/rescan/v1/bulk_query/json ``` ``` json { "rl": { "query": { "hash_type": "md5", "hashes": [ "4bb64c06b1a72539e6d3476891daf17b", "6353de8f339b7dcc6b25356f5fbffa4e", "59cb087c4c3d251474ded9e156964d5d", "6c2eb9d1a094d362bcc7631f2551f5a4", "a82c781ce0f43d06c28fe5fc8ebb1ca9", "920f5ba4d08f251541c5419ea5fb3fb3" ] } } } ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "13e40f38427a55952359bfc5f52b5841ce1b46ba", "831fc2b9075b0a490adf15d2c5452e01e6feaa17", "42b05278a6f2ee006072af8830c103eab2ce045f" ] } } } ``` --- ## Reputation & Metadata Alerts API (tca-0206) — Spectra Intelligence # Reputation and metadata alerts (TCA-0206) The Reputation and Metadata Changes service allows users to subscribe to up to one billion sample and URL hashes, tracking changes in their status over a period of time. These subscriptions, valid for a duration of 1 year, enable users to monitor any changes to the subscribed samples or URLs. When changes occur, they are delivered through the [Data Change Feed API](#continuous-data-change-feed-query). To subscribe to a list of samples, users can: - use the Spectra Intelligence [Alert Subscription API](#how-to-use-the-alert-subscription-api-and-data-change-feed) - use the Spectra Intelligence [File Upload API](/SpectraIntelligence/API/Automation/tca-0202-0203) and set the query parameter `?subscribe=data_change` in their [metadata upload requests](/SpectraIntelligence/API/Automation/tca-0202-0203/#metadata-upload-request) To unsubscribe from the Data Change Feed for previously subscribed samples or URLs, users can use the Alert Subscription API - [Unsubscribe Query](#unsubscribe-query). ## General Info about Requests/Responses - All requests support the **format** parameter which allows changing the response format - Default response format is **xml**, except for bulk queries, where default format is the same as the POST format - The number of hashes in a bulk request must not be larger than one hundred (100) ## How to use the Alert Subscription API and Data Change Feed The subscription procedure consists of two general steps. ### Step 1 - Subscribe to samples Users submit a list of sample or URL hashes they want to track in a bulk HTTP POST request to the Alert Subscription API. The request body can be XML or JSON. Example: submitting a list of hashes as JSON ``` bash curl --location 'https://data.reversinglabs.com/api/subscription/data_change/v1/bulk_query/subscribe/json?format=json' \ --header 'Authorization: Basic bXNjb3R0OnRoYXQncyB3aGF0IHNoZSBzYWlkCg==' \ --header 'Content-Type: application/json' \ --data '{ "rl": { "query": { "hash_type": "sha1", "hashes": [ "a7afddb68260a60f86c02a021efba7f216c2e7cf", "ca03064987d3c4465f91552ba8b6a883eecfd3e5", "b363713a938afcd3c74603827fab79e935b2b09b" ] } } }' ``` ### Step 2 - Monitor changes to subscribed samples Users can poll the Data Change Feed using HTTP GET requests to check whether there have been any changes to the samples or URLs they have subscribed to. The Data Change Feed returns the *last_timestamp* value that can be used in the next request up until 60 seconds from the current time. The value determines the time period for which the user wants to retrieve information about changes to subscribed samples. For example: 1. User sends a subscription request at timestamp T0. 2. The user then issues a GET request at timestamp T1. 3. The request contains the T0 timestamp as the *last_timestamp* value, and the API returns the changes that happened between T0 and T1 (if there have been any changes). The response returned by the API contains SHA1 hashes of subscribed samples or URLs and sections that have changed in the requested period of time. For every sample with detected changes, the following sections are included. For URLs, only `dynamic_analysis` applies. - `xref`: AV scanning results have been updated. - `sample_available`: The sample has become available for processing. - `malware_presence`: The sample's Malware Presence classification, or any part of its metadata, has changed (including changes to the sample's Malicious/Unknown/Suspicious/Known status). - `sample_became_shareable`: The sample became shareable and is available for download. - `dynamic_analysis`: Dynamic analysis report has been completed and is available for querying. ## Subscribe query This query is used for subscribing to a list of samples or 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. ### Request ``` POST /api/subscription/data_change/v1/bulk_query/subscribe/{post_format} ``` #### Path parameters - `post_format` - Accepts the following values: `xml` or `json`. It defines the POST body format and the response format. #### Query parameters - `format` - Accepts the following values: `xml` or `json`. Can be used to override the default response format. #### Request body ``` json5 { "rl": { "query": { "hash_type": "string", // sha1, sha256, or md5 "hashes": [ "string" ] } } } ``` - `hash_type` can be *sha1*, *md5* or *sha256* for samples, and *sha1* for URLs that were seen by the Spectra Intelligence system. **Note:** Samples or URLs that have not yet been seen can be subscribed only with SHA1 hash values. - hash values must be valid hashes defined by the `hash_type` parameter ### Response ```json5 { "rl": { "subscription_data_change": { "hash_type": "string", // requested hash type "subscribed": [ "string" // list of successful subscriptions ], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" // only if MD5 or SHA256 were used ] } } } ``` ## Unsubscribe query This query is used for unsubscribing from a list of samples or URLs that the user was previously subscribed to. Submitting a sample or URL hash in a POST request to this endpoint removes the associated sample or URL 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 or URLs will no longer be delivered in the Data Change Feed. ### Request ``` POST /api/subscription/data_change/v1/bulk_query/unsubscribe/{post_format} ``` The request format (body, parameters) is identical to the format in the [subscribe query](#request). ### Response ```json5 { "rl": { "subscription_data_change": { "hash_type": "string", // requested hash type "unsubscribed": [ "string" // list of successful unsubscriptions ], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" // only if MD5 or SHA256 were used ] } } } ``` ## Examples ### Subscribe to a list of SHA1 hashes ``` /api/subscription/data_change/v1/bulk_query/subscribe/json ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "84dbb381485e6ee9d69fbad3c6f020be88230e9b", "81648fd7871017eef87e0efa166e00e891a6ea9d", "0761c95bd639466aff2d65c1c092e2cae40f900c", "552ec95c8ffe3a0cb014eee508b87730461c8f26", "d234189a25892325746699fe2ab39a40b2d14d6e" ] } } } ``` ### Unsubscribe from a list of SHA1 hashes ``` /api/subscription/data_change/v1/bulk_query/unsubscribe/json ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "84dbb381485e6ee9d69fbad3c6f020be88230e9b", "81648fd7871017eef87e0efa166e00e891a6ea9d", "0761c95bd639466aff2d65c1c092e2cae40f900c", "552ec95c8ffe3a0cb014eee508b87730461c8f26", "d234189a25892325746699fe2ab39a40b2d14d6e" ] } } } ``` ## Data change feed: PULL This query returns the next set of samples or URLs to which the user is subscribed. The starting point for this query is defined using the [START query](#data-change-feed-start). 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 and any surplus records sharing the same timestamp. This ensures that all the records with the same timestamp will be included in the set of records. The limit parameter must not be greater than 1000. This endpoint supports single threaded requests. Any concurrent request will be blocked until the previous one is fulfilled. ### Request ``` GET /api/feed/data_change/v3/pull ``` #### Query parameters - `events` - Accepts a list of sections that should be included in the response, delimited by commas. If omitted, includes all values. Otherwise, list one or more of the sections: - `xref` - `sample_available` - `malware_presence` - `sample_became_shareable` - `dynamic_analysis` - Optional - `format` - Specifies the response format. Supported values: - `xml` (default) - `json` - `tsv`(tab-separated values, delimiter character `\t` (`0x09`)) - Optional - `limit` - 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. - Optional ### Response ```json { "rl": { "data_change_feed": { "entries": [], "last_timestamp": 0, "time_range": {} } } } ``` ----------------------------------------------------------------------- `rl.data_change_feed.entries[]` ```json { "record_on": "string", "sha1": "string", "updated_sections": [ "string" ], "sha256": "string", "md5": "string" } ``` - `sha1` - SHA1 hash value of the sample or URL - `md5` - MD5 hash value of the sample, if available - `sha256` - SHA256 hash value of the sample, if available - `updated_sections` - See `rl.data_change_feed.entries[].updated_sections` ----------------------------------------------------------------------- `rl.data_change_feed.entries[].updated_sections` - `xref` - Changed AV scanning results - `malware_presence` - Changed Malware Presence result - `sample_became_shareable` - Sample become shareable and is available for download - `dynamic_analysis` - Dynamic analysis report completed and available for querying ----------------------------------------------------------------------- ## Data change feed: START This query sets the starting timestamp for the previously described *PULL query*. ### Request ``` PUT /api/feed/data_change/v3/start/{time_format}/{time_value} ``` #### Path parameters - `time_format` accepts these options: - `timestamp`: number of seconds since 1970-01-01 00:00:00 - `utc`: date and time in the format `YYYY-MM-DDThh:mm:ss` - `time_value` - Accepts values defined by individual option set by `time_format` ## Continuous data change feed query This query returns a set of records (samples or URLs) that the user is subscribed to from the requested timestamp onwards. Essentially it combines the START and PULL queries into one. The feed returns up to 1000 records and any surplus records sharing the same timestamp. The response also contains the latest timestamp up to which the events are included in the response. To fetch the next set, use the **last_timestamp** value from the response, increase it by 1 and submit it in a new request. The response format is the same as with the [PULL query](#data-change-feed-pull). ### Request ``` GET /api/feed/data_change/v3/query/{time_format}/{time_value} ``` #### Path parameters - `time_format` accepts these options: - `timestamp`: number of seconds since 1970-01-01 00:00:00 - `utc`: date and time in the format `YYYY-MM-DDThh:mm:ss` - `time_value` - Accepts values defined by individual option set by `time_format` #### Query parameters - `events` - Accepts a list of sections that should be included in the response, delimited by commas. If omitted, includes all values. Otherwise, list one or more of the sections: - `xref` - `sample_available` - `malware_presence` - `sample_became_shareable` - `dynamic_analysis` - Optional - `format` - Specifies the response format. Supported values: - `xml` (default) - `json` - `tsv`(tab-separated values, delimiter character `\t` (`0x09`)) - Optional - `limit` - 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. - Optional ## Examples - Get samples you subscribed to, set response format to JSON: `/api/feed/data_change/v3/pull?format=json` - Get samples that changed their classification: `/api/feed/data_change/v3/pull?events=malware_presence` - Get dynamic analysis changes and set the response format: `/api/feed/data_change/v3/pull?events=dynamic_analysis&format=json` - Set the start time for the pull query, use UTC: `/api/feed/data_change/v3/start/utc/2015-05-01T13:00:00` --- ## Certificate Threat Intelligence API — Spectra Intelligence The Certificate Threat Intelligence APIs help security teams investigate code signing certificates, identify samples signed with specific certificates, and detect impersonation attempts using compromised or malicious certificates. ## Common Use Cases ### Find samples signed with a certificate - **[Certificate index (TCA-0501)](tca-0501.md)** - Get a list of files signed with a specific certificate thumbprint, with optional filtering by classification status. ### Analyze certificate reputation - **[Certificate analytics (TCA-0502)](tca-0502.md)** - Get certificate reputation data including sample counts by classification, blacklist/whitelist status, threat level, and certificate chain of trust. ### Search for certificates by name - **[Certificate thumbprint search (TCA-0503)](tca-0503.md)** - Find certificate thumbprints by searching for common names or partial matches using wildcards. ## All Certificate Threat Intelligence APIs --- ## Certificate Index API (TCA-0501) — Spectra Intelligence # Certificate index (TCA-0501) This service provides a list of samples signed with a particular certificate, specified by its thumbprint. Samples are listed along with their reputation information and some other properties such as sample size, sample type, download availability, and more. The service also allows filtering the results by sample classification status. ## Certificate This query returns a list of SHA1 hashes for samples signed with the certificate matching the requested thumbprint. If the extended option is selected, the list of samples will include: > - reputation information - 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), as well as the hashes of files containing the sample(s); > - certificate validation The response can be filtered by sample classification status. ### Request ``` GET /api/certificate/index/v1/query/thumbprint/{thumbprint}/page/{next_page}?[format=xml|json]&[classification=MALICIOUS|SUSPICIOUS|KNOWN|UNKNOWN]&[limit={1-100}]&[extended=true|false] ``` Path parameters: - `thumbprint` - The thumbprint (*sha1*, *sha256*, *md5*) of the requested certificate - Required - `next_page` - An optional pagination parameter for retrieving the next page of the results. The pagination value for the next page is provided in the previous request response - Optional Query parameters: - `format` - Allows choosing between *xml* (default) and *json* format for the response - `limit` - Maximum number of samples to return in the certificate sample list. It is possible to choose a number between 1 and 100 (100 is the default value) - `extended` - Allows choosing between *true* - extended, and *false* - non-extended data set (default) - `classification` - If this parameter is provided in the request, the query will return a list of only those samples that match the requested classification. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN ### Response ```json { "rl": { "next_page": "string", "request": { "extended": 0, "limit": 3, "response_format": "string", "thumbprint": "string" }, "samples": { "item": [ "string", "string", "string" ] } } } ``` The query will return a list of `limit` samples signed with the certificate that matches the requested thumbprint. If the `limit` value is not provided in the request, 100 records will be returned by default. Response fields that will be returned depend on the selected data set. If the `extended` parameter is not set to *true*, only the list of sample SHA1 hashes will be returned. The `next_page` response field contains the hash value for the next page. This can be used with the `next_page` parameter in the following request to retrieve more samples. `rl.request` - `thumbprint` - Requested thumbprint - `limit` - Number of requested samples - `response_format` - Output format - `extended` - Return extended info for samples instead of just hashes - `page` - Page (only if the page is a part of the request) - `classification` - Classification (only if classification is a part of the request) ---------------------------------------------------------------------- `rl.samples[]` ```json { "container_sha1": "string", "sha1": "string", "pe_sha1": "string", "threat_level": 0, "classification": "string", "threat_name": "string", "sample_type": "string", "validation": [ "string" ], "sample_size": 0, "sample_available": 0, "platform": "string", "last_seen": "string", "malware_type": "string", "first_seen": "string", "sha256": "string", "pe_sha256": "string", "trust_factor": 0, "malware_family": "string", "md5": "string" } ``` - `sha1` - SHA1 - `sha256` - SHA256 - `md5` - MD5 - `pe_sha1` - SHA1 authentihash of the PE file used in the authenticode signing process - `pe_sha256` - SHA256 authentihash of the PE file used in the authenticode signing process - `container_sha1` - SHA1 of the sample container - `first_seen` - time when the sample was first seen (UTC) - `last_seen` - The last time when the sample received impactful changes that updated its threat intelligence report. (UTC) - `sample_type` - sample type - `sample_size` - sample size - `sample_available` - whether the sample is available for download - `classification` - classification of the sample - `platform` - platform targeted by the malware - `subplatform` - subplatform targeted by the malware - `threat_name` - threat name for malicious samples - `malware_type` - malware type for malicious samples - `malware_family` - malware family for malicious samples - `threat_level` - threat level of the sample - `trust_factor` - trust factor of the sample - `validation` - list of validation descriptions for a certificate regarding a sample at the time the sample was detected ## Examples ### Example 1 Retrieving a SHA1 list of 2 samples signed with a certificate with SHA256 thumbprint `86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A`. ``` /api/certificate/index/v1/query/thumbprint/86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A?limit=2 ``` ### Example 2 Retrieving a SHA1 list of samples signed with a certificate matching the requested SHA1 thumbprint `e1230631000216e59c20ed0e18f8f752b8489bb5`. ``` /api/certificate/index/v1/query/thumbprint/e1230631000216e59c20ed0e18f8f752b8489bb5?limit=2 ``` ### Example 3 Retrieving a list of 2 samples, with an extended data set in JSON format, signed with a certificate with the SHA256 thumbprint `709df96feede2cab2a5fb803beb599571d18a1d4`. ``` /api/certificate/index/v1/query/thumbprint/709df96feede2cab2a5fb803beb599571d18a1d4?limit=2&extended=true&format=json ``` ### Example 4 Retrieving one sample with an extended data set in JSON format, signed with a certificate with the SHA256 thumbprint `86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A` and `MALICIOUS` classification. ``` /api/certificate/index/v1/query/thumbprint/86900D438047F6D00ACE379C6E68A9461BA36ACD152C9E82EDDBE87B331F3E4A?limit=2&extended=true&format=json&classification=malicious ``` --- ## Certificate Analytics API (TCA-0502) — Spectra Intelligence # Certificate analytics (TCA-0502) This service provides certificate analytics for the requested certificate thumbprint and the certificate chain of trust. Analytics include a sample counter - number of samples signed by the certificate grouped by their classification, certificate status (blacklisted/whitelisted/undefined), time when the certificate was first seen, certificate trust factor, certificate threat level, and history of certificate blacklisting/whitelisting. The service also allows bulk requests for up to 100 thumbprints per request. ## Certificate Analytics The query returns certificate analytics for the requested certificate thumbprint and the certificate chain of trust. Analytics include: - real-time statistics (number of samples signed by the certificate, with samples grouped by their classification), - time when the certificate was first seen, - certificate classification status (blacklisted/whitelisted/undefined), - other certificate reputation data (threat level, trust factor, history of blacklisting/whitelisting, reason for whitelisting/blacklisting). ### Request ``` GET /api/certificate/analytics/v1/query/thumbprint/{thumbprint}?[format=xml|json] ``` Path parameters: - `thumbprint` - The thumbprint (*sha1*, *sha256*, *md5*) of the requested certificate - Required Query parameters: - `format` - Allows choosing between *xml* (default) and *json* format for the response - Optional The query will return certificate analytics for the requested thumbprint. ### Response ```json { "rl": { "request": {}, "certificate_analytics": {} } } ``` ---------------------------------------------------------------------- `rl.request` ```json { "response_format": "string", "thumbprint": "string" } ``` ---------------------------------------------------------------------- `rl.certificate_analytics` ```json { "certificate_first_seen": "string", "statistics": {}, "classification": {}, "certificate": {} } ``` - `certificate_first_seen` - When the certificate was first seen in ReversingLabs system (UTC) - `certificate` - Certificate information is presented as a signature chain. It includes information about issuer certificates recursively until root certificate is reached. Individual certificate information includes the following fields: **common_name, valid_from, valid_to, signature_algorithm, signature, extensions, certificate_thumbprints, serial_number, version, issuer** ---------------------------------------------------------------------- `rl.certificate_analytics.statistics` - `classification` - KNOWN/UNKNOWN/MALICIOUS/SUSPICIOUS/TOTAL - `sample_count` - Number of samples with each classification ---------------------------------------------------------------------- `rl.certificate_analytics.classification` - `status` - whitelisted/blacklisted/undefined - `reason` - Reason for whitelisting/blacklisting - `blacklisted_from` - Last valid signing time of the certificate that is now blacklisted - `whitelisted_to` - Property applicable only to certificates that were first whitelisted and then blacklisted; it should correspond to the **blacklisted_from** field - `threat_level` - 0-5; property of blacklisted certificates - `trust_factor` - 0-5; property of whitelisted certificates ## Certificate Analytics Bulk The bulk query returns certificate analytics in the same format as the single query, but for multiple certificate thumbprints in one response. ### Request ``` POST /api/certificate/analytics/v1/query/thumbprint/{post_format} ``` - **post_format** - allows choosing between `xml` and `json` format in the POST payload #### Request body ```json { "rl": { "query": { "thumbprints": [ "string", "string", "string", "string" ], "format": "string" } } } ``` - `thumbprint` - The thumbprint (*sha1*, *sha256*, *md5*) of the requested certificate. - Required - `format` - Allows choosing between `xml` (default) and `json` format for the response. - Required ### Response ```json { "rl": { "request": { "response_format": "string", "thumbprints": [] }, "invalid_thumbprints": [], "certificate_analytics": [] } } ``` - `request` - **thumbprint**: requested thumbprint; **format**: output format - `invalid_thumbprints` - List of ill-formatted thumbprints provided in the request - `certificate_analytics` - List of certificates matching the requested thumbprints with the same analytics data as in the single query ## Examples ### Example 1 - single query Retrieving certificate analytics for the thumbprint `A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1`, in JSON format. **Request** ``` /api/certificate/analytics/v1/query/thumbprint/A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1?format=json ``` **Response** ``` json { "rl": { "request": { "response_format": "json", "thumbprint": "A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1" }, "certificate_analytics": { "certificate_first_seen": "2022-09-14T08:05:10", "statistics": { "known": 77, "unknown": 1, "malicious": 0, "suspicious": 0, "total": 78 }, "classification": { "status": "undefined" }, "certificate": { "valid_from": "2022-06-14T04:02:43Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2025-07-12T07:06:34Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "False", "name": "Authority Information Access", "value": "CA Issuers - URI:http://secure.globalsign.com/cacert/gsgccr45evcodesignca2020.crt\nOCSP - URI:http://ocsp.globalsign.com/gsgccr45evcodesignca2020\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.3.6.1.4.1.4146.1.2\n CPS: https://www.globalsign.com/repository/\nPolicy: 2.23.140.1.3\n" }, { "is_critical": "False", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl.globalsign.com/gsgccr45evcodesignca2020.crl\n" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:25:9D:D0:FC:59:09:86:63:C5:EC:F3:B1:13:3B:57:1C:03:92:36:11\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "B9:8B:D3:79:F7:03:DC:12:78:E5:28:C2:AF:E8:61:4D:3E:E1:AC:E3" } ], "signature": "5B69F2E4D90E7BE365D1C7AC43371CB7776CEECA23F711A58800F1091BFABCC1B84E48ADAC4369227C12B4E245B3614E4A458EC2F4910F403A5C65AF14FB75D183C5CAEA2F1420728FAE1E982286FCDFFFC05B1CE0B1A7F20B40722AD54BB6DCC9E43A8C56B6F7095FC1A9BE7C66B8C7C5AF02F1796D5A83C571256B969FC26F7D7FC450D18424862E8CD1E025EEA76AA1960A98A9A3901BCEC5F0BE5C4EE75A3B54737E95458AE7945904FB998A00AFFD6EC08545B5617352444248D5AFF9F2AC565F8002F64C03FBFFD06052849F3C198AD516E7C6B711704B9F3A005076DDA3059DEBC975DB2F3965F589494E62DE687762783502E2E2EBA139A54300B59E116BA9CBD8323F7EB2C831A857D540E243C277C7DC59320AA3122E4A60E0908102342BFEC432407BD0F911E53D8C2CDF36A63FD1FE8DC271DF5F0CA0A32C6DC01DB8BD271F7766C2798F220171DDE4189C3411E88E0573D23291CDA2884217BB55458C8D4B957EFBC8B0D58F88490924C68E1BE8A7348C3F490B7D4158DB936902FF473A033A2F78F311FB44EEF9C2547A1632CEE370A20D3E9042C49C219C877AE9DB73E0542657A66F27C7EA7C3B594CCC4CD0BDEFC3B40443DBE4AA0E7875684531C6E51BCCF876BD9AA052E0A15FF5BBE1D5E77F63E80E3C5D08D200CAE0C5BC219A89DF67FA38C60EB60FFDA27324DEC43EBBB2E37BF341458B075084B5", "common_name": "Reallusion Inc.", "serial_number": "67C6DAAFB381A5567534EB0F", "certificate_thumbprints": [ { "name": "MD5", "value": "3b5d3951bd5930863767cd86a4ba27c5" }, { "name": "SHA1", "value": "e18af391a8ba1ae94eb61794c573c5a9856c80d3" }, { "name": "SHA256", "value": "A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1" } ], "issuer": "GlobalSign GCC R45 EV CodeSigning CA 2020" } } } } ``` ### Example 2 - single query Retrieving certificate analytics for the thumbprint `E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4`, in JSON format. **Request** ``` /api/certificate/analytics/v1/query/thumbprint/E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4?format=json ``` **Response** ``` json { "rl": { "request": { "response_format": "json", "thumbprint": "E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4" }, "certificate_analytics": { "certificate_first_seen": "2022-09-15T05:09:36", "statistics": { "known": 0, "unknown": 0, "malicious": 1, "suspicious": 0, "total": 1 }, "classification": { "status": "undefined" }, "certificate": { "valid_from": "2022-08-16T16:45:04Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2023-08-16T16:45:03Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:09:FE:C0:15:90:F9:AF:64:0A:92:12:B9:26:28:63:0C:97:EC:A7:B2\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "CA Issuers - URI:http://certs.apple.com/wwdrg3.der\nOCSP - URI:http://ocsp.apple.com/ocsp03-wwdrg305\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.2.840.113635.100.5.1\n User Notice:\n Explicit Text: Reliance on this certificate by any party assumes acceptance of the then applicable standard terms and conditions of use, certificate policy and certification practice statements.\n CPS: https://www.apple.com/certificateauthority/\n" }, { "is_critical": "True", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "8B:DB:F3:20:E4:7F:AD:DD:DB:04:07:B8:D0:F4:EF:03:82:21:A1:50" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "True", "name": "1.2.840.113635.100.6.1.7", "value": ".." }, { "is_critical": "True", "name": "1.2.840.113635.100.6.1.4", "value": ".." } ], "signature": "D8506E1AD8408E4A9850644A2870525B362FBF5C74DCEF62AB73E3EB2BFC178D66168F491FF4CD894D1CD0FD3C799236C7FD41A114A1DA33EB87AAA89B51F532DFA461DCF383B1CE388E03ABB3B710925ED477EE546F5D7BAF7066E9D397D522F86CBAB8E6470B419E5CA16A9946356D4B50523E28CF852EB1BE912A215AD527F32690C1CD0DA294834AC5D06E745D6DD20077F0613F65F8547CC3BA9271BFD03A4C1245147F0197D687193E9086059AFB1997DDCA54BF7F0914C3FDC873629FAC16B5129C461A61BF28863902B87CA04E33FEC390C756C1D0556ED04B41C8B95C4AE53C6BF7422BD7D9705EA0D3984D665A2536419556ACCFEB5717B7112ACE", "common_name": "Apple Distribution: The Dash Foundation, Inc. (44RJ69WHFF)", "serial_number": "733E6B713464528602D5CA7DB152C6D6", "certificate_thumbprints": [ { "name": "MD5", "value": "cb702899b0e4a8e748678e6b8acde556" }, { "name": "SHA1", "value": "0463c9bff6b702da41487c8440fd02f5c5e239c1" }, { "name": "SHA256", "value": "E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4" } ], "issuer": { "valid_from": "2020-02-19T18:13:47Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2030-02-20T00:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE, pathlen:0" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.apple.com/ocsp03-applerootca\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl.apple.com/root.crl\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "09:FE:C0:15:90:F9:AF:64:0A:92:12:B9:26:28:63:0C:97:EC:A7:B2" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "1.2.840.113635.100.6.2.1", "value": ".." } ], "signature": "AD6513E8F6E0817744024742BE5FA53920EA62A9FDC590C97313D59E9BD0AA0F8D8DCBED01CF6C28405BC7552441F8FCCFC1B523E9DCECF16FCA801D77C2C461492567AF0FCA3925ADD3E37ACC33280D0E2EA1574073FAE65CAE065129EDE3850C4F61DC32168B77D044CA5D720331469CAE9B401AFAF4E0D33EFA2F8C669F97C45459EFD248F4079949605919C7DD94D1C0C16C7F7821EF0CEB3B6C99824B526038B539826DEC523153BE0F914C4949748FA651CB84474E1D75276EBDF9D25CF37FC26C0B0936E264E4C237031419D5EA6A94AAA9DBFEF69A08678BEF2BB8AA174983AFCFCBBCE9CFEA9571B0B445A2CCE587AA0AC3413A795CDA50349D953B", "common_name": "Apple Worldwide Developer Relations Certification Authority", "serial_number": "7CAF690A25B739FE7B9B447AC178C5EE", "certificate_thumbprints": [ { "name": "MD5", "value": "08a45128fa238443623421dd2c9887ab" }, { "name": "SHA1", "value": "06ec06599f4ed0027cc58956b4d3ac1255114f35" }, { "name": "SHA256", "value": "DCF21878C77F4198E4B4614F03D696D89C66C66008D4244E1B99161AAC91601F" } ], "issuer": { "valid_from": "2006-04-25T21:40:36Z", "signature_algorithm": "sha1WithRSAEncryption", "valid_to": "2035-02-09T21:40:36Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Certificate Sign, CRL Sign" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.2.840.113635.100.5.1\n CPS: https://www.apple.com/appleca/\n User Notice:\n Explicit Text: Reliance on this certificate by any party assumes acceptance of the then applicable standard terms and conditions of use, certificate policy and certification practice statements.\n" } ], "signature": "5C36994C2D78B7ED8C9BDCF3779BF276D277304FC11F8583851B993D4737F2A99B408E2CD4B19012D8BEF4739BEED2640FCB794F34D8A23EF978FF6BC807EC7D39838B5320D338C4B1BF9A4F0A6BFF2BFC59A705097C174056111E74D3B78B233B47A3D56F24E2EBD1B770DF0F45E127CAF16D78EDE7B51717A8DC7E2235CA25D5D90FD66BD4A2242311F7A1AC8F738160C61B5B092F92B2F84448F060389E15F53D2667208A336AF70D82CFDEEBA32FF9536A5B64C0633377F73A072C56EBDA0F210EDABA73194FB5D9367FC18755D9A799B93242FBD8D5719E7EA152B71BBD934224122AC70F1DB64D9C5E63C84B801750AA8AD5DAE4FCD0090737B0757521", "common_name": "Apple Root CA", "serial_number": "02", "certificate_thumbprints": [ { "name": "MD5", "value": "7e611e0f7ba31b51986f413b41383ef0" }, { "name": "SHA1", "value": "611e5b662c593a08ff58d14ae22452d198df6c60" }, { "name": "SHA256", "value": "B0B1730ECBC7FF4505142C49F1295E6EDA6BCAED7E2C68C5BE91B5A11001F024" } ], "issuer": "Apple Root CA" } } } } } } ``` ### Example 3 - bulk query Retrieving certificate analytics in JSON format for thumbprints `A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1`, `E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4`, and `ABC` via POST request in JSON format. **Request** ``` /api/certificate/analytics/v1/query/thumbprint/json ``` ``` json { "rl": { "query": { "thumbprints": [ "A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1", "E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4", "ABC" ], "format": "json" } } } ``` **Response** ``` json { "rl": { "invalid_thumbprints": [ "ABC" ], "request": { "response_format": "json", "thumbprints": [ "A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1", "ABC", "E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4" ] }, "certificate_analytics": [ { "certificate_first_seen": "2022-09-14T08:05:10", "statistics": { "known": 77, "unknown": 2, "malicious": 0, "suspicious": 0, "total": 79 }, "classification": { "status": "undefined" }, "certificate": { "valid_from": "2022-06-14T04:02:43Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2025-07-12T07:06:34Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "False", "name": "Authority Information Access", "value": "CA Issuers - URI:http://secure.globalsign.com/cacert/gsgccr45evcodesignca2020.crt\nOCSP - URI:http://ocsp.globalsign.com/gsgccr45evcodesignca2020\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.3.6.1.4.1.4146.1.2\n CPS: https://www.globalsign.com/repository/\nPolicy: 2.23.140.1.3\n" }, { "is_critical": "False", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl.globalsign.com/gsgccr45evcodesignca2020.crl\n" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:25:9D:D0:FC:59:09:86:63:C5:EC:F3:B1:13:3B:57:1C:03:92:36:11\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "B9:8B:D3:79:F7:03:DC:12:78:E5:28:C2:AF:E8:61:4D:3E:E1:AC:E3" } ], "signature": "5B69F2E4D90E7BE365D1C7AC43371CB7776CEECA23F711A58800F1091BFABCC1B84E48ADAC4369227C12B4E245B3614E4A458EC2F4910F403A5C65AF14FB75D183C5CAEA2F1420728FAE1E982286FCDFFFC05B1CE0B1A7F20B40722AD54BB6DCC9E43A8C56B6F7095FC1A9BE7C66B8C7C5AF02F1796D5A83C571256B969FC26F7D7FC450D18424862E8CD1E025EEA76AA1960A98A9A3901BCEC5F0BE5C4EE75A3B54737E95458AE7945904FB998A00AFFD6EC08545B5617352444248D5AFF9F2AC565F8002F64C03FBFFD06052849F3C198AD516E7C6B711704B9F3A005076DDA3059DEBC975DB2F3965F589494E62DE687762783502E2E2EBA139A54300B59E116BA9CBD8323F7EB2C831A857D540E243C277C7DC59320AA3122E4A60E0908102342BFEC432407BD0F911E53D8C2CDF36A63FD1FE8DC271DF5F0CA0A32C6DC01DB8BD271F7766C2798F220171DDE4189C3411E88E0573D23291CDA2884217BB55458C8D4B957EFBC8B0D58F88490924C68E1BE8A7348C3F490B7D4158DB936902FF473A033A2F78F311FB44EEF9C2547A1632CEE370A20D3E9042C49C219C877AE9DB73E0542657A66F27C7EA7C3B594CCC4CD0BDEFC3B40443DBE4AA0E7875684531C6E51BCCF876BD9AA052E0A15FF5BBE1D5E77F63E80E3C5D08D200CAE0C5BC219A89DF67FA38C60EB60FFDA27324DEC43EBBB2E37BF341458B075084B5", "common_name": "Reallusion Inc.", "serial_number": "67C6DAAFB381A5567534EB0F", "certificate_thumbprints": [ { "name": "MD5", "value": "3b5d3951bd5930863767cd86a4ba27c5" }, { "name": "SHA1", "value": "e18af391a8ba1ae94eb61794c573c5a9856c80d3" }, { "name": "SHA256", "value": "A481635184832F09BC3D3921A335634466C4C6FC714D8BBD89F65E827E5AF1B1" } ], "issuer": "GlobalSign GCC R45 EV CodeSigning CA 2020" } }, { "certificate_first_seen": "2022-09-15T05:09:36", "statistics": { "known": 0, "unknown": 0, "malicious": 1, "suspicious": 0, "total": 1 }, "classification": { "status": "undefined" }, "certificate": { "valid_from": "2022-08-16T16:45:04Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2023-08-16T16:45:03Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:09:FE:C0:15:90:F9:AF:64:0A:92:12:B9:26:28:63:0C:97:EC:A7:B2\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "CA Issuers - URI:http://certs.apple.com/wwdrg3.der\nOCSP - URI:http://ocsp.apple.com/ocsp03-wwdrg305\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.2.840.113635.100.5.1\n User Notice:\n Explicit Text: Reliance on this certificate by any party assumes acceptance of the then applicable standard terms and conditions of use, certificate policy and certification practice statements.\n CPS: https://www.apple.com/certificateauthority/\n" }, { "is_critical": "True", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "8B:DB:F3:20:E4:7F:AD:DD:DB:04:07:B8:D0:F4:EF:03:82:21:A1:50" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "True", "name": "1.2.840.113635.100.6.1.7", "value": ".." }, { "is_critical": "True", "name": "1.2.840.113635.100.6.1.4", "value": ".." } ], "signature": "D8506E1AD8408E4A9850644A2870525B362FBF5C74DCEF62AB73E3EB2BFC178D66168F491FF4CD894D1CD0FD3C799236C7FD41A114A1DA33EB87AAA89B51F532DFA461DCF383B1CE388E03ABB3B710925ED477EE546F5D7BAF7066E9D397D522F86CBAB8E6470B419E5CA16A9946356D4B50523E28CF852EB1BE912A215AD527F32690C1CD0DA294834AC5D06E745D6DD20077F0613F65F8547CC3BA9271BFD03A4C1245147F0197D687193E9086059AFB1997DDCA54BF7F0914C3FDC873629FAC16B5129C461A61BF28863902B87CA04E33FEC390C756C1D0556ED04B41C8B95C4AE53C6BF7422BD7D9705EA0D3984D665A2536419556ACCFEB5717B7112ACE", "common_name": "Apple Distribution: The Dash Foundation, Inc. (44RJ69WHFF)", "serial_number": "733E6B713464528602D5CA7DB152C6D6", "certificate_thumbprints": [ { "name": "MD5", "value": "cb702899b0e4a8e748678e6b8acde556" }, { "name": "SHA1", "value": "0463c9bff6b702da41487c8440fd02f5c5e239c1" }, { "name": "SHA256", "value": "E199A1AE82E44F824C3086C1704B7CC0004364371316951992008A5E976A42C4" } ], "issuer": { "valid_from": "2020-02-19T18:13:47Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2030-02-20T00:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE, pathlen:0" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.apple.com/ocsp03-applerootca\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl.apple.com/root.crl\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "09:FE:C0:15:90:F9:AF:64:0A:92:12:B9:26:28:63:0C:97:EC:A7:B2" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "1.2.840.113635.100.6.2.1", "value": ".." } ], "signature": "AD6513E8F6E0817744024742BE5FA53920EA62A9FDC590C97313D59E9BD0AA0F8D8DCBED01CF6C28405BC7552441F8FCCFC1B523E9DCECF16FCA801D77C2C461492567AF0FCA3925ADD3E37ACC33280D0E2EA1574073FAE65CAE065129EDE3850C4F61DC32168B77D044CA5D720331469CAE9B401AFAF4E0D33EFA2F8C669F97C45459EFD248F4079949605919C7DD94D1C0C16C7F7821EF0CEB3B6C99824B526038B539826DEC523153BE0F914C4949748FA651CB84474E1D75276EBDF9D25CF37FC26C0B0936E264E4C237031419D5EA6A94AAA9DBFEF69A08678BEF2BB8AA174983AFCFCBBCE9CFEA9571B0B445A2CCE587AA0AC3413A795CDA50349D953B", "common_name": "Apple Worldwide Developer Relations Certification Authority", "serial_number": "7CAF690A25B739FE7B9B447AC178C5EE", "certificate_thumbprints": [ { "name": "MD5", "value": "08a45128fa238443623421dd2c9887ab" }, { "name": "SHA1", "value": "06ec06599f4ed0027cc58956b4d3ac1255114f35" }, { "name": "SHA256", "value": "DCF21878C77F4198E4B4614F03D696D89C66C66008D4244E1B99161AAC91601F" } ], "issuer": { "valid_from": "2006-04-25T21:40:36Z", "signature_algorithm": "sha1WithRSAEncryption", "valid_to": "2035-02-09T21:40:36Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Certificate Sign, CRL Sign" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:2B:D0:69:47:94:76:09:FE:F4:6B:8D:2E:40:A6:F7:47:4D:7F:08:5E\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 1.2.840.113635.100.5.1\n CPS: https://www.apple.com/appleca/\n User Notice:\n Explicit Text: Reliance on this certificate by any party assumes acceptance of the then applicable standard terms and conditions of use, certificate policy and certification practice statements.\n" } ], "signature": "5C36994C2D78B7ED8C9BDCF3779BF276D277304FC11F8583851B993D4737F2A99B408E2CD4B19012D8BEF4739BEED2640FCB794F34D8A23EF978FF6BC807EC7D39838B5320D338C4B1BF9A4F0A6BFF2BFC59A705097C174056111E74D3B78B233B47A3D56F24E2EBD1B770DF0F45E127CAF16D78EDE7B51717A8DC7E2235CA25D5D90FD66BD4A2242311F7A1AC8F738160C61B5B092F92B2F84448F060389E15F53D2667208A336AF70D82CFDEEBA32FF9536A5B64C0633377F73A072C56EBDA0F210EDABA73194FB5D9367FC18755D9A799B93242FBD8D5719E7EA152B71BBD934224122AC70F1DB64D9C5E63C84B801750AA8AD5DAE4FCD0090737B0757521", "common_name": "Apple Root CA", "serial_number": "02", "certificate_thumbprints": [ { "name": "MD5", "value": "7e611e0f7ba31b51986f413b41383ef0" }, { "name": "SHA1", "value": "611e5b662c593a08ff58d14ae22452d198df6c60" }, { "name": "SHA256", "value": "B0B1730ECBC7FF4505142C49F1295E6EDA6BCAED7E2C68C5BE91B5A11001F024" } ], "issuer": "Apple Root CA" } } } } ] } } ``` --- ## Certificate Thumbprint Search API (TCA-0503) — Spectra Intelligence # Certificate thumbprint search (TCA-0503) This service provides a list of thumbprints (MD5, SHA1, SHA256) for certificates matching the requested common name or common name part. ## Certificate Search Query The query returns common names matching the request, along with the list of thumbprints of all the certificates sharing that common name. The common name in the request can contain a wildcard `*` which substitutes any subset of all possible characters. For retrieving the next page of the results, both of the pagination arguments should be provided in the request. ### Request ``` POST /api/certificate/search/v1/query/subject/{post_format} ``` Path parameters: - `post_format` - allows choosing between XML and JSON format in the POST payload #### Request body ``` json { "rl": { "query": { "common_name": "string", "response_format": "string", "limit": 5, "page_common_name": "string", "page_thumbprint": "string" } } } ``` - `common_name` - Common name can contain a wildcard '\*’ which substitutes any subset of all possible characters (for example, if we want all certificates with a common name that contains the word "Windows" we would type *Windows*. If we want all certificates with a common name that begins with the word "Windows", we would type Windows\*) - Required - `limit` - Maximum number of certificate thumbprints to be returned. It is possible to choose a number between 1 and 100 (100 is used by default) - Optional - `page_common_name` - 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` - Optional - `page_thumbprint` - 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` - Optional - `response_format` - Allows choosing between XML and JSON format for the response. Default is xml. - Optional ### Response The query will return all common names matching the requested common name, along with the list of thumbprints of all the certificates sharing that common name. ```json { "rl": { "next_page_common_name": "string", "search": [], "next_page_thumbprint": "string", "request": {} } } ``` - `request` - **common_name**: requested common name; **response_format**: output format; **limit**: number of requested samples; **page_common_name**: requested page common name value; **page_thumbprint**: requested page thumbprint value - `next_page_common_name` - Pagination value for retrieving the next page (if it exists) - `next_page_thumbprint` - Pagination value for retrieving the next page (if it exists) - `search` - **common_name**: common name matching the requested name; **thumbprints**: list of certificate thumbprints associated with the requested common name ## Examples ### Request `/api/certificate/search/v1/query/subject/json` ```json { "rl": { "query": { "common_name": "Microsoft", "response_format": "json", "limit": 5 } } } ``` ### Response
Response ```json { "rl": { "next_page_common_name": "Microsoft", "search": [ { "common_name": "Microsoft", "thumbprints": [ { "certificate_thumbprints": [ { "name": "MD5", "value": "91888389aa2cac07c610f469e5f18092" }, { "name": "SHA1", "value": "e8a53bed75c33d48cf49382ddba6b048e85072b2" }, { "name": "SHA256", "value": "0AF958372FEDCFA29B8DD4C6DB83D44DC25AC6AD2435ACA5C0B08DCD5D596828" } ] }, { "certificate_thumbprints": [ { "name": "MD5", "value": "f971881e5219b17d98c181d50440d3d0" }, { "name": "SHA1", "value": "b5d1c90c8e8036610094bb6182d6c3f7481cd9eb" }, { "name": "SHA256", "value": "0F59B2A0809BE2B87728DCE7051C81FFD005A00CEA60FF1F0D7E11C911C8BBAB" } ] }, { "certificate_thumbprints": [ { "name": "MD5", "value": "2377666edb5a4d5656f68e002efb8415" }, { "name": "SHA1", "value": "4f0333347b6f953b33966e976f24c5da36d75143" }, { "name": "SHA256", "value": "18254B1DC375B74E339EB99ABFE31AF0D735CB5A3B535570731175811D735B0D" } ] }, { "certificate_thumbprints": [ { "name": "MD5", "value": "e0379a7291368975ffa2c8c10cb71fe7" }, { "name": "SHA1", "value": "c8f9dd2174879e6d50def833c68338fe4227c26f" }, { "name": "SHA256", "value": "0695208909EDBFD9AEBAAF712EEE1FC7916BC0F563475CDEE5E64F497D7563D0" } ] }, { "certificate_thumbprints": [ { "name": "MD5", "value": "2acdfc999c7b50813635718cfb0eea7f" }, { "name": "SHA1", "value": "39c4da3d122c4bc9369928464377ead34878d4a6" }, { "name": "SHA256", "value": "2606995A71C2128D6410DE8F1D7C199C5254F677FA44EA312C32A8B991F32C5F" } ] } ] } ], "next_page_thumbprint": "2606995A71C2128D6410DE8F1D7C199C5254F677FA44EA312C32A8B991F32C5F", "request": { "common_name": "Microsoft", "limit": 5, "response_format": "json" } } } ```
--- ## Customer Administration & Usage API — Spectra Intelligence The Customer Usage API provides visibility and control over your Spectra Intelligence account, including user management, license monitoring, and usage tracking. ## Common Use Cases ### Manage your account - **[Customer usage (TCA-9999)](tca-9999.md)** - View company information, create and manage users, list licenses and limits, monitor usage, and configure automated usage alerts. ## All Customer Usage APIs --- ## Customer Usage (TCA-9999) — Spectra Intelligence The **TCA-9999 API** provides authenticated Spectra Intelligence customers with full visibility and control over their licensed services. It enables: - **Viewing company information and users** - **Creating and managing users** - **Listing and managing licenses and limits** - **Monitoring usage and limits** - **Configuring automated usage alerts** All responses are returned in **JSON**. Authentication uses **Basic Auth** with Spectra Intelligence credentials. **Licensing and Management endpoints are rate limited to 12 requests per minute.** **Usage and Monitoring endpoints are not rate limited.** **Note: Spectra Intelligence Account Self-Management** Licensing and Management endpoints are available as an optional add-on for account self-management. To enable these capabilities for your organization, contact your sales representative or open a support ticket. ## Licensing and Management ### Company #### Company Information Returns the number of users and the company name for the company the authenticated user belongs to. ``` GET /api/customer_usage/v1/management/companies ``` **Response** ```json { "name": "Company", "user_count": 250 } ``` **Response Fields** - `name` - The name of the company. - Type: `string` - Always present. - `user_count` - The number of users in the company. - Type: `integer` - Always present. --- ### Users #### Create User Creates a new user. **Important: This is the only user-related endpoint that returns a `password` for the created user. If the password is lost, create a new password using the `reset-password` endpoint.** **Important: Once created, users cannot be deleted. To disable a user, set the `enabled` field to `false`. There is a global limit of 1000 users, after which no new users can be created.** ``` POST /api/customer_usage/v1/management/users ``` **Request Fields** - `username` - The username of the user to create. Must be alphanumeric, and `/` is allowed. - The first and last characters must be alphanumeric. This is the last segment of the username, without the `/u/company/` prefix. - The value cannot contain `test`, `demo`, `temp`, or `trial`. - Required - `email_addresses[]` - The email addresses of the user to create. - Required - `description` - User description. - Required - `enabled` - Whether the user is enabled. - Required ```json { "username": "username", "email_addresses": ["email1@gmail.com","email2@gmail.com"], "description": "User description", "enabled": true } ``` **Response** ```json { "rl": { "created_at": "2025-10-15T05:21:38+0000", "description": "User description", "email_addresses": [ "email1@gmail.com", "email2@gmail.com" ], "enabled": true, "password": "p4ssw0rd", "updated_at": null, "username": "u/company/user" } } ``` **Response Fields** - `created_at` - The date and time when the user was created. - Type: `string` - Always present. - `description` - The user description. - Type: `string` - Optional. - `email_addresses[]` - The list of email addresses associated with the user. - Type: `array[string]` - Always present. - `enabled` - Whether the user is currently enabled. - Type: `boolean` - Always present. - `password` - The generated password for the new user. - Returned only during creation. - Type: `string` - `updated_at` - The date and time the user was last updated, or `null` if never updated. - Type: `string`, nullable - `username` - The full username of the created user. - Type: `string` - Always present. #### List Users Returns a list of all users in the company. ``` GET /api/customer_usage/v1/management/users ``` **Request Parameters** - `page` - `page={page_number}` - Return a specific page. - Optional - `size` - `size={page_size}` - The number of users to return per page. - Optional **Response** ```json { "rl": { "page": { "current_page": 1, "next": "/api/customer_usage/v1/management/users?size=5&page=2", "previous": null, "total_pages": 3, "total_records": 11 }, "users": [ { "created_at": "2024-07-26T09:09:46+0000", "description": "User description", "email_addresses": [ "user@example.com" ], "enabled": true, "updated_at": null, "username": "u/company/user/1234" }, ... ] } } ``` **Response Fields** - `page` - `current_page` - The current page number. - Type: `integer` - Always present. - `next` - The URL for the next page, or `null` if there is no next page. - Type: `string`, nullable - Always present. - `previous` - The URL for the previous page, or `null` if there is no previous page. - Type: `string`, nullable - Always present. - `total_pages` - The total number of pages. - Type: `integer` - Always present. - `total_records` - The total number of records. - Type: `integer` - Always present. - `users[]` - The list of users. - Type: `array[object]` - Always present. - `users[].created_at` - The date and time when the user was created. - Type: `string` - Always present. - `users[].description` - The user description. - Type: `string` - Optional. - `users[].email_addresses[]` - The list of email addresses associated with the user. - Type: `array[string]` - Always present. - `users[].enabled` - Whether the user is currently enabled. - Type: `boolean` - Always present. - `users[].updated_at` - The date and time the user was last updated, or `null` if never updated. - Type: `string`, nullable - Always present. - `users[].username` - The full username of the created user. - Type: `string` - Always present. #### Retrieve User ``` GET /api/customer_usage/v1/management/users/{username} ``` `{username}` must be **base64-encoded**. **Response** ```json { "rl": { "created_at": "2025-10-15T05:21:38+0000", "description": "Test user", "email_addresses": [ "self.service@test.com" ], "enabled": true, "updated_at": null, "username": "u/company/username" } } ``` **Response Fields** - `created_at` - The date and time when the user was created. - Type: `string` - Always present. - `description` - The user description. - Type: `string` - Optional. - `email_addresses[]` - The list of email addresses associated with the user. - Type: `array[string]` - Always present. - `enabled` - Whether the user is currently enabled. - Type: `boolean` - Always present. - `updated_at` - The date and time the user was last updated, or `null` if never updated. - Type: `string`, nullable - Always present. - `username` - The full username of the created user. - Type: `string` - Always present. #### Update User Updates an existing user. All fields are optional. ``` PUT /api/customer_usage/v1/management/users/{username} ``` `{username}` must be **base64-encoded**. **Request** ```json { "description": "Updated user for integration testing", "email_addresses": [ "self.service@test.com", "secondary.contact@test.com" ], "enabled": false } ``` **Request Fields** Any of the fields from the **Retrieve User** response can be updated. **Response** ```json { "rl": { "created_at": "2025-10-15T05:21:38+0000", "description": "Updated user for integration testing", "email_addresses": [ "self.service@test.com", "secondary.contact@test.com" ], "enabled": false, "updated_at": "2025-10-15T05:28:57+0000", "username": "u/neworg/selfservice1234" } } ``` #### Reset Password Resets the user's password. ``` PUT /api/customer_usage/v1/management/users/{username}/password-reset ``` - `{username}` must be **base64-encoded**. - `old_password_expiration_date` is optional. If not provided, the password rotation grace period defaults to 1 hour from the time of the request. **Request** ```json { "old_password_expiration_date": "2025-11-01T00:00:00Z" } ``` **Response** ```json { "rl": { "password": "n3wp4ssw0rd" } } ``` --- ### Licenses #### List Licenses Returns a list of all licenses for the company. ``` GET /api/customer_usage/v1/management/licenses ``` **Request Parameters** - `page` - `page={page_number}` - Return a specific page. - Optional - `size` - `size={page_size}` - The number of licenses to return per page. - Optional **Response** ```json { "rl": { "licenses": [ { "available_limit": 10000, "created_at": "2025-09-30T08:54:09+0000", "end_date": "2026-09-30", "id": 6427, "is_unlimited": false, "limit": 10000, "limit_type": "DAILY", "products": [ "TCA-0314" ], "start_date": "2025-09-30", "strain": "PRODUCTS", "type": "ACTIVE", "updated_at": "2025-09-30T09:03:41+0000" }, ... ], "page": { "current_page": 1, "next": null, "previous": null, "total_pages": 1, "total_records": 2 } } } ``` **Response Fields** **Response Fields** - `licenses[]` - A list of license objects returned for the company. - `licenses[].available_limit` - The available limit for the license. - Optional - `licenses[].created_at` - The date and time the license was created. - Optional - `licenses[].end_date` - The end date of the license. - Optional - `licenses[].id` - The ID of the license. - Optional - `licenses[].is_unlimited` - Whether the license is unlimited. - Optional - `licenses[].limit` - The limit of the license. - Optional - `licenses[].limit_type` - The limit type of the license. - Optional - `licenses[].products[]` - The products associated with the license. - Optional - `licenses[].start_date` - The start date of the license. - Optional - `licenses[].strain` - The strain of the license. Can be either `PRODUCTS` or `BUNDLE`. - Optional - `licenses[].type` - The type of the license. - Optional - `licenses[].updated_at` - The date and time the license was updated. - Optional - `page.current_page` - The current page number of results. - Optional - `page.next` - The URL of the next page of results, or `null` if there is no next page. - Optional - `page.previous` - The URL of the previous page of results, or `null` if there is no previous page. - Optional - `page.total_pages` - The total number of pages available. - Optional - `page.total_records` - The total number of records across all pages. - Optional --- ### Limits #### Create Limit Creates a new limit. ``` POST /api/customer_usage/v1/management/limits ``` **Request Parameters** - `license_id` - The ID of the license to create the limit for. - Required - `is_unlimited` - Whether the limit is unlimited. Mutually exclusive with `limit`, unless `is_unlimited` is set to `false` - Optional - `limit` - The limit to set. Mutually exclusive with `is_unlimited`, unless `is_unlimited` is set to `false` - Optional - `strain` - The strain of the license to create the limit for. - Required - Can be either `PRODUCTS` or `BUNDLE` - `usernames[]` - The usernames to set the limit for. - Required ```json { "license_id": 6427, "is_unlimited": false, "limit": 10000, "strain": "PRODUCTS", "usernames": ["u/company/user"] } ``` **Response** ```json { "rl": { "id": 20939, "license_id": 6427, "is_unlimited": false, "limit": 10000, "strain": "PRODUCTS", "usernames": [ "u/company/user" ], "created_at": "2025-10-15T05:51:46+0000", "updated_at": null } } ``` **Response Fields** - `id` - The unique ID of the created limit. - Always present. - `license_id` - The ID of the license the limit belongs to. - Required. - `is_unlimited` - Whether the limit is unlimited. - Optional. - `limit` - The numeric value of the limit, if not unlimited. - Optional. - `strain` - The strain of the license the limit belongs to. - Required. - `usernames[]` - List of usernames the limit applies to. - Required. - `created_at` - Date and time when the limit was created. - Always present. - `updated_at` - Date and time when the limit was last updated, or `null` if never updated. - Optional. #### Read License Limits Returns a list of limits created for a specific license. ``` GET /api/customer_usage/v1/management/licenses/{strain}/{license_id}/limits ``` **Request Parameters** - `strain` - License strain. Can be either `PRODUCTS` or `BUNDLE`. `license_id` can repeat for different strains. - Required - `license_id` - `license_id={license_id}` - The ID of the license to read the limits for. Must be considered in combination with `strain`, as a license with the ID `1234` can exist for both `PRODUCTS` and `BUNDLE` strains. - Required - `page` - `page={page_number}` - Return a specific page. - Optional - `size` - `size={page_size}` - The number of limits to return per page. - Optional **Response** ```json { "rl": { "limits": [ { "created_at": "2025-10-15T05:51:46+0000", "id": 20939, "is_unlimited": false, "license_id": 6427, "limit": 10000, "updated_at": null, "usernames": [ "u/company/user" ], "strain": "PRODUCTS" }, { "created_at": "2025-10-15T05:51:46+0000", "id": 20940, "is_unlimited": false, "license_id": 6428, "limit": 10000, "updated_at": null, "usernames": [ "u/company/user" ], "strain": "BUNDLE" } ], "page": { "current_page": 1, "next": null, "previous": null, "total_pages": 1, "total_records": 1 } } } ``` #### Read User Limits Returns a list of limits created for a specific user. ``` GET /api/customer_usage/v1/management/users/{username}/limits ``` `{username}` must be **base64-encoded**. **Response** ```json { "rl": { "limits": [ { "created_at": "2025-10-15T05:51:46+0000", "id": 20939, "is_unlimited": false, "license_id": 6427, "limit": 10000, "updated_at": null, "usernames": [ "u/company/user" ], "strain": "PRODUCTS" }, { "created_at": "2025-10-15T05:51:46+0000", "id": 20940, "is_unlimited": false, "license_id": 6427, "limit": 10000, "updated_at": null, "usernames": [ "u/company/user" ], "strain": "BUNDLE" } ], "page": { "current_page": 1, "next": null, "previous": null, "total_pages": 1, "total_records": 1 } } } ``` **Response Fields** - `limits[]` A list of limits created for the specified user. Each limit object contains the following fields: - `limits[].id` The unique ID of the limit. Optional - `limits[].license_id` The ID of the license this limit is associated with. Optional - `limits[].is_unlimited` Indicates whether the limit is unlimited. Optional - `limits[].limit` The numeric value of the limit, if not unlimited. Optional - `limits[].usernames[]` A list of usernames this limit applies to. Optional - `limits[].created_at` The date and time the limit was created. Optional - `limits[].updated_at` The date and time the limit was last updated, or `null` if never updated. Optional - `limits[].strain` The strain of the license. Can be either `PRODUCTS` or `BUNDLE`. Optional - `page.current_page` The current page number of the results. Optional - `page.next` The URL of the next page of results, or `null` if there is no next page. Optional - `page.previous` The URL of the previous page of results, or `null` if there is no previous page. Optional - `page.total_pages` The total number of pages available. Optional - `page.total_records` The total number of records across all pages. Optional #### Update Limit Updates an existing limit. ``` PUT /api/customer_usage/v1/management/limits/{limit_id} ``` **Request** - `is_unlimited` - `is_unlimited={is_unlimited}` - Whether the limit is unlimited. - Optional - `limit` - `limit={limit}` - The limit to set. - Optional - `usernames` - `usernames={usernames}` - The usernames to set the limit for. - Optional ```json { "is_unlimited": false, "limit": 1000, "usernames": ["u/company/user", "u/company/user2"] } ``` **Response** ```json { "rl": { "created_at": "2025-10-15T05:51:46+0000", "id": 20939, "is_unlimited": false, "license_id": 6427, "limit": 1000, "updated_at": "2025-10-15T06:05:14+0000", "usernames": [ "u/company/user", "u/company/user2" ] } } ``` **Response Fields** - `id` The unique ID of the limit. Always present. - `license_id` The ID of the license this limit belongs to. Always present. - `is_unlimited` Indicates whether the limit is unlimited. Optional. - `limit` The numeric value of the limit, if not unlimited. Optional. - `usernames[]` The usernames this limit applies to. Optional. - `created_at` The date and time when the limit was created. Always present. - `updated_at` The date and time when the limit was last updated, or `null` if it hasn’t been updated yet. Optional. #### Delete Limit Deletes a limit. ``` DELETE /api/customer_usage/v1/management/limits/{limit_id} ``` **Path Parameters** - `limit_id` The ID of the limit to delete. Required **Response** `204 No Content` --- ## Usage and Monitoring The Customer Usage service allows the tracking of various usage and limit metrics of Spectra Intelligence services provisioned to the authenticated account, or to all accounts in a company. Daily, monthly and date range queries return the number of queries (and bytes if file size based limiting applies to the product) made in the requested time range for the current user, or the combined usage for all accounts within the company the current user belongs to. The Active YARA rulesets query returns information about the number of active YARA rulesets for the Spectra Intelligence account that sent the request. Quota limits queries return current service quota limits for APIs accessible to the authenticated user, or to all accounts within the company the current user belongs to. Provisioned services with no registered usage in the requested time range are not included in the response. ### Daily Usage #### User This query returns information about daily service usage for the Spectra Intelligence account that sent the request. If the date is not specified in the request, the service returns usage for the current date. The users can also specify a from-to time range (in days), to a maximum interval of 365 days. ``` GET /api/customer_usage/v1/usage/daily ``` #### Company This query returns information about combined daily service usage for all users in the company. If the date is not specified, the service returns usage for the current day. The users can also specify a from-to time range (in days), up to a maximum interval of 365 days. ``` GET /api/customer_usage/v1/usage/company/daily ``` #### Request Parameters - `user` - `user=u/company/user` - Return usage for the specified user. If not specified, the usage for the current user is returned. - **Available for**: User endpoint only (`/api/customer_usage/v1/usage/daily`) - Optional - `date` - `date={YYYY-MM-DD}` - Return usage for the specified date. - Optional - `from/to` - `from={YYYY-MM-DD}&to={YYYY-MM-DD}` - Return usage for the specified time range (in days). - Optional - `format` - `format={format}` - Specify the response format. Supported values are `xml` and `json`. The default is XML. - Optional #### Response Format The `allocation` field containing the list of entries with `name`, `number_of_queries`, and `used_bytes` values will be returned only in case there is usage. ##### For a Single Day **XML** **JSON** ``` json { "rl": { "date": "2020-02-01", "usage_report": [ { "product": "TCA-0101 File Reputation", "number_of_queries": 13487257 }, { "product": "TCAI-0011 Sample Submission Counter", "number_of_queries": 59, "used_bytes": 311816 } ] } } ``` ##### When Using From/To **XML** **JSON** ``` json { "rl": { "usage_reports": [ { "date": "2020-01-31", "usage_report": [ { "product": "TCA-0101 File Reputation", "number_of_queries": 53967760 } ] }, { "date": "2020-02-01", "usage_report": [ { "product": "TCA-0101 File Reputation", "number_of_queries": 13487257 } ] } ] } } ``` ### Monthly Usage #### User This query returns information about monthly service usage for the Spectra Intelligence account that sent the request. If the month is not specified, the service returns usage for the current month. The users can also specify a from-to time range (in months). ``` GET /api/customer_usage/v1/usage/monthly ``` #### Company This query returns information about combined monthly service usage for all users in the company. If the month is not specified, the service returns usage for the current month. The users can also specify a from-to time range (in months). ``` GET /api/customer_usage/v1/usage/company/monthly ``` #### Request Parameters - `user` - `user=u/company/user` - Return usage for the specified user. The user must belong to the same company as the authenticated user. If not specified, the usage for the current user is returned. - **Available for**: User endpoint only (`/api/customer_usage/v1/usage/monthly`) - Optional - `month` - `month={YYYY-MM}` - Return usage for the specified month. - Optional - `from/to` - `from={YYYY-MM}&to{YYYY-MM}` - Return usage for the specified time range (in months). - Optional - `format` - `format={format}` - Specify the response format. Supported values are `xml` and `json`. The default is XML. - Optional #### Response Format This query returns information about monthly service usage for the Spectra Intelligence account that sent the request. The `allocation` field containing the list of entries with `name`, `number_of_queries`, and `used_bytes` values will be returned only in case there is usage. ##### For a Single Month **XML** **JSON** ``` json { "rl": { "month": "2023-10", "usage_report": [ ... { "product": "TCAI-0011 Sample Submission Counter", "number_of_queries": 10, "used_bytes": 530000, "allocation": [ { "name": "Portal", "number_of_queries": 3, "used_bytes": 320000 }, { "name": "CLI-01", "number_of_queries": 7, "used_bytes": 210000 } ] } ... ] } } ``` ##### When Using From/To **XML** **JSON** ``` json { "rl": { "usage_reports": [ { "month": "2020-01", "usage_report": [ { "product": "TCA-0101 File Reputation", "number_of_queries": 1384316486 } ] }, { "month": "2020-02", "usage_report": [ { "product": "TCA-0101 File Reputation", "number_of_queries": 1332893230 } ] } ] } } ``` ### Date Range Usage #### User This query returns total usage for all product licenses with a fixed quota over a single date range. Use this endpoint for products with quotas that don't reset on a daily or monthly basis. The endpoint accepts no additional date specifying parameters, instead always returning total usage for the account in question. Some services may count the quota in used bytes instead of requests. In this case used_bytes value is included as a response field on a per-product basis. ``` GET /api/customer_usage/v1/usage/date_range ``` #### Company This query returns information about combined date range service usage for all users in the company. The endpoint accepts no additional date-specifying parameters, instead always returning total usage for the account in question. Some services may count the quota in used bytes instead of requests. In this case used_bytes value is included as a response field on a per-product basis. ``` GET /api/customer_usage/v1/usage/company/date_range ``` #### Request Parameters - `format` - `format={format}` - Specify the response format. Supported values are `xml` and `json`. The default is XML. - Optional #### Response Format The `allocation` field containing the list of entries with `name`, `number_of_queries`, and `used_bytes` values will be returned only in case there is usage. **XML** **JSON** ``` json { "rl": { "usage_reports": [ { "start_date": "2022-04-01", "end_date": "2023-03-31", "products": [ "TCAI-0011 Sample Submission Counter" ], "count": 566, "used_bytes": 4123890 } ] } } ``` ### Active YARA rulesets This query returns information about the number of active YARA rulesets for the Spectra Intelligence account that sent the request. Historical data is not shown. ``` GET /api/customer_usage/v1/usage/yara ``` - `format` - `format={format}` - Specify the response format. Supported values are `xml` and `json`. The default is XML. - Optional #### Response Format **XML** **JSON** ``` json { "rl": { "product": "TCA-0303 Yara Hunting", "number_of_active_rulesets": 23 } } ``` ### Quota Limits #### User This query returns current quota limits for APIs accessible to the authenticated user. 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. If product quota is limited by the number of bytes, limit field may be omitted, limit_size field is returned instead. If a product license has a fixed expiry date, start_date and end_date are included with the limit. If the product enforces a limit on the number of bytes for each submitted file, it is included as limit_size_per_file within the appropriate limit. ` A product license may include an additional free usage quota which resets alongside the standard quota (e.g. free quota for monthly licenses also resets monthly). This quota has a separate expiry period. The information about the quota is available via the `free_flex` field. Products related to Spectra Assure may also include an `entitlements` object associated with each limit, containing `max_package_size` - the largest processable package size in bytes, as well as various feature flags included with the product license. ``` GET /api/customer_usage/v1/limits ``` #### Company This query returns current quota limits for APIs available to all 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. ``` GET /api/customer_usage/v1/limits/company ``` #### Request Parameters - `user` - `user=u/company/user` - Return limits for the specified user. The user must belong to the same company as the authenticated user. If not specified, the limits for the current user are returned. - **Available for**: User endpoint only (`/api/customer_usage/v1/limits`) - Optional - `format` - `format={format}` - Specify the response format. Supported values are `xml` and `json`. The default is XML. - Optional #### Response Format The response format is identical for both endpoints, differing only in the number of listed services. In the following examples, `user1` will receive the same response for both the Current User and Company endpoints, while `user2` will not receive the TCA-0301 object when querying the Current User endpoint, as it is only accessible to `user1`. **XML** **JSON** ``` json { "rl": { "limits": [ { "limit": 500000, "limit_type": "daily", "limit_exceeded" : true, "products": ["TCA-0101 File Reputation", "TCA-0104 RLDATA", "TCA-0103 Historic Multi-AV Scan Records"], "users": ["user1","user2","user3"] }, { "limit": 1000, "limit_type": "monthly", "limit_exceeded" : false, "products": ["TCA-0301 RHA Functional Similarity"], "users": ["user1"], "start_date": "2022-09-15", "end_date": "2023-09-15" }, { "limit_size": { "value": 1000, "unit": "GB" }, "limit_type": "monthly", "limit_exceeded" : false, "products": ["TCAI-0011 Sample Submission Counter"], "users": ["user1"], "start_date": "2022-09-15", "end_date": "2023-09-15", "free_flex": { "limit_size": { "value": 1000, "unit": "GB" }, "start_date": "2022-09-15", "end_date": "2022-12-15" }, "limit_size_per_file": { "value": 1, "unit": "GB" }, "entitlements": { "hardening": true, "licenses": true, "malware": true, "max_package_size": 10737418240, "secrets": true, "tampering": true, "vulnerabilities": true } } ] } } ``` **Response format for API usage (XML)** **Response format for secure.software quotas (JSON)** The `allocation` field containing the list of entries with `name` and `size` values will be returned only in case there exists a total allocation limit. ``` json { "rl": { "limits": [ ... { "limit_size": { "value": 5, "unit": "GB" }, "limit_type": "monthly", "limit_exceeded" : false, "products": ["TCAI-0011 Sample Submission Counter"], "users": ["user1"], "start_date": "2023-09-15", "end_date": "2024-09-15", "allocation": [ { "name": "Portal", "size": { "value": 3000000000, "unit": "byte" } }, { "name": "CLI-01", "size": { "value": 2000000000, "unit": "byte" } } ] } ... ] } } ``` ### Email Alerting Configuration The Email Alerting Configuration service allows users to set up automated email notifications based on usage thresholds for specific products. By configuring alerts for selected product IDs, users can receive timely updates when their daily, monthly, or total usage exceeds defined percentage thresholds. This ensures better visibility and control over product consumption. Alerts are sent to a customizable list of email recipients, who may also opt out of future notifications via an unsubscribe link provided in each alert. #### List Existing Alerts This query returns a list of currently stored alert configurations. ``` GET /api/customer_usage/v1/alerts ``` #### Response Format **JSON** ``` json { "rl": { "alerts": [ { "emails": [ "user@example.com" ], "enabled": true, "product_id": "TCA-0101", "thresholds": [50, 100] }, ... ] } } ``` #### Create/Update Existing Alert This query creates a new alert configuration or updates an existing one for the same product ID. ``` POST /api/customer_usage/v1/alert ``` #### Request format **JSON** ``` json { "rl": { "alert": { "product_id": "TCA-0101", "emails": [ "user@example.com" ], "thresholds": [50, 100], "enabled": true } } } ``` An `alert` contains a `product_id`, a list of recipients, a boolean `enabled` flag, and a list of `thresholds`. Following `product_id` values are supported: ``` text TCA-0101, TCA-0103, TCA-0104, TCA-0105, TCA-0106, TCA-0201, TCA-0202, TCA-0203, TCA-0204, TCA-0205, TCA-0206, TCA-0207, TCA-0207-URL, TCA-0301, TCA-0302, TCA-0303, TCA-0319, TCA-0320, TCA-0321, TCA-0401, TCA-0402, TCA-0403, TCA-0404, TCA-0405, TCA-0406, TCA-0407, TCA-0501, TCA-0502, TCA-0503, TCAI-0001, TCAI-0011, TCAI-0106, TCAI-0320 ``` `thresholds` may contain any number of integer percentage values from 1 to 100 (inclusive). For each enabled alert, the service will email all listed recipients whenever the usage for the corresponding `product_id` crosses any configured threshold. Successful alert creation or update returns an empty `200 OK` response. Individual recipients may unsubscribe from future alerts by following the unsubscribe link included in each notification email. ## Examples **Monthly usage for the current user from January to March 2020, in JSON format** ``` /api/customer_usage/v1/usage/monthly?from=2020-01&to=2020-03&format=json ``` **Daily usage for the entire company from January 13th to February 14th** ``` /api/customer_usage/v1/usage/company/daily?from=2020-01-13&to=2020-02-14 ``` **Quota limits for the current user** ``` /api/customer_usage/v1/limits ``` --- ## Spectra Intelligence RL Cloud Sandbox API — Dynamic Analysis The RL Cloud Sandbox APIs enable dynamic analysis of files and URLs by detonating them in isolated sandbox environments to observe runtime behavior, network activity, and dropped files. ## Common Use Cases ### Detonate a file or URL in the sandbox 1. **[Dynamic analysis submission (TCA-0207)](tca-0207.md)** - Submit files or URLs for execution in Windows, macOS, Linux, or Android sandbox environments 2. **[Dynamic analysis report (TCA-0106)](tca-0106.md)** - Retrieve behavior reports including triggered processes, network traffic, screenshots, memory dumps, and dropped files ## All RL Cloud Sandbox APIs --- ## Dynamic Analysis Results API (TCA-0106) — Spectra Intelligence ## General information This service allows users to retrieve dynamic analysis reports for files and URLs executed in the ReversingLabs cloud sandbox. It returns two types of reports: **merged reports** and **specific reports**. ### Merged reports If you provide only the file or URL identifier, the response will contain a merged report with an overview of all dynamic analyses performed on the file or the URL. Most objects in the merged report include lists of analysis IDs, allowing the users to retrieve specific reports for more information about items of interest. ### Specific reports If the request includes the `/latest` query parameter, or an `analysis_id` matching an existing report, the report will contain information specific to that execution. All specific reports will contain download links for the network traffic PCAP file, screenshots, and memory strings dump file captured during that specific analysis. These files have a retention period of 1 year, while their download links are dynamically generated on report request, and are valid for 1 hour. Files and URLs can be submitted for dynamic analysis using the [TCA-0207 Dynamic Analysis](./tca-0207.md) service. ### Archive reports While working with archives, use the [archives](#archives) and [archive latest](#archives-latest) endpoints. Submitting only the SHA1 of the archive to these endpoints returns a list of SHA1 hashes of all files within the archives along with the **merged** dynamic analysis report for each file. If the `/latest` parameter is provided, the API returns a list of SHA1 hashes of all files within the archive, as well as the most recent **specific** dynamic analysis report for each file. Archives do not get an `analysis_id`, only the samples contained inside. They can be used to query the regular [file report endpoint](#files) for getting a specific report on an individual sample. A user's quota is deducted with the number of files or URLs for which the *merged* or *specific* dynamic analysis report is provided. ### Privacy Whether submitted files, email metadata, PCAP files, dropped files, screenshots, and memory string dumps will be shared with other ReversingLabs customers depends on the role configured for the Spectra Intelligence account used to upload files. If the account is configured to upload all files as shareable (not private), other ReversingLabs customers will be able to access analysis results, but also download the uploaded files, dropped files, PCAP files, screenshots, and memory string dumps generated during file execution. If the account is configured to upload all files as not shareable (private), other ReversingLabs customers will only be able to access analysis results, but not retrieve the actual contents of uploaded files, emails, dropped files, PCAP files, screenshots or memory string dumps. **This API is rate limited to 5 requests per second.** ## Files This query returns the dynamic analysis report for the requested sample hash. ### Request ``` GET /api/dynamic/analysis/report/v1/query/{hash_type}/{hash_value} ``` **Path parameters:** - `hash_type` - Accepts these values: `md5`, `sha1`, `sha256` - `hash_value` - The hash value of the sample for which to retrieve the report. If neither `/latest` nor `analysis_id` are used, the response contains a merged report of all analyses performed on the sample. Must be a valid hash defined by the `hash_type` parameter. - This report only contains `pcap`, `memory_strings`, `screenshots` and `dropped_files` if `artifacts_url=True`. - `/latest` - If added at the end of the endpoint path, the response contains only the newest dynamic analysis report for the requested file hash. This parameter is incompatible and mutually exclusive with `analysis_id`. - This report contains download links for the network traffic PCAP file, screenshots, and memory strings dump file captured during file execution. - `analysis_id` - If added at the end of the request, the response contains only the dynamic analysis report matching the provided `analysis_id`. This parameter is incompatible and mutually exclusive with `/latest`. - This report contains download links for the PCAP network traffic file, screenshots, and memory strings dump file captured during file execution. **Query parameters:** - `format` - Specifies the response format. Supported values are `json` (default), `xml` - `artifacts_url` - Add `artifacts_url=True` after the path parameters to receive a response containing artifact links (`pcap`, `memory_strings`, `screenshots`, `dropped_files`) for specific reports in the history part of the merged report. Passing this parameter will slow the response down. ### Response ```json { "rl": { "report": {}, "requested_hash": "string", "private_data_filtered": true } } ``` - `report` - The object containing the dynamic analysis report (merged or report for a specific dynamic analysis run) - `requested_hash` - The SHA1 hash of the analyzed file - `private_data_filtered` - Sample privacy from the perspective of the account requesting the report. If `private_data_filtered` is false, the sample either belongs to the requesting account or is publicly available, and the report includes all relevant information. If `true`, the sample was privately uploaded by a different account, and the report will exclude any information described in the [Privacy](#privacy) chapter. ----------------------------------------------------------------------- `rl.report` ```json { "network": {}, "mitre_attack": {}, "process_tree": [], "sha1": "string", "analysis_id": "string", "classification": "string", "dropped_files": [], "snort_alerts": [], "analysis_duration": 0, "platform": "string", "configuration": "string", "behavioral": [], "memory_strings": "string", "sha256": "string", "pcap": "string", "md5": "string", "analysis_time": "string", "optional_parameters": "string", "yara": {} "interactive": "string", "timeout": 200 } ``` - `sha1`, `sha256`, `md5` - Hashes of the analyzed sample - `classification` - The sandbox classification of the sample. Possible values are MALICIOUS, SUSPICIOUS, CLEAN, NO_THREATS_FOUND. In the merged report, classification is always the worst result out of all performed analyses. - `risk_score` - Value representing the trustworthiness or malicious severity of a sample. Risk score is expressed as a number from 0 to 10, with 0 indicating whitelisted samples from a reputable origin, and 10 indicating the most dangerous threats. Goodware samples with risk scores of 2 and 3 are labeled "Likely benign / Public origin", and those with scores of 4 and 5 are labeled as "Not a known threat / Unverified origin". Risk scores from 6 to 10 are reserved for suspicious/malicious samples, and express their severity. The score from the specific report will show the risk score for that specific analysis, whereas the score from analysis with the highest risk score will be propagated to the top level of the merged report. - `threat_names` - Name of the threats. Shows a list of unique threat names within the analyzed sample. - `first_analysis` - The date and time when this sample was first analyzed - `last_analysis` - The date and time when this sample was last analyzed - `analysis_duration` - The duration of the analysis (in seconds) - `platforms` - A list of platforms used to analyze the sample. - `browser` - Browser-specific dynamic analysis detonation. This object is present only in specific reports. - `configuration` - A short description of the platform configuration specifics (for example, "Win10 x64, Office 2016, Java 8 Update 191"). This object is present only in specific reports. - `history_analysis` - An object containing an overview of all available reports. This object is present only in merged reports. - `sample_name` - The name of the sample that was used during analysis. In a merged report, each individual analysis has its own sample_name attribute. - `sample_path` - The full file path of the sample. In a merged report, each individual analysis has its own sample_path attribute. - `optional_parameters` - An object containing a list of optional parameters used during analysis. Possible values: `internet_simulation`, `sample_name`, `geolocation`, `locale`. - If `internet_simulation` is true, dynamic analysis was performed without connecting to the internet and a simulated network was used instead. If this value is false, the report is the same as if the parameter is omitted from the response. HTTPS traffic information is not monitored during analysis when `internet_simulation` is set to true. - `sample_name` is a custom file name and/or extension provided on submission. Custom extensions impact which application was used to open and run the file. - `geolocation` is a 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` setting reflects 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`. - `mitre_attack` - A list of identified MITRE ATT&CK tactics and techniques. - `network` - A list of network resources the analyzed sample used or contacted during execution - `behavioral` - A list of objects containing behavioral information about the executed sample. Every object relates one process spawned during sample execution to specific actions it performed. - `android_behavioral` - A list of objects containing behavioral and permission information about the executed APK sample. Every object relates one process spawned during sample execution to specific actions it performed. - `malware_configurations` - A list of embedded malware configuration data collected during sample execution. - `bot_configurations` - Contains bot-related information. - `snort_alerts` - Matched Snort alerts in PCAP network captures. - `suricata_alerts` - Matched Suricata alerts in PCAP network captures. - `sigma_detections` - Sysmon events, Windows event logs, and operating system process creation events captured during the detonation of malware in a sandbox. - `signatures` - Abstracted behaviors, attributes, and content identified during analysis. Each signature has a signature ID, description and a risk score. Signatures commonly provide the following types of information: - Behaviors and capabilities observed during execution of the sample. - Attributes extracted via static analysis of the sample or artifacts generated during execution. - Data-enrichment results, such as file reputation detections for the sample and any dropped files, Snort signature detections from network traffic, and YARA rule matches in the sample or process memory - `static.email` - For email files, this object includes extracted metadata. In merged reports, the metadata is linked to the analyses from which it was retrieved, identified by their analysis IDs. - `static.apk` - For APK files, this object includes extracted metadata. In merged reports, the metadata is linked to the analyses from which it was retrieved, identified by their analysis IDs. - `related_analysis` - If the analysis spawned additional analysis processes, this object contains a list of their analysis IDs, hashes, their relationship with the parent report, and any other applicable information. - `dropped_files` - An object containing a list of all files dropped during execution of the analyzed sample. ReversingLabs uses an internal algorithm to filter and store dropped files in order to provide customers with the most interesting and valuable files. - `dropped_files_url` - Contains a link to download all files dropped during the file execution. This link is generated when the report is requested, and expires in 1 hour. This object is present as `dropped_files_url` in specific reports, and as `dropped_files` in merged reports when `artifacts_url=True`. - `pcap` - Contains a link to download the PCAP file with all the network traffic generated during sample execution. PCAP files have a retention period of 1 year. This link is generated when the report is requested, and expires in 1 hour. This object is present in specific reports, and in merged reports when `artifacts_url=True`. - `memory_strings` - Contains a link to download a dump of memory strings stored in the memory and captured during file execution. Memory strings have a retention period of 1 year. This link is generated when the report is requested, and expires in 1 hour. This object is present in specific reports, and in merged reports when `artifacts_url=True`. - `screenshots` - Contains a link to screenshots collected during the analysis. Screenshots have a retention period of 1 year. This link is generated when the report is requested, and expires in 1 hour. This object is present in specific reports, and in merged reports when `artifacts_url=True`. - `process_tree` - An entire process tree generated during sample execution, sorted in order. This object is present only in specific reports. - `warnings` - Descriptive warning messages regarding the status of the analysis. - `errors` - Descriptive error messages regarding the status of the analysis. - `yara` - Contains details regarding matched YARA rules during analysis. - `interactive` - Whether the report comes from an interactive session with Spectra Analyze. Can be either "true" or "false" (string, not boolean). - `timeout` - Maximum running time allowed for the sample. ----------------------------------------------------------------------- `rl.report.mitre_attack.matrix_list` ```json { "matrix_list": [ { "name": "string", "tactics": {} } ] } ``` - `name` - The name of the matrix used during analysis - `tactics` - A list of tactics detected during sample execution. Each entry has an `id`, `name`, `description` and a `technique_list` containing a list of specific techniques that were detected. Technique lists in merged reports will also contain a list of `analysis_ids` for every technique. ----------------------------------------------------------------------- `rl.report.network` - `url` - A list of URLs extracted during sample execution. Every entry contains: - the destination URL - URL `source`: - `memory`: the URL was extracted from memory. - `malware_config`: the URL was extracted from a malware configuration. - `file`: the URL was extracted from a PDF file. - `network`: the URL was extracted from network traffic. - URL `classification`. - A list of `categories` for this URL. - `http` - A list of resources this sample contacted using HTTP. Every entry contains the destination IP address and the request method. - `udp` - A list of resources this sample contacted using UDP. Every entry contains the destination IP address, the destination port, and the process ID. - `tcp` - A list of resources this sample contacted using TCP. Every entry contains the destination IP address, the destination port, and the process ID. - `dns` - A list of DNS requests and resolutions the analyzed sample performed during execution. The address field contains the DNS server response, if available. ----------------------------------------------------------------------- `rl.report.behavioral` - `process` - An object containing information about the process that spawned during dynamic analysis. Contains the process ID, process name, the full execution path with parameters, and parent process ID. - `mutex_actions` - A list of all mutex actions performed by the process during sample execution. Entries contain the file name, file path, the type of action that was performed, and if the action was successful or not. - `file_actions` - A list of all files that were accessed or modified by the process. Entries contain the file name, file path, the type of action that was performed, and if the action was successful or not. - `registry_actions` - A list of all registry actions performed by the process. Entries contain the registry key name, the type of action that was performed, and if the action was successful or not. - `process_actions` - A list of all actions performed by spawned processes. Entries contain the process name, the type of action that was performed, and if the action was successful or not. - `modules_loaded` - A list of all modules loaded by the process. ----------------------------------------------------------------------- `rl.report.android_behavioral` - `dynamic_services` - List of dynamically started services. Every entry is a stringified Intent, e.g.: - `"Intent { cmp=cmf0.c3b5bm90zq.patch/.C11 }"` - `dynamic_receivers` - List of dynamically registered broadcast receivers. Every entry contains: - `name`: runtime-registered receiver class name. - `intents`: list of intent actions the receiver handles, e.g.: - `android.intent.action.BATTERY_CHANGED` - `permissions_executed` - List of permissions actually executed during dynamic analysis. Every entry contains: - `name`: permission name, e.g. `ACCESS_NETWORK_STATE`. - `executed`: boolean flag indicating whether the permission was used at runtime. ----------------------------------------------------------------------- `rl.report.malware_configurations` - `threat_names` - Name of the threats. Shows a list of unique threat names within the analyzed sample. - `configuration` - Embedded malware configuration data extracted during sample execution - `malware_config_ip` - C2 IP addresses the malware contacted or attempted to contact during sample execution - `malware_config_url` - C2 URLs the malware contacted or attempted to contact during sample execution - `analysis_ids` - An object containing a list of analysis IDs of specific analyses during which this configuration was extracted. **This object is present only in merged reports.** ----------------------------------------------------------------------- `rl.report.signatures` - `sig_id` - Signature ID - `description` - Signature description in human-readable format. - `risk_factor` - Risk factor assigned to this signature. Can have one of the following values: `10` - Malicious behavior. Attributable to specific malware family/actor, `9` - Highly malicious behavior or content, `8` - Malicious behavior, `7` - Suspicious behavior, `6` - Moderately suspicious behavior or content, `5` to `1` - Normal behavior or content, `0` - Behavior indicative of goodware ----------------------------------------------------------------------- `rl.report.dropped_files` - `dropped_files_url` - Contains a link to download all files dropped during the file execution. This link is generated when the report is requested, and expires in 1 hour. - `sha1` - The SHA1 hash of the dropped file - `sha256` - The SHA256 hash of the dropped file - `md5` - The MD5 hash of the dropped file - `classification` - The classification of the dropped file. Possible values are `MALICIOUS`, `SUSPICIOUS`, `CLEAN`, `NO_THREATS_FOUND`. - `file_name` - The file name of the dropped file - `sample_type` - The file type of the dropped file - `sample_size` - The file size of the dropped file (in bytes) - `analysis_ids` - An object containing a list of analysis IDs and classifications for every occurrence of this dropped file during parent sample execution. **This object is present only in merged reports.** ----------------------------------------------------------------------- `rl.report.static.email` Contains information extracted from emails. This will be omitted from the report if the sample belongs to a different Spectra Intelligence account, and was uploaded as private (not shareable). - `subject` - The subject line of the email. - `from_address` - The sender's name and email address. - `to_address` - The recipient's email address. - `cc` - CC (carbon copy) email addresses. - `bcc` - BCC (blind carbon copy) email addresses. - `communications` - A list containing extracted strings from the email body or related communications. - `date` - The date and time the email was sent. - `analysis_id`: In merged reports, this field includes a list of related analysis IDs, identifying the analyses where the email information was extracted. - `headers` - `key`: Header key (e.g., `Return-Path`). - `value`: Header value (e.g., ``). - `analysis_id`: Headers in merged reports also contain a list of related `analysis_ids` for every header. - `attachment`: A list of email attachments. ----------------------------------------------------------------------- `rl.report.static.apk` - `label` Human-readable application label from the APK. - `minimum_sdk` Minimum Android SDK version required to install the app. - `target_sdk` Target Android SDK version declared in the manifest. - `version_code` Internal version code of the APK. - `version_name` Version name of the APK, typically user-visible. - `package_name` Unique application package identifier. - `permissions` - List of permissions declared in the manifest. - `activities` - List of declared activity component names. Every entry contains: - `name`: fully-qualified activity class name. - `services` - List of declared service component names and their intent filters. Every entry contains: - `name`: fully-qualified service class name. - `intents`: list of intent actions the service listens for. - `receivers` - List of declared broadcast receiver component names and intent filters. Every entry contains: - `name`: fully-qualified receiver class name. - `intents`: list of intent actions the receiver handles. - `icon` - Launcher icon resource data. Contains: - `name`: file path of the icon resource within the APK. - `data`: Base64-encoded PNG image data for the icon. - `certificate` - Signing certificate metadata used to sign the APK. Contains: - `issuer`: distinguished name of the certificate issuer. - `subject`: distinguished name of the certificate subject. - `md5`: MD5 fingerprint of the signing certificate. - `sha1`: SHA1 fingerprint of the signing certificate. - `sha256`: SHA256 fingerprint of the signing certificate. ----------------------------------------------------------------------- `rl.report.related_analysis` In **specific reports**, this object lists related analyses for the given entry. **Merged reports** list all associated files, including duplicates if a file was part of multiple analyses. - `relationship_type` - Indicates the type of relationship between the analysis and its related analyses. Possible values are: - `email_source` - Indicates that the related analysis is for an email from which this attachment or URL was extracted. - `email_attachment` - Indicates that the related analysis is for an attachment to the email. - `email_extracted_url` - Indicates that the related analysis is for a URL extracted from the email. - `md5` - The MD5 hash of the file (applies if the related analysis is for an attachment or source email). - `sha1` - The SHA1 hash of the file (applies if the related analysis is for an attachment or source email). - `sha256` - The SHA256 hash of the file (applies if the related analysis is for an attachment or source email). - `url` - The extracted URL (applies if the related analysis is for an extracted URL). - `related_analysis_id` - The ID of the report associated to the related extracted file/URL. - `analysis_id` - The ID of the analysis during which the related file/URL was encountered. ----------------------------------------------------------------------- The following objects are present only in merged reports: `rl.report.history_analysis` - `analysis_id` - The analysis ID of the report - `classification` - The classification of the sample. Possible values are `MALICIOUS`, `SUSPICIOUS`, `CLEAN`, `NO_THREATS_FOUND`. - `risk_score` - Value representing the trustworthiness or malicious severity of a sample. - `platform` - The platform used to analyze the sample - `browser` - Browser-specific dynamic analysis detonation. **This object is present only in merged reports.** - `configuration` - A short description of the platform configuration specifics (for example, "Win10 x64, Office 2016, Java 8 Update 191") - `analysis_time` - The date and time of the analysis - `screenshots` - Contains a link to screenshots collected during the analysis. Screenshots have a retention period of 1 year. This link is generated when the report is requested, and expires in 1 hour. - `pcap` - Contains a link to download the PCAP file with all the network traffic generated during sample execution. This link is generated when the report is requested, and expires in 1 hour. The PCAP file has a retention period of 1 year. - `dropped_files` - An object containing a list of all files dropped during execution of the analyzed sample. ReversingLabs uses an internal algorithm to filter and store dropped files in order to provide customers with the most interesting and valuable files. Contains a link to download all files dropped during the file execution. This link is generated when the report is requested, and expires in 1 hour. - `memory_strings` - Contains a link to download the memory strings captured during the sample execution. This link is generated when the report is requested, and expires in 1 hour. Memory strings have a retention period of 1 year. - `optional_parameters` - An object containing a list of optional parameters used during analysis. Possible values: `internet_simulation`, `sample_name`, `geolocation`, `locale`. - If `internet_simulation` is true, dynamic analysis was performed without connecting to the internet and a simulated network was used instead. If this value is false, the report is the same as if the parameter is omitted from the response. HTTPS traffic information is not monitored during analysis when `internet_simulation` is set to true. - The `sample_name` is a custom file name and/or extension provided on submission. Custom extensions impact which application was used to open and run the file. - The `geolocation` is a 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`. - The `locale` setting reflects 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`. ----------------------------------------------------------------------- The following objects are present only in specific reports. `rl.report.process_tree` - `process_id` - The ID assigned to the process - `parent_process_id` - The ID of the parent process - `process_name` - The process name - `process_parameters` - Specific parameters used to execute the process ----------------------------------------------------------------------- The following objects are present only in specific reports. They will be omitted if the sample belongs to a different Spectra Intelligence account, and was uploaded as private (not shareable). `rl.report.memory_strings` - `memory_strings` - Contains a link to download the memory strings captured during the sample execution. This link is generated when the report is requested, and expires in 1 hour. Memory strings have a retention period of 1 year. ----------------------------------------------------------------------- `rl.report.pcap` - `pcap` - Contains a link to download the PCAP file with all the network traffic generated during sample execution. This link is generated when the report is requested, and expires in 1 hour. The PCAP file has a retention period of 1 year. ----------------------------------------------------------------------- `rl.report.screenshots` - `screenshots` - Contains an S3 link to screenshots collected during the analysis. This link is generated when the report is requested, and expires in 1 hour. Screenshots have a retention period of 1 year. ----------------------------------------------------------------------- `rl.report.yara` - `entries` - Contains a list of matched YARA rules and details about where they matched. - `source_type` - The type of file or content where the YARA rule matched. Possible values include: - `sample`: The original sample file. - `dropped_file`: Files created or dropped during the analysis. - `memory_dump`: Process memory captured during the analysis. - `unpacked_pe`: Unpacked PE (Portable Executable) files extracted during analysis. - `html`: HTML files involved in the analysis. - `pcap`: Network traffic captured in a PCAP file. - `other`: Any other content types. - `source_name` - The name of the source where the YARA rule matched (optional). - `rule` - Contains details about each YARA rule that matched against the source. - `description`: A textual explanation of the YARA rule's purpose. - `matched_data`: A list of matched strings within the YARA rule. - `matched_string`: The base64-encoded string that triggered the YARA rule match. - `matched_offset`: The decimal-encoded offset where the string was found in the source file or memory dump. ----------------------------------------------------------------------- ### Examples #### Merged report ##### Request ``` GET /api/dynamic/analysis/report/v1/query/sha1/cac61424fb5414d589687bfd35452a351604ef11 ``` ##### Response
Response ``` json { "rl":{ "report":{ "mitre_attack":{ "matrix_list":[ { "tactics":{ "tactic_list":[ { "techniques":{ "technique_list":[ { "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ], "id":"T1091", "name":"Replication Through Removable Media" }, "..." ] }, "id":"8", "name":"Lateral Movement" }, "..." ] }, "name":"Enterprise" } ] }, "sha1":"cac61424fb5414d589687bfd35452a351604ef11", "last_analysis":"2021-02-09T18:54:58", "network":{ "udp":[ { "destination_port":53, "destination_ip":"8.8.4.4", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] }, "..." ], "dns":[ { "type":"A (IP address)", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ], "value":"services.homedns.org", "address":"xxx.xxx.xxx.xxx" }, "..." ] }, "classification":"MALICIOUS", "history_analysis":[ { "analysis_id":"bc093926-e53f-49d9-82d7-1e5481cb22eb", "classification":"MALICIOUS", "analysis_duration":217, "platform":"windows7", "configuration":"MS Office 2007;Java 7;Adobe reader 8;Firefox 37;Google Chrome 51;Internet Explorer 8", "sample_name": "Sample", "sample_path": "C:\Users\user\Desktop", "analysis_time":"2021-02-07T23:49:38", }, "..." ], "sample_name": "Sample", "sample_path": "C:\Users\user\Desktop", "first_analysis":"2021-02-07T23:49:38", "dropped_files":[ { "sha1":"BCF7B98F948D2CDDF2ABB74C4673604DDE801E1A", "classification":"NO_THREATS_FOUND", "file_name":"Logs", "sample_type":"ASCII text, with CRLF line terminators", "sample_size":33, "analysis_ids":[ { "analysis_id":"bc093926-e53f-49d9-82d7-1e5481cb22eb", "classification":"NO_THREATS_FOUND" } ], "sha256":"51BE93BCB053F7412C5FFBCA5C947EC0DDA4A52D6D9A12F18BCE35C4E1F216A0", "file_path":"C:\\Users\\user\\AppData\\Roaming", "md5":"F07F3A1093767FF0B58C5FB7FC7617C7" }, "..." ], "optional_parameters": "internet_simulation=true, geolocation=us, locale=en-US", "snort_alerts":[ { "message":"ICMP Destination Unreachable Port Unreachable", "classification_type":"Misc activity", "destination_ip":"8.8.4.4", "rule":402, "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] }, "..." ], "platforms":[ "windows7", "windows10" ], "behavioral":[ { "process":{ "name":"cmd.exe", "parameters":"cmd /c REG ADD HKLM\\System\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\StandardProfile /v 'DoNotAllowExceptions' /t REG_DWORD /d '0' /f", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] }, "mutex_actions":[ { "status":"success or wait", "name":"unknown", "action_type":"mutex_created", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] } ], "process_actions":[ { "status":"success or wait", "path":"C:\\Windows\\SysWOW64\\cmd.exe", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ], "action_type":"process_terminated" }, "..." ], "file_actions":[ { "status":"success or wait", "file_name":"reg.exe", "file_path":"C:\\Windows\\SysWOW64", "action_type":"file_opened", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] }, "..." ], "modules_loaded":[ { "module_name":"\\KnownDlls32\\MPR.dll", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ] }, "..." ], "registry_actions":[ { "status":"success or wait", "key_name":"HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\SharedAccess\\Parameters\\FirewallPolicy\\StandardProfile", "analysis_ids":[ "bc093926-e53f-49d9-82d7-1e5481cb22eb" ], "action_type":"key_opened" }, "..." ] }, "..." ], "yara": { "entries": [ { "source_type": "sample", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 45520 } ] } ] }, { "source_type": "dropped_file", "source_name": "C:\\ProgramData\\d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADcMQEApbYBZgAyAgAxg8GcTThakA==", "matched_offset": 45520 }, { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 123848 } ] } ] }, { "source_type": "memory_dump", "source_name": "d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 3735928559 } ] } ] } ] }, "sha256":"cc6102694e9d8f8efbd63c687972291369079c0bbd62b5d71cc106e9f64946d6", "md5":"4f2af32661dc73320acbe5acea29cfba" }, "requested_hash":"cac61424fb5414d589687bfd35452a351604ef11" } } ```
#### Specific Report There are no formatting differences between reports retrieved using the `analysis_id` and `/latest` endpoint parameters. The only differences can occur in cases when users request information on a private sample belonging to another Spectra Intelligence account. If the sample is public, other ReversingLabs customers will be able to access analysis results, but also download the uploaded files, dropped files, PCAP files, screenshots, and memory string dumps generated during file execution. If the sample is private, other ReversingLabs customers will only be able to access analysis results, but not retrieve the actual contents of uploaded files, dropped files, PCAP files, screenshots or memory string dumps. ##### Request ``` GET /api/dynamic/analysis/report/v1/query/sha1/cac61424fb5414d589687bfd35452a351604ef11/dd39d858-636f-4c76-a0d1-249ef21ff780 ``` ##### Response
Response ``` json { "rl":{ "report":{ "mitre_attack":{ "matrix_list":[ { "tactics":{ "tactic_list":[ { "id":"8", "name":"Lateral Movement", "techniques":{ "technique_list":[ { "id":"T1080", "name":"Taint Shared Content" }, "..." ] } }, "..." ] }, "name":"Enterprise" } ] }, "process_tree":[ { "process_id":2096, "name":"rl_file.exe", "parameters":"'C:\\Users\\user\\Desktop\\rl_file.exe' ", "parent_process_id":1712 } ], "sha1":"cac61424fb5414d589687bfd35452a351604ef11", "analysis_id":"dd39d858-636f-4c76-a0d1-249ef21ff780", "classification":"MALICIOUS", "dropped_files":[ { "sha1":"E0A8096041DFA6D6E5F9D41E870C892E59438964", "classification":"NO_THREATS_FOUND", "file_name":"81608.bpc", "sample_type":"PE32 executable (GUI) Intel 80386, for MS Windows", "sample_size":5077073, "sha256":"6BECD956E49FA786BC2845909BC2C7BB6B8E633DE1633151014B44AF925966C6", "file_path":"C:\\ProgramData\\Microsoft\\OFFICE\\DATA", "md5":"60BCE3FACE583205A3247205052FD7A1" }, "..." ], "analysis_duration":188, "platform":"windows7", "configuration":"MS Office 2007;Java 7;Adobe reader 8;Firefox 37;Google Chrome 51;Internet Explorer 8", "sample_name": "Sample", "sample_path": "C:\Users\user\Desktop", "behavioral":[ { "process_actions":[ { "status":"success or wait", "path":"C:\\Users\\user\\Desktop\\rl_file.exe", "action_type":"process_queried" } ], "registry_actions":[ { "status":"object name not found", "key_name":"HKEY_LOCAL_MACHINE\\SYSTEM\\ControlSet001\\Control\\Nls\\Language", "action_type":"key_value_queried" }, "..." ], "file_actions":[ { "status":"success or wait", "file_name":"KsecDD", "file_path":"\\Device", "action_type":"file_opened" }, "..." ], "process":{ "name":"rl_file.exe", "parameters":"'C:\\Users\\user\\Desktop\\rl_file.exe' " }, "mutex_actions":[ { "status":"success or wait", "name":"unknown", "action_type":"mutex_created" }, "..." ], "modules_loaded":[ { "module_name":"C:\\Windows\\SysWOW64\\sechost.dll" }, "..." ] } ], "yara": { "entries": [ { "source_type": "sample", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 45520 } ] } ] }, { "source_type": "dropped_file", "source_name": "C:\\ProgramData\\d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADcMQEApbYBZgAyAgAxg8GcTThakA==", "matched_offset": 45520 }, { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 123848 } ] } ] }, { "source_type": "memory_dump", "source_name": "d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 3735928559 } ] } ] } ] }, "sha256":"cc6102694e9d8f8efbd63c687972291369079c0bbd62b5d71cc106e9f64946d6", "md5":"4f2af32661dc73320acbe5acea29cfba", "analysis_time":"2021-02-08T12:51:37", "optional_parameters": "internet_simulation=true, geolocation=us, locale=en-US" }, "requested_id":"dd39d858-636f-4c76-a0d1-249ef21ff780", "requested_hash":"cac61424fb5414d589687bfd35452a351604ef11" } } ```
#### Latest report ##### Request ``` GET /api/dynamic/analysis/report/v1/query/sha1/cac61424fb5414d589687bfd35452a351604ef11/latest ```
Response ``` json { "rl":{ "report":{ "mitre_attack":{ "matrix_list":[ { "tactics":{ "tactic_list":[ { "id":"8", "name":"Lateral Movement", "techniques":{ "technique_list":[ ] } }, "..." ] }, "name":"Enterprise" } ] }, "yara": { "entries": [ { "source_type": "sample", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 45520 } ] } ] }, { "source_type": "dropped_file", "source_name": "C:\\ProgramData\\d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADcMQEApbYBZgAyAgAxg8GcTThakA==", "matched_offset": 45520 }, { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 123848 } ] } ] }, { "source_type": "memory_dump", "source_name": "d0db02bh22.exe", "rule": [ { "description": "Detects executables packed with aPLib.", "matched_data": [ { "matched_string": "QVAzMhgAAADP3QAAaFvqdQDMAQDrxK5YTThakA==", "matched_offset": 3735928559 } ] } ] } ] }, "sha1":"cac61424fb5414d589687bfd35452a351604ef11", "analysis_id":"64708859-7739-4c1a-9e64-2de5741882db", "classification":"NO_THREATS_FOUND", "analysis_duration":210, "platform":"windows7", "configuration":"MS Office 2007;Java 7;Adobe reader 8;Firefox 37;Google Chrome 51;Internet Explorer 8", "sample_name": "Sample", "sample_path": "C:\Users\user\Desktop", "memory_strings":"https://...", "sha256":"cc6102694e9d8f8efbd63c687972291369079c0bbd62b5d71cc106e9f64946d6", "pcap":"https://...", "md5":"4f2af32661dc73320acbe5acea29cfba", "analysis_time":"2021-02-09T18:54:58", "optional_parameters": "internet_simulation=true, geolocation=us, locale=en-US" }, "requested_hash":"cac61424fb5414d589687bfd35452a351604ef11" } } ```
## URLs This query returns dynamic analysis reports for the requested URL. The requested URL is identified by its Base64 encoding or SHA1 hash. Use the Base64/SHA1 identifier that you get in the response of the [TCA-0207 Dynamic Analysis](./tca-0207.md) service. If you calculate this value **locally**, for example using `sha1sum`, there is a chance that you won't get results for that URL because the Dynamic Analysis service first performs a normalization process on the URL, and only then calculates the Base64 encoding / SHA1 hash. ### Request ``` GET /api/dynamic/analysis/report/v1/query/url/sha1/{sha1_value}/{analysis_id} ``` ``` GET /api/dynamic/analysis/report/v1/query/url/base64/{base64_value}/{analysis_id} ``` **Path parameters**: - `sha1_value` - A valid SHA1 value defined by the SHA1 parameter. - Required - `base64_value` - A valid Base64 value defined by the Base64 parameter. - Required - `analysis_id` - If added at the end of the request, the response will contain only the dynamic analysis report matching the provided analysis_id. It can be supplied only if the `latest` parameter is not already supplied. If neither are provided, the response returns a merged report. - Optional - `latest` - Required if the user wants to retrieve the latest dynamic analysis report for the requested URL. It can be supplied only if the `analysis_id` parameter is not already supplied. If neither are provided, the response returns a merged report. - Optional ## Archives This query returns dynamic analysis reports for the requested archive sample hash. ### Request By submitting the SHA1 of the archive, the query returns the merged dynamic analysis report for each file within the archive. This endpoint accepts only SHA1 hashes. ``` GET /api/dynamic/analysis/report/v1/archive/query/sha1/{hash_value} ``` **Path parameters:** - `hash_value` - The hash value of the sample for which to retrieve the report. If `/latest` is not used, the response will contain a merged report of all analyses performed on the sample. ### Response ``` json { "rl": { "requested_hash": "string", "files": [ { "sha1": "string", "merged_report": {} }, { "sha1": "string", "merged_report": {} } ] } } ``` ### Examples ``` GET /api/dynamic/analysis/report/v1/archive/query/sha1/e662bfd39cf389b0bad5262e6007c09824261ee4 ```
Response ``` json { "rl": { "requested_hash": "e662bfd39cf389b0bad5262e6007c09824261ee4", "files": [ { "sha1": "zzzf8d4dd290435a978e70adcf7876c0", "merged_report": {} }, { "sha1": "vvvf8d4dd290435a978e70adcf7876c0", "merged_report": {} } ] } } ```
## Archives Latest By submitting SHA1 of the archive with the `/latest` parameter, the query returns the most recent specific dynamic analysis report for each file within the archive. ### Request ``` GET /api/dynamic/analysis/report/v1/archive/query/{hash_type}/{hash_value}/latest ``` **Path parameters:** - `hash_value` - The hash value of the sample for which to retrieve the report. If `/latest` is not used, the response will contain a merged report of all analyses performed on the sample. ### Response ``` json { "rl": { "requested_hash": "string", "files": [ { "sha1": "string", "report": {} }, { "sha1": "string", "report": {} } ] } } ``` ### Examples ``` GET /api/dynamic/analysis/report/v1/archive/query/sha1/e662bfd39cf389b0bad5262e6007c09824261ee4/latest ```
Response ``` json { "rl": { "requested_hash": "e662bfd39cf389b0bad5262e6007c09824261ee4", "files": [ { "sha1": "zzzf8d4dd290435a978e70adcf7876c0", "report": {} }, { "sha1": "vvvf8d4dd290435a978e70adcf7876c0", "report": {} } ] } } ```
## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | | DESCRIPTION | | :--- | :-------------- | :---------- | | 404 | Preprocessing | If the sample is still being validated for dynamic analysis, the response will contain the `pre_processing` status. | | Queued | The sample is queued for analysis, indicated by the `queued` status in the response. | | | Preparing Sample | The `preparing_sample` status indicates that the sample is currently being submitted to the sandbox. | | | Analyzing | The `analyzing` status indicates that the sample is currently being analyzed. | | | Postprocessing | The `post_processing` status indicates that the report is currently being generated. | | | Finished | The `finished` status indicates that the analysis is complete and the report is ready. | | | Error | The `error` message response indicates that the sample failed to analyze. | --- ## Dynamic Analysis Submission API (tca-0207) — Spectra Intelligence The Dynamic Analysis service allows users to detonate a file or URL in the ReversingLabs Cloud Sandbox. The following sandbox profiles are available: 1. Win11 22H2 (MS Office 2016, Adobe Reader 21, Java 8, Google Chrome 113, Firefox 96, Python 3.9) 2. 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, Python 3.9) 3. 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) 4. macOS 11 (MacOS Big Sur; Safari 14.1.2; Acrobat Reader 22.003.20258) 5. Linux (Ubuntu 20.04 Server; Kernel 5.4.0-72-generic, LibreOffice 7.5.3.2, OpenJDK 11.0.18, Adobe Reader 9.5.5, Firefox 112.0.2, Python 3.8, Ruby 2.7) 6. Android 12 The report about the performed analysis and behavior can be retrieved using the [TCA-0106 File Dynamic Analysis Report](../DynamicAnalysis/tca-0106.md) service. The time to report takes around 15 minutes. ## File submissions To detonate a file, it must first exist in the Spectra Intelligence cloud. If it doesn't exist, it must be uploaded using the [TCA-0202/0203 File Upload](../Automation/tca-0202-0203.md) API. After the sample and its metadata are uploaded, the hash of the sample can be submitted to the Dynamic Analysis API. For consistent results during dynamic analysis, you must submit the filename of the upload in the metadata API call. Samples must not exceed the maximum size limit of 400 MB. For more information on uploading files to the cloud, see the [TCA-0202/0203 File Upload](../Automation/tca-0202-0203.md) API documentation. Submitted samples will be executed and analyzed by ReversingLabs Cloud Sandbox and a report will be generated. Supported file types for Windows environments (non-exhaustive): - Windows executables: EXE, DLL, BAT, CHM, WSF, JS, JSE, VBS, VBE, PS1, CMD, PIF, LNK, SCR, CPL, HWP, MSI - Microsoft Office: DOC(X)(M), XLS(X)(M), PPT(X)(M), MSG, EML - PDF documents - Java: JAR - Misc: CRX (Chrome extension) Supported file types for macOS (non-exhaustive): - DMG - APP - MACH-O - PKG Supported file types for Linux (non-exhaustive): - ELF (including .so) - Microsoft Office: DOC(X)(M), XLS(X)(M), PPT(X)(M), MSG, EML - Bash scripts - PY - PHP - DEB - PDF documents Supported file types for OS-independent environments (non-exhaustive): - Markup: HTM, HTML Windows, macOS and Linux support submissions as [archives](#dynamic-analysis---archive-detonation). Samples can be simultaneously submitted for analysis to multiple sandbox environments. Each analysis will get a unique `analysis_id`. ### Email Submissions When a submitted file hash corresponds to an email, the dynamic analysis service initiates additional workflows that may impact the classification and increase quota usage. Emails with attachments or embedded URLs trigger separate analyses: one for each attachment and up to three URLs extracted from the email. Each of these counts as an individual submission to the service. The most severe classification result is propagated to the parent report, with detailed information provided in the `report.related_analysis` and `report.static.email` fields of the report. ## Privacy Whether submitted files, email metadata, PCAP files, screenshots, dropped files, and memory string dumps will be shared with other ReversingLabs customers depends on the role configured for the Spectra Intelligence account used to upload files. If the account is configured to upload all files as shareable (not private), other ReversingLabs customers will be able to access analysis results, but also download the uploaded files, dropped files, PCAP files, screenshots, and memory string dumps generated during file execution. If the account is configured to upload all files as not shareable (private), other ReversingLabs customers will only be able to access analysis results, but not retrieve the actual contents of uploaded files, emails, dropped files, PCAP files, screenshots or memory string dumps. **This API is rate limited to 3 requests per minute.** ## Dynamic Analysis Request This query is used to submit a sample or URL for dynamic analysis. Detonation of archives is supported by a [separate endpoint](#dynamic-analysis---archive-detonation). ### Request ``` POST /api/dynamic/analysis/analyze/v1/query/{post_format} ``` Path parameters: - `post_format` - Defines the POST payload format. Supported formats are: `xml` and `json`. - Required #### Request body - `md5`/`sha1`/`sha256` - The hash of the file to be analyzed. It must match a previously uploaded sample of a supported file type. Mutually exclusive with `url` and `url_base64`. - Required - `url` - The URL to be analyzed. Mutually exclusive with `sha1` and `url_base64`. - Required - `url_base64` - Base64-encoded URL to be analyzed. Mutually exclusive with hashes (`md5`/`sha1`/`sha256`) and `url`. The value is decoded and normalized, and then used to calculate a SHA1 and Base64 of the normalized URL. All three values (decoded and normalized URL, SHA1 and Base64 of the normalized value) are returned in the response. - Required - `platform` - The platform to execute the sample on. Supported values are `windows11`, `windows10`, `windows7`, `macos11`, `linux`, `android12`. - Required - `response_format` - Specifies the response format. Supported values are `json` (default), `xml` - Optional - `interactive` - Available only to Spectra Analyze instances with the proper role. Can be either "true" or "false" (string, not boolean). - `timeout` - How long (in seconds) a sample can run in the sandbox virtual machine. Different from total analysis time, which will be longer than the timeout. Default: `200`. Minimum allowed value: `30`. Maximum allowed value: `500`. - `optional_parameters` - Additional optional parameters to send with the request. Provide the optional parameters in the format of a comma-delimited string. - `internet_simulation`: 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. **Note: When Internet simulation is disabled/omitted and samples are allowed to connect to the Internet, network traffic obfuscation measures are implemented to protect the analysis infrastructure. Traffic obfuscation is achieved through VPN routing that masks the origin of network requests, preventing external entities from identifying the analysis environment.** - `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`. #### Example JSON for file analysis ``` json { "rl": { "sha1": "72e76e5273496e674c20ab5352e56e7253696e47", "platform": "windows7", "response_format": "json", "optional_parameters": "internet_simulation=true, sample_name=Sample, geolocation=us, locale=en-US" } } ``` #### Example JSON for URL analysis ``` json { "rl": { "url": "http://www.google.com", "platform": "windows7", "response_format": "json", "optional_parameters": "geolocation=us, locale=en-US" } } ``` ### Response #### Response format for file analysis - `requested_hash` - The submitted SHA1 hash. - `analysis_id` - The ID that was assigned to this submission. It can be used to retrieve the report of this specific analysis. - `status` - Shows if the dynamic analysis started successfully. Example: ``` json { "rl": { "requested_hash": "3c3ce51a7ab839c2f412fb06212fcf6a92932252", "analysis_id": "663a0671-36d2-4a1a-8f3b-e5ddcb91f5e5", "status": "started" } } ``` #### Response format for URL analysis - `url` - The normalized submitted URL. - `sha1` - The SHA1 hash of the normalized submitted URL. - `url_base64` - The normalized submitted URL encoded in base64 format. - `analysis_id` - The ID that was assigned to this submission. It can be used to retrieve the report of this specific analysis. - `status` - Shows if the dynamic analysis started successfully. Example: ``` json { "rl": { "url": "http://www.google.com", "status": "started", "sha1": "171ba7127cf28cc63ea1fef74be9746842f5093f", "url_base64": "aHR0cDovLzk3NzkuaW5mby8", "analysis_id": "4c923efb-a282-4aa1-8cda-d3eb04fa14e8" } } ``` ### Examples #### Submitting a hash for analysis ``` /api/dynamic/analysis/analyze/v1/query/json ``` ##### Request body ``` json { "rl": { "sha1": "83c69d2b26a1d1e5218e666316080b458e2e6948", "platform": "windows7" } } ``` #### Submitting a URL for analysis ``` /api/dynamic/analysis/analyze/v1/query/json ``` ##### Request body ``` json { "rl": { "url": "http://www.google.com", "platform": "windows7" } } ``` #### Submitting a Base64 encoded URL for analysis ```` /api/dynamic/analysis/analyze/v1/query/json ```` ##### Request body ``` json { "rl": { "url_base64": "aHR0cDovL3d3dy5nb29nbGUuY29t", "platform": "windows7" } } ``` #### Unsupported file type Submitting a file hash matching an unsupported file type will return the HTTPS status code 406 and the following message: `filetype_not_supported`. #### File exceeds the maximum file size Submitting a file hash matching a file larger than 400 MB will return the HTTPS status code 406 and the following message: `sample_size_exceeds`. #### Sample doesn't exist in Spectra Intelligence If a submitted file hash does not exist in Spectra Intelligence, the service will respond with the HTTPS status code 404 and the following message: `sample_not_found`. ## Dynamic Analysis - Archive Detonation ### Request ``` POST /api/dynamic/analysis/analyze/v1/archive/query/{post_format} ``` All provided parameters will apply to all files in the archive. An archive can contain a maximum of 10 non-archives, each one up to 400 MB in size, that will be sent to a sandbox for detonation. Only successful submissions of individual files will count against the user's quota for this API. The process of submission of archives is identical to the process of submission of other files - in both cases, the user sends a MD5/SHA1/SHA256 hash of the file to analysis. ### Response ``` json { "rl": { "requested_hash": "e662bfd39cf389b0bad5262e6007c09824261ee4", "files": [ { "sha1": "zzzf8d4dd290435a978e70adcf7876c0", "analysis_id": "bedf8d4d-d290-435a-978e-70adcf7876c0", "status": "started" }, { "sha1": "bbbf8d4dd290435a978e70adcf7876c0", "analysis_id": "uuuf8d4d-d290-435a-978e-70adcf7876c0", "status": "started" }, { "sha1": "zzzf8d4dd290435a978e70adcf7876c0", "analysis_id": "hhhf8d4d-d290-435a-978e-70adcf7876c0", "status": "started" }, { "sha1": "cccf8d4dd290435a978e70adcf7876c0", "analysis_id": "zzzf8d4d-d290-435a-978e-70adcf7876c0", "error_message": "sample_size_exceeds" }, { "sha1": "uuuf8d4dd290435a978e70adcf7876c0", "analysis_id": "lllf8d4d-d290-435a-978e-70adcf7876c0", "error_message": "filetype_not_supported" } ] } } ``` #### Too many files in archive Submitting an archive which contains more than the maximum allowed amount of files will return the HTTPS status code 406 and the following message: `too_many_files_in_archive`. #### Archive doesn't exist If a submitted archive does not exist, the service will respond with the HTTPS status code 404 and the following message: `archive_not_found`. --- ## Spectra Intelligence File Threat Intelligence API Overview The File Threat Intelligence APIs help security teams assess file reputation, retrieve detailed analysis reports, and manage classification overrides for files in the Spectra Intelligence system. ## Common Use Cases ### Check if a file is malicious - **[File reputation (TCA-0101)](tca-0101.md)** - Get malware status (malicious, suspicious, known, unknown) with threat level, trust factor, and malware family details. Supports bulk queries. - **[File reputation override (TCA-0102)](tca-0102.md)** - Override file classifications within your organization to handle false positives or flag internal threats. ### Get detailed file analysis - **[File analysis (TCA-0104)](tca-0104.md)** - Retrieve comprehensive analysis results for a submitted sample, including file hashes, metadata, relationships, and source history. Depending on availability, the response may include static and dynamic analysis findings, multi-AV detections, behavioral indicators, certificates, and URLs or other artifacts extracted from images or QR codes. - **[File analysis (goodware) (TCA-0105)](tca-0105.md)** - Get analysis data for known-good files only, with trust factor and relationships. ### Review AV scan history - **[Historic multi-AV scan records (TCA-0103)](tca-0103.md)** - Retrieve current and historical multi-AV scan reports showing detection changes over time. ## All File Threat Intelligence APIs --- ## File Reputation API (tca-0101) — Spectra Intelligence # File reputation (TCA-0101) The File Reputation (Malware Presence) service provides information about the malware status of requested samples. The status can be malicious, suspicious, known, or unknown. The service supports single and bulk queries. It also provides an option to return extended response data that includes even more information about samples, such as their trust factor, threat level, and more. Additionally, it is possible to retrieve MD5, SHA1, and SHA256 hashes for the requested sample(s) using the **show_hashes** parameter. **This API is rate limited to 500 requests per second.** ## General Info about Requests/Responses - All requests support the **format** parameter which supports two options: **xml** or **json**. - Default response format is **xml**, except for bulk queries, where the default response format is the same as the **post_format**. - The number of hashes in a bulk request must not be greater than **100**. - POST requests must contain an HTTP header field **Content-Type: application/octet-stream** ## Malware Presence This query returns information about the malware status of the requested sample. ### Request ``` GET /api/databrowser/malware_presence/query/{hash_type}/{hash_value} ``` - `hash_type` - Specifies which hash type will be used in the request. Supported values: `md5`, `sha1`, `sha256` - Required - `hash_value` - 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 ### Response ``` json { "rl": { "malware_presence": { "status": "KNOWN", "query_hash": { "sha1|md5|sha256": "hash_value" } } } } ``` - `status` - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). Read more about the ReversingLabs [classification algorithm](/General/AnalysisAndClassification/Classification). - `query_hash` - The hash type and value used in the request. Can be `md5`, `sha1`, or `sha256` ## Malware Presence Bulk A bulk query will return a response of the same format as a single query retrieves, but for multiple hashes in a single response. There are also additional response fields describing ill-formatted hashes, and hashes not found by the service. Up to 100 hashes can be submitted in one request. ### Request ``` POST /api/databrowser/malware_presence/bulk_query/{post_format} ``` - `post_format` - 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. - Required The following rules apply to both formats (XML and JSON). - **hash_type** value must be one of the following: `md5`, `sha1`, `sha256` - **hash_value** must be a valid hash of the same type specified by `hash_type` #### Request body ``` json { "rl": { "query": { "hash_type": "hash_type", "hashes": [ "hash_value", "hash_value", "...", "hash_value" ] } } } ``` ### Response ``` json { "rl": { "entries": [ { "status": "UNKNOWN", "query_hash": { "sha1|md5|sha256": "hash_value" } } ], "invalid_hashes": [ "hash_value" ] } } ``` Items in `rl.entries` in the **bulk** query response are equivalent to the `rl.malware_presence` element in the **single** query response. ## Extended Malware Presence Single and bulk queries support an additional query parameter `extended`. This is an optional parameter that specifies whether extended classification metadata for the requested sample(s) should be returned in the response. The parameter can be set to `true` (include extended metadata) or `false` (default; don't include extended metadata). If the parameter is not provided in the request, it is interpreted as `false` (extended metadata is not returned). Extended metadata includes information such as trust factor and threat level values; malware type, family name, and platform; first and last seen times, and more. It may also include information on the classification reason for each sample. This information is conveyed in the optional response field `reason`, which is only returned when the `extended` parameter is included in the request, and only if the field is calculated for the requested sample(s). Classification reason information helps users understand the logic behind sample classification decisions; particularly in the case of goodware overrides. This is an advanced goodware whitelisting technique designed to prevent and suppress possible false positives within highly trusted software packages. If a sample has a valid and trusted certificate signature, or if it came from a trusted source, the sample and all its extracted files should be whitelisted regardless of the AV results. A common example of this are samples with high AV detection results that have the KNOWN classification status. ### Single Query with Extended Option ``` GET /api/databrowser/malware_presence/query/hash_type/hash_value?extended=true ``` ### Bulk Query with Extended Option ``` POST /api/databrowser/malware_presence/bulk_query/post_format?extended=true ``` ### Response The response format is the same for sample nodes in both single and bulk queries. ```json { "rl": { "malware_presence": { "status": "string", "threat_level": 0, "scanner_percent": 0, "scanner_match": 0, "last_seen": "string", "reason": "string", "scanner_count": 0, "query_hash": { "sha1": "string" }, "first_seen": "string", "trust_factor": 0 } } } ``` - `status` - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS). The status designation is calculated by a proprietary ReversingLabs algorithm that adapts and improves as new information about the file and the threat is discovered. - The algorithm takes the following into account: Spectra Intelligence antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information. - `reason` - Optional response field that clarifies the reason why a sample received a particular classification status. This field is presently not calculated for all samples in the Spectra Intelligence system, which means it can be omitted from the response. - The value of this field can be one of the following: `analyst_sample_override` (the sample was classified manually after an analysis), `antivirus` (the sample was classified by the ReversingLabs multi-scan algorithm based on aggregated antivirus scan results), `best_certificate` (the sample or its container are signed with a valid and trusted certificate), `best_source` (the sample can be obtained from a trusted source, or it was unpacked from a file originating from a trusted source), `TC_certificate` (the sample is signed with a recognized whitelisted certificate), `next-gen-av` (the sample was classified based on aggregated next-gen antivirus scan results), `sandbox` (classified by the ReversingLabs Cloud Sandbox) (*deprecated*). - `scanner_count` - Number of scanners used in the last scan - `classification` - Malware classification based on the latest analysis of the requested sample, calculated by the ReversingLabs algorithm. See rl > malware_presence > classification for details - `scanner_percent` - Percent of scanners that detected malware in the last scan - `scanner_match` - Number of scanners that detected malware in the last scan - `threat_name` - Detected threat name for the requested sample - `query_hash` - Hash value used in the request; can be md5, sha1, or sha256 - `first_seen` - Indicates the date and time when the sample was first uploaded to the system, or when it has received a scan result for the first time - `last_seen` - Indicates the date and time when the sample last received impactful changes to its analysis or classification data - `threat_level` - Threat level value for the requested sample (0 indicates no threat; 1 is the lowest threat value - lowest severity, such as Adware; 5 is the highest threat value, e.g, Trojan) - `trust_factor` - Trust factor value of the sample's sources (0 is the most trusted; 5 is the least trusted) ---------------------------------------------------------------------- `rl.malware_presence.classification` - `family_name` - Malware family name of the detected malware - `subplatform` - Subplatform targeted by the detected malware; can be one of the subplatforms defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). - `platform` - Platform targeted by the detected malware; can be one of the platforms defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). - `is_generic` - Select trusted 3rd party AV scanners assigned threat names that, based on their naming conventions suggest the sample was "generically" and/or "heuristically" identified as having characteristics similar to known malicious software. If malware is detected in this way, this field returns a true value - `cve` - If applicable, contains the Common Vulnerabilities and Exposures (CVE) identifier. Additional fields are is_candidate (returns true if the sample is a CVE candidate or false if the sample is an official CVE list entry), CVE number, and CVE year - `type` - Malware type; can be one of the types defined in [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). ---------------------------------------------------------------------- ### Response Examples #### Sample with Malware Presence Status MALICIOUS ``` json { "rl": { "malware_presence": { "status": "MALICIOUS", "scanner_count": 40, "classification": { "platform": "Win32", "type": "Trojan", "is_generic": false, "family_name": "Nsis" }, "scanner_percent": 82.5, "scanner_match": 33, "threat_name": "Win32.Trojan.Nsis", "query_hash": { "sha1": "1d412db0ac58dd8d8bfae8b18c7b355bd14dab2f" }, "first_seen": "2012-07-12T00:05:00", "threat_level": 5, "trust_factor": 5, "last_seen": "2017-08-09T11:40:00" } } } ``` #### Sample with Malware Presence Status SUSPICIOUS ``` json { "rl": { "malware_presence": { "status": "SUSPICIOUS", "scanner_count": 29, "classification": { "subplatform": "JS", "platform": "Script", "is_generic": false, "family_name": "Trojan-downloader" }, "scanner_percent": 6.8965516090393066, "scanner_match": 2, "threat_name": "Script-JS.Malware.Trojan-downloader", "query_hash": { "sha1": "e0c58164cde263904abc07915d7c9d2722e3806c" }, "first_seen": "2017-09-07T01:14:31", "threat_level": 0, "trust_factor": 5, "last_seen": "2017-09-28T09:08:00" } } } ``` #### Sample with Malware Presence Status KNOWN ``` json { "rl": { "malware_presence": { "status": "KNOWN", "reason": "TC_certificate", "scanner_count": 25, "scanner_percent": 76, "scanner_match": 19, "query_hash": { "sha1": "5ff74f670c8a68557bf36955d3e4e2353266d607" }, "first_seen": "2016-06-30T01:17:42", "threat_level": 0, "trust_factor": 0, "last_seen": "2019-10-17T10:03:23" } } } ``` #### Sample with Malware Presence Status UNKNOWN ``` json { "rl": { "malware_presence": { "status": "UNKNOWN", "query_hash": { "sha1": "e4e8c856c1524ff22b87b29d605ab8fdb1007298" } } } } ``` ## Malware Presence with Available Hashes Single and bulk queries support an additional request parameter `show_hashes`, which can be set to either `true` or `false`. This optional parameter can be used in combination with the `extended` parameter in the same request. When set to `true`, the `show_hashes` parameter specifies that 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, it is interpreted as `false` (additional hashes are not returned). ### Request ``` GET /api/databrowser/malware_presence/query/hash_type/hash_value?show_hashes=true ``` ``` POST /api/databrowser/malware_presence/bulk_query/{post_format}?show_hashes=true ``` ### Response Entries in `rl.entries` in the bulk query response are equivalent to the `rl.malware_presence` element in the single query response. If both the **extended** and **show_hashes** parameters are set to true then the response will contain both extended malware presence information and MD5, SHA1 and SHA256 hashes. ``` json { "rl": { "malware_presence": { "status": "KNOWN", "query_hash": { "sha1|md5|sha256": "hash_value" }, "md5": "md5 hash_value", "sha1": "sha1 hash_value", "sha256": "sha256 hash_value" } } } ``` - `status` - Malware presence status designation (UNKNOWN, KNOWN, SUSPICIOUS, or MALICIOUS) - `query_hash` - The hash type and value used in the request; can be MD5, SHA1, or SHA256 - `md5, sha1, sha256` - Respective hashes for the requested sample(s). ## Examples ### Single query - changing the response format ``` /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml ``` ### Single query - changing the hash type ``` /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b /api/databrowser/malware_presence/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd /api/databrowser/malware_presence/query/md5/ca083f61113e1fb8f539ecfa7c725fc8 ``` ### Single query - changing the optional flags ``` /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?extended=true /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?show_hashes=true /api/databrowser/malware_presence/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?extended=true&show_hashes=true ``` ### Bulk query - changing the POST format ``` /api/databrowser/malware_presence/bulk_query/json /api/databrowser/malware_presence/bulk_query/xml ``` With bulk queries, the response format will default to the request format. If you want a different response format, add the **format** query field: ``` /api/databrowser/malware_presence/bulk_query/xml?format=json ``` ### Bulk query - JSON POST format ``` /api/databrowser/malware_presence/bulk_query/json ``` ``` json { "rl": { "query": { "hash_type": "md5", "hashes": [ "4bb64c06b1a72539e6d3476891daf17b", "6353de8f339b7dcc6b25356f5fbffa4e", "59cb087c4c3d251474ded9e156964d5d", "6c2eb9d1a094d362bcc7631f2551f5a4", "a82c781ce0f43d06c28fe5fc8ebb1ca9", "920f5ba4d08f251541c5419ea5fb3fb3" ] } } } ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "13e40f38427a55952359bfc5f52b5841ce1b46ba", "831fc2b9075b0a490adf15d2c5452e01e6feaa17", "42b05278a6f2ee006072af8830c103eab2ce045f" ] } } } ``` ``` json { "rl": { "query": { "hashes": [ "0001f757f6b9523707462066100aa543", "000202ed4a0fb4c95e68824bc7777a78", "00026f63fd5a2600b73a866d7ef08b6f" ], "hash_type": "md5" } } } ``` --- ## File Reputation Override API (tca-0102) — Spectra Intelligence # File reputation override (TCA-0102) The File Reputation User Override service enables sample classification overrides. Any sample 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. For more information on classifications, trust factor, threat level, and the ReversingLabs malware naming standard, see the TCA-0101 File Reputation (Malware Presence) documentation. **This API is rate limited to 10 requests per second.** ## General Info about Requests/Responses - All requests support the **format** parameter which supports two options: **xml** or **json**. - Default response format is **xml**. ## User Override This query allows classification overrides for one or more sample hashes. Up to 100 hashes can be submitted in one request. ### Request ``` POST /api/databrowser/malware_presence/user_override/{post_format} ``` - `post_format` - Required parameter that defines the POST payload format. Supported options are **xml** and **json**. - Required #### Request body ``` json { "rl": { "query": { "override_samples": [ { "sha1": "string", "md5": "string", "sha256": "string", "status": "string", "trust_factor": 0 }, { "sha1": "string", "md5": "string", "sha256": "string", "status": "string", "threat_level": 0, "threat_name": "string" } ], "remove_override": [ { "sha1": "string", "md5": "string", "sha256": "string" } ] } } } ``` The following rules apply to both formats (XML and JSON). One of the following fields, `override_samples` or `remove_override`, must be provided and not empty: - **override_samples** requires an array of objects with **md5**, **sha1**, **sha256**, and **status** - **status** options: MALICIOUS, SUSPICIOUS, KNOWN - For KNOWN status: - Optional **trust_factor**: integer (0-5), defaults to 0 - Not accepted: **threat_level** and **threat_name** - For MALICIOUS/SUSPICIOUS status: - Optional **threat_name**: follows the ReversingLabs malware naming standard, defaults to **Win32.Trojan.Generic** - Optional **threat_level**: integer (1-5), auto-determined if not provided - Not accepted: **trust_factor** - **remove_override** must be an array of objects containing `md5`, `sha1`, and `sha256`. These samples will have their classification overrides removed. For more information on these values, refer to the TCA-0101 File Reputation (Malware Presence) documentation. The total number of sample overrides to create, update and delete may not exceed 100 in a single request. In case the request does not pass input validation for any reason, the endpoint will return the `400 Bad Request` status code, the response body will contain a helpful error message, and any overrides, valid or not, will be rejected. ### Response ``` json { "rl": { "user_override": { "create_override": [ { "status": "string", "sha256": "string", "sha1": "string", "md5": "string", "threat_level": 0, "threat_name": "string" } ], "replace_override": [ { "status": "string", "sha256": "string", "sha1": "string", "md5": "string", "trust_factor": 0 } ], "remove_override": [ { "sha256": "string", "sha1": "string", "md5": "string" } ] } } } ``` - `rl.user_override.create_override` is an array of all newly created classification overrides - `rl.user_override.replace_override` is an array of all new overrides which will replace existing overrides - `rl.user_override.remove_override` is an array of all overrides to be removed There are also additional response fields describing ill-formatted hashes, and hashes not found by the service. Format of each element within these fields matches the request format. Requests to TCA-0101 File Reputation (Malware Presence) for overridden samples may still return other metadata such as scanner info, CVE data etc., but will return user-specified classification details, and **user_sample_override** as a reason for the classification. ## List Overrides The List Overrides Query returns a list of all currently active overrides for the current organization. ### Request ``` GET /api/databrowser/malware_presence/user_override/list_hashes/{hash_type}?start_hash=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json|xml&extended=true|false ``` - `hash_type` - Specifies which hash type will be used in the request. Supported values: `md5`, `sha1`, `sha256` - Required - `start_hash` - When this parameter is present, the API will return up to 1000 hashes with a classification override starting from the `start_hash` value. The format must correspond to the one defined with the `hash_type` parameter. - Optional - `format` - Response format. Supported values: `json`, `xml`. Default (none): `xml`. - Optional - `extended` - When set to `true`, the response extends `rl.user_override.hash_values` into an array of objects containing hash values and classification metadata. In this case, the `hash_type` parameter affects only the type of the `next_hash` value, as the response entries will nor contain all available hash types. - Default (absent or `false`): the response format remains unchanged (array of hash strings). - Optional ### Response Format `rl.user_override.hash_values` is an array of hashes specified by the `hash_type`, or objects if `extended=true`. Hashes in the response are sorted. The response contains up to 1000 entries. If there are more than 1000 currently overridden samples, `rl.user_override.next_hash` will be a hash value which can be provided in a subsequent request as a `start_hash` query parameter. If this is the last page, or there are no more than 1000 overrides, `next_hash` will be **null**. **Response Fields** - `rl.user_override.hash_values` - Array of hashes specified by the `hash_type`, or objects if `extended=true`. - `rl.user_override.next_hash` - Hash value which can be provided in a subsequent request as a `start_hash` query parameter. **Extended Response Fields** - `rl.user_override.hash_values` - Array of objects containing hash values and classification metadata. - Each object contains the following fields: - `sha1`: SHA1 hash value. - `md5`: MD5 hash value. - `sha256`: SHA256 hash value. - `status`: Classification status (MALICIOUS, SUSPICIOUS, KNOWN). - `threat_level`: Threat level (1-5) for MALICIOUS/SUSPICIOUS classification/status. - `trust_factor`: Trust factor (0-5) for KNOWN classification/status. - `threat_name`: Threat name for MALICIOUS/SUSPICIOUS classification/status. - `rl.user_override.next_hash` - Hash value which can be provided in a subsequent request as a `start_hash` query parameter. ``` json { "rl": { "user_override": { "hash_values": [ "string", "string", "string", "string" ], "next_hash": null } } } ``` #### Extended Response Format (`extended=true`) ``` json { "rl": { "user_override": { "hash_values": [ { "sha1": "28279d17721bdce45111f8d62998dbf04cd943f5", "md5": "1e7df4685b1d4a6886215d2b0a8d9370", "sha256": "94b4387b9e7e715d1e10f11a5aa664e05b5e6989e5168605ddd2f68905dadb24", "status": "SUSPICIOUS", "threat_level": 1, "threat_name": "Win32.Malware.Generic" }, { "sha1": "562527985fa902f778f824951d0d4958ed6447ba", "md5": "b918da6cd16de67e2ff4e5029fc5e416", "sha256": "4f0d0a1e96e0a3755ed7f6d73083d846176d3b338740e62854fcfaee404e6d77", "status": "KNOWN", "trust_factor": 0 } ], "next_hash": "64ac2597da314420792b42e81b67f377fc083c91" } } } ``` --- ## Historic Multi-AV Scan Records API (tca-0103) — Spectra Intelligence # Historic multi-AV scan records (TCA-0103) The Historic Multi-AV Scan Records service provides multi-AV scan reports for a given sample. Additionally, the service allows fetching historic multi-AV scan results. Single or bulk queries are supported. **This API is rate limited to 400 requests per second.** ## General Info about Requests/Responses - All requests support the **format** query field which supports two options: **xml** or **json**. - Default response format is *xml*, except for bulk queries, where default format is the same as the **post_format**. - All bulk query rules will accept post payload of the same format (described below). - The number of hashes in a bulk request must not be larger than 100. - POST requests must set **Content-Type: application/octet-stream** in the HTTP header field. - Scanners that failed while scanning the sample are not shown in the **results** field. If the whole **results** field is missing from the **xref** field, all scanners failed to scan the sample. ## Multi-AV Scan Report ### Request ``` GET /api/xref/v2/query/{hash_type}/{hash_value}{?format=xml|json} ``` - **hash_type** can be: `md5`, `sha1`, `sha256` - **hash_value** must be a valid hash defined by **hash_type** - **format** can be: `xml` or `json` - If the entry is not found, the API will return an HTTP 404 response ### Response `rl.sample` ``` json { "rl": { "sample": { "sha1": "string", "sha256": "string", "sha384": "string", "sha512": "string", "ripemd160": "string", "md5": "string", "first_seen_on": "string", "last_seen_on": "string", "single_scan": false, "first_scanned_on": "string", "last_scanned_on": "string", "sample_type": "string", "sample_size": 0, "xref": [ { "scanned_on": "string", "scanner_match": 0, "scanner_count": 0, "results": [ { "scanner": "string", "result": "string" } ], "scanners": [ { "name": "string", "version": "string", "timestamp": "string" } ] } ] } } } ``` - `sha1` - SHA1 value; this field is mandatory and can be used as a primary key - `first_seen_on` - Indicates the date and time when the file was first uploaded to the system, or when it was scanned for the first time - `last_seen_on` - Indicates the date and time when the file was last uploaded to the system, or when it was scanned for the last time - `single_scan` - True if the sample has only one multi-AV scan report; otherwise it's false - `first_scanned_on` - The date and time of the first scan result - `last_scanned_on` - The date and time of the last scan result - `sample_type` - File type description e.g. MS Windows Shortcut, PE32 executable (GUI) Intel 80386, for MS Windows, ... - `sample_size` - Sample size (in bytes) - `xref` - Multi-AV scan records (The latest AV scanning report about the given sample, no historical results because history=false) ---------------------------------------------------------------------- `rl.xref.item` - `scanned_on` - The UTC timestamp when the sample was scanned (if history exists - in this case it's the latest result) - `scanner_match` - The number of AV scanners with results - `scanner_count` - The overall number of AV scanners that scanned the sample - `results` - A list of results per scanner for this report ---------------------------------------------------------------------- `rl.xref.item.results` - `item` - The scanner-specific scanning report, contains two objects: the `scanner` name and the scanning `result` string. ---------------------------------------------------------------------- The scanners object contains scanner information. Each scanner is in a separate `item` object. `rl.xref.scanners.item` - `name` - Scanner name. - `version` - The name of the antivirus engine file (or its update) used for this scanning report. - `timestamp` - The scanner update timestamp. This update can refer either to an update in the AV database or an update to the AV engine itself. ## Multi-AV Scan Bulk Report This query retrieves the same data as single query does, but for multiple hashes within single response. It is more network-efficient compared to multiple single queries. ### Request ``` POST /api/xref/v2/bulk_query/{post_format} ``` - **post_format** is a required parameter that defines the POST payload format. The parameter accepts the following formats: **xml** and **json** #### Request body ``` json { "rl": { "query": { "hash_type": "string", "hashes": [ "string", "string" ] } } } ``` - **hash_type** must be one of the following options: **md5**, **sha1**, **sha256** - **hash values** must be valid hashes defined by `hash_type` ### Response ``` json { "rl": { "samples": [], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" ] } } ``` - `invalid_hashes` - A list of ill-formatted hashes provided in request - `unknown_hashes` - A list of hashes from the request that were not found in the database or don't have multi-AV data ## Multi-AV Scan History Both single and bulk multi-AV queries support an additional query parameter **history** which can be either `true` or `false`. If not specified, the default value is `false`. When set to `true`, the service will provide the last 20 multi-AV records. ### Request ``` GET /api/xref/v2/query/hash_type/hash_value?history=true&format=xml ``` ``` POST /api/xref/v2/bulk_query/post_format?history=true&format=json ``` - **history** defines whether the response should contain multi-AV records from history (when *true*) or latest one only (when *false*, default) - **format** defines the response format: *xml* or *json* ### Response When `history` is true, everything is the same as in the single query, except the `rl.sample.xref` object which now contains the history of scan results (if there are more than one). ``` json { "rl": { "sample": { "sha1": "string", "sha256": "string", "sha384": "string", "sha512": "string", "ripemd160": "string", "md5": "string", "first_seen_on": "string", "last_seen_on": "string", "single_scan": false, "first_scanned_on": "string", "last_scanned_on": "string", "sample_type": "string", "sample_size": 0, "xref": [ { "scanned_on": "string", "scanner_match": "string", "scanner_count": "string", "results": [ {} ], "scanners": [ {} ] } ] } } } ``` ## Examples ### Different response formats These examples request different response formats: ``` /api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json /api/xref/v2/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=xml ``` ### Different hash types These examples use different hash types: ``` /api/xref/v2/query/sha1/531249faab39b526fc0b5f38af5c22af83887151 /api/xref/v2/query/sha256/000051db594056505dafa98420221285a3b1701282a54091aad7c63aa19f9854 ``` ### Different post formats These examples use different post formats: ``` /api/xref/v2/bulk_query/xml /api/xref/v2/bulk_query/json ``` #### Example of JSON bulk POST payload ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "13e40f38427a55952359bfc5f52b5841ce1b46ba", "831fc2b9075b0a490adf15d2c5452e01e6feaa17", "42b05278a6f2ee006072af8830c103eab2ce045f" ] } } } ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | MESSAGE | DESCRIPTION | |:-----|:---------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | Invalid username | The username sent in the Authorization header contained unrecognized characters, or was otherwise invalid. | | | Invalid hash value | The requested hash value did not match the hash type, or was otherwise invalid. | | | Invalid hash type | The requested hash type was not recognized. Accepted types are SHA1, SHA256, MD5. | | | Parsing error description | There was a problem with parsing the request. Possible reasons: no JSON object could be decoded; a parameter name is missing; a required parameter is missing; a delimiter character is missing. | | | Unknown POST format | The requested POST format was not recognized. Accepted formats are XML and JSON. | | | Empty request | The request did not contain any values or parameters. | | 403 | | The server understood the request, but is refusing to fulfill it. The user account that sent the request is disabled. | | | User not allowed | The user account that sent the request does not have the required permissions. | | 404 | Missing multi-AV scan for sample | The requested sample does not have an multi-AV scan record. | --- ## File Analysis API (tca-0104) — Spectra Intelligence # File analysis (TCA-0104) This service provides analysis data on requested hashes. Depending on the hash, the response can include relevant portions of static analysis, dynamic analysis information, AV scan information, file sources and any related IP/domain information. The service supports single and bulk hash queries. For additional context on indicators of compromise and actively exploited vulnerabilities, refer to [CISA's Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities). **This API is rate limited to 100 requests per second.** ## General Info about Requests/Responses - All requests support the **format** query field which supports two options: **xml** or **json**. - Default response format is *xml*, except for bulk queries, where default format is the same as the **post_format** - All bulk query rules will accept POST payload of the same format (described below). - The number of hashes in a bulk request must not be larger than a hundred (100). - POST requests must set in HTTP header field **Content-Type: application/octet-stream** - Dynamic analysis report is only available with additional permissions. **Note: Querying Results for Recently Uploaded Files** When querying results for recently uploaded files, use the **SHA1 hash**. SHA256 and other hash types become available only after the file analysis is complete. ## Single File Analysis This query returns a response containing analysis results for the requested hash. Depending on the hash, the response can contain information such as full file format information, static analysis data, historic multi-AV scan records, extracted malware configuration network and mutex data, dynamic network analysis data, file sources, parent information, certificate chain data, certificate signer information. ### Request ``` GET /api/databrowser/rldata/query/{hash_type}/{hash_value}[?format=xml|json] ``` - **hash_type** accepts these options: *md5*, *sha1*, *sha256* - **hash_value** must be a valid hash defined by the **hash_type** parameter ### Response Response code 404 is returned with a message "Requested data was not found" when the requested hash isn't found in the database.
Response ``` json { "rl": { "sample": { "sha1": "string", "md5": "string", "sha256": "string", "sha384": "string", "sha512": "string", "ripemd160": "string", "ssdeep": "string", "tlsh": "string", "sample_size": 0, "password_uploaded": "bool" "relationships": { "container_sample_sha1": [ "string" ], "parent_sample_sha1": [ "string" ], "child_sample_sha1": [ "string" ], "more_child_samples_available": "bool" }, "analysis": { "entries": [ { "record_time": "string", "analysis_type": "string", "analysis_version": "string", "tc_report": { "info": { "file": { "file_type": "string", "file_subtype": "string" }, "identification": { "name": "string" } }, "interesting_strings": [ { "category": "string", "values": [ {} ] } ], "story": "string" } } ] }, "xref": { "entries": [ { "record_time": "string", "scanners": [ { "name": "string", "result": "string" } ], "info": { "scanners": [ { "name": "string", "version": "string", "timestamp": "string" } ] } } ], "first_seen": "string", "last_seen": "string", "sample_type": "string" }, "sources": { "entries": [ { "record_time": "string", "tag": "string", "properties": [ { "name": "string", "value": "string" } ], "domain": { "name": "string" } } ] }, "computer_vision_analysis": { "entries": [ { "analysis_time": "string", "results": [ { "format": "string", "category": "string", "value": "string" } ] } ] } } } } ```
`rl.sample` - `sha1` - SHA1 value of the requested sample. This field is mandatory and can be used as a primary key. - `hashes` - List of hashes computed for the requested sample, e.g. MD5, SHA256, SHA384, SHA512, SSDEEP, Authenticode hashes (PE_SHA1, PE_SHA256), imphash… - `tlsh` - A hash value which can be used for file similarity comparisons, helping to identify similar, nearly identical, or modified files. TLSH hash is not calculated if `SSDEEP` is enabled and the file size is either smaller than its minimum size (1024 bytes) or larger than its maximum size (734003200 bytes). - `sample_size` - Logical file size of the requested sample (in bytes). - `password_uploaded` - Indicates that password was uploaded for unpacking this sample. If a password wasn't uploaded, this field is omitted. - `relationships` - Parent, container and child sample lists. (limited) - `analysis` - Different analysis results for the requested sample. Currently only [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) is supported for this section. - `xref` - Collection of AV scanning reports for the requested sample. The API is able to return up to 20 last reports. Every **item** represents a single AV scanning report. - `sources` - A sequence of source items indicating where the sample came from. These can be different domains, specific uploaders, etc. One sample can have multiple sources. The service returns a list of 10 oldest sources, sorted by timestamp in descending order. - `dynamic_analysis` - If the sample has been detonated in the sandbox, the section displays network data and mutexes observed. - `computer_vision_analysis` - Processes samples to detect URIs in images and extract information from QR codes. If a sample has already been analyzed, this section displays the results. - For email samples, this section includes QR and OCR-decoded URIs found in the email itself and propagated from all child samples. ---------------------------------------------------------------------- `rl.sample.relationships` - `container_sample_sha1` - List of container hashes. Container is the top-level archive/sample that was uploaded to the system and also contains the requested sample. The response will contain up to 5 container sample hashes, sorted by SHA1 hash. - `parent_sample_sha1` - List of samples that directly contain the requested sample. The requested hash is a child to the hashes in this list. The list of children has been acquired by file extraction. The response will contain up to 5 parent sample hashes, sorted by SHA1 hash. - `child_sample_sha1` - A list of samples contained within the requested sample. - `more_child_samples_available` - Indicator that more than 10 child samples are available. If false, this field is omitted. ---------------------------------------------------------------------- `rl.sample.analysis.entries.item` - `record_time` - Timestamp indicating when the analysis was executed. - `analysis_type` - Label indicating the type of analysis (for example, TC_REPORT indicates Spectra Core static analysis). - `analysis_version` - Version of the tool used for analysis. - `tc_report` - Available metadata for the requested sample obtained as a result of Spectra Core static analysis. ---------------------------------------------------------------------- `rl.sample.analysis.entries.item.tc_report` - `info` - Contains information about **file_type**, **file_subtype**, **validation**, **identification**, and **package** (if applicable). - `metadata` - Relevant information about a sample extracted through static analysis. The fields returned in this section depend on the sample type. - `interesting_strings` - When Spectra Core encounters files with strings that contain interesting information, it will tag those files with tags corresponding to the type of string. Strings are considered interesting if they contain information related to various network resources and addresses. Interesting strings are usually found in binary files, documents and text files. Every **item** inside this object belongs to a **category** and contains **values**. - The `category` field classifies the extracted string based on its type. It includes common network resource identifiers and address formats such as URIs, IPs, and protocols. Supported values: `domain`, `mailto`, `ipv4`, `ipv6`, `http`, `https`, `ftp`, `nfs`, `file`, `gopher`, `ldap`, `prospero`, `net.pipe`, `net.tcp`, `news`, `nntp`, `telnet`, `uuid`, and `wais`. - The `values` fields contain the extracted string values. - `story` - The story section contains a summarized natural language description of the file's behavior and properties. - `indicators` - List of indicators. They are the main static analysis technique Spectra Core uses to describe the analyzed content behavior. Since indicators are human-readable, their purpose is to simplify the code analysis process by converting complex code patterns into descriptions of their intent. Simply put, indicators make it possible to describe the file behavior through descriptions like “Downloads a file”, “Encrypts or encodes data in memory using Windows API”, “Enumerates currently available disk drives”, etc. While some indicators can only be found in certain formats, most are universal and therefore generally applicable. ---------------------------------------------------------------------- `rl.sample.analysis.entries.item.tc_report.info` - `file_type` - Type of the sample, as detected by Spectra Core (for example, Document, Image, PE…). - `file_subtype` - Subtype of the sample, as detected by Spectra Core (for example, TIFF, Clojure, HTML…). - `proposed_filename` - Suggested filename extracted from other metadata if the original filename is not available. - `identification` - Identification name of the sample. Identification is not generated for all file types and subtypes; it is an optional field in the static analysis report. - `validation` - Indicates whether a sample is considered valid by Spectra Core at the time it was processed. Optionally contains a list of validation descriptions, for example bad checksum, bad signature, invalid certificate, expired certificate, blacklisted certificate, whitelisted certificate, malformed certificate, self-signed certificate. Explanations of these values can be found in the table "Sample validation explanations" below. - `package` - Sample metadata related to malware configurations, such as C&C servers. ---------------------------------------------------------------------- `rl.sample.analysis.entries[].tc_report.metadata` - `application` - Refers to all PE files. Metadata that is extracted statically from these formats can vary depending on the type of application. This section can contain information such as **dos_header, file_header, optional_header, sections, imports, resources**... - `certificate` - If the requested sample contains certificate-related metadata, this section provides detailed information about certificates, such as **subject, issuer, serial_number, thumbprint, extensions**... - `attack` - If the requested sample contains MITRE ATT&CK metadata, this section provides list of **attack tactics**, and for each of these tactics, list of their **attack techniques** and **subtechniques**. Attack tactics, techniques and subtechniques have information about their **id, description and name**, while techniques and subtechniques can additionally contain indicators with priority, category, relevance etc. - software_packages - List of packages. File type reserved for all programming language-specific packages. **softwarePackage** is specific metadata related to the package file type. ---------------------------------------------------------------------- `rl.sample.analysis.entries[].tc_report.software_packages` - `name` - Package name - `description` - Package summary - `authors` - List of package authors - `release_dependencies` - List of release dependency packages with the field **name**, representing the name of the package - `develop_dependencies` - List of development dependency packages with the field **name**, representing the name of the package ---------------------------------------------------------------------- `rl.sample.analysis.entries[].indicators` - `priority` - Priority is a number used to sort the indicators from least to most interesting (0 to 10) within a category. It is determined by the severity of the action described by the indicator. More dangerous indicators are prioritized higher within their category. - `category` - Category to which the indicator belongs. - `description` - Short description of the capability referenced by the detected indicator. - `id` - Unique ID of an indicator. - `relevance` - Contribution to the final classification. ---------------------------------------------------------------------- `rl.sample.xref.entries[]` - `record_time` - Timestamp when the multi-AV report was generated. - `scanners` - List of results per scanner for this report. Every item is a scanner-specific scanning report, containing the scanner name and scanner detection string. - `info` - Information about the scanners used for this scanning report. Contains a sequence of scanners ordered by name, with **name, version**, and **timestamp** indicating when the scanner was updated. - `first_seen` - The date and time of the oldest multi-AV report created for the requested sample. - `last_seen` - The date and time when the sample last received impactful changes to its analysis or classification data. - `sample_type` - Detected sample type for the requested sample. ---------------------------------------------------------------------- `rl.sample.sources.entries[]` - `record_time` - Timestamp indicating when the requested sample was uploaded. - `tag` - Uploader designation indicating the origin of the sample; can be **reversing_labs**, **external_feed**, **microsoft_whitelist** or **nsrl**. - `properties` - Various sample-related information listed as **name/value** properties in free format. - `domain` - If there is a domain linked to the sample source, it will be described within this element. ---------------------------------------------------------------------- `rl.sample.dynamic_analysis.entries.dynamic_analysis_report` - `analysed_on` - Timestamp indicating when the dynamic analysis report for the requested sample was generated. - `version` - Numerical label indicating the version of the tool used for dynamic analysis. - `summary` - Contains **mutexes** detected during dynamic analysis (if any). - `network` - Contains information about **dns_requests, domains, tcp_destinations, udp_destinations, http_requests** detected during dynamic analysis. ---------------------------------------------------------------------- `rl.sample.computer_vision_analysis.entries[]` - `analysis_time` - The timestamp indicating when the computer vision analysis was performed. - `results` - A list of elements detected by the computer vision analysis. Each element includes the following fields: `format`, `category`, and `value`. - For email samples, `results` include URIs extracted directly from the email and URIs propagated from all child samples for up to 1,000 children, providing information for QR and OCR-decoded URIs within an email and its attachments. - The `format` field specifies the data format from which the string was extracted. Supported values: `OCR` for URIs extracted from images and PDFs, and `QR_CODE` for strings extracted from QR codes. - The `category` field classifies the extracted string based on its type. It includes common network resource identifiers and address formats such as URIs, IPs, and protocols. Supported values: `domain`, `mailto`, `ipv4`, `ipv6`, `http`, `https`, `ftp`, `nfs`, `file`, `gopher`, `ldap`, `prospero`, `net.pipe`, `net.tcp`, `news`, `nntp`, `telnet`, `uuid`, and `wais`. - The `value` field contains the extracted string value from the computer vision analysis. #### Sample validation explanations | Name | Description | |------|-------------| | Valid certificate | Any certificate with an intact digital certificate chain that confirms the integrity of the signed file. The hash within Signer Info matches the hash of the file contents. | | Invalid certificate | Any certificate with an intact digital certificate chain, but for which the certificate chain validation failed due to other reasons (e.g. because of attribute checks). Without a valid digital certificate chain, the integrity of the signed file cannot be validated. | | Bad checksum | The integrity of the signed file could not be verified, because the hash within Signer Info does not match the hash of the file contents. | | Bad signature | Any certificate with an intact digital certificate chain, but for which the signature validation failed. Without a valid signature, the integrity of the signed file cannot be validated. | | Malformed certificate | Any certificate that does not have an intact digital certificate chain. The digital certificate is corrupted or incomplete, but that doesn't mean the file is also corrupted. Without a valid digital certificate chain, the integrity of the signed file cannot be validated. | | Self-signed certificate | A self-signed certificate is a certificate that is signed by the same entity whose identity it certifies. In other words, this is a certificate that is used to sign a file, and doesn't have a CA that issued it. If CA information is present, but not found within the Spectra Core certificate store, the CA will be considered plausible and files signed with it will be declared valid (they will not be considered self-signed). | Impersonation attempt | Any self-signed certificate is a candidate for an impersonation check. Impersonation means that the signer is trying to misrepresent itself as a trusted party, where "trusted party" is defined by the certificate whitelist. Any self-signed certificate that matches the common name of another certificate on the Spectra Core whitelist is marked as an impersonation attempt | | Expired certificate | Any certificate with signing time information is checked for expiration. When the time on the local machine indicates that the certificate has passed its "valid to" date and time, the certificate is considered expired. The "Expired" certificate status is merely informative, and expired certificates cannot influence certificate classification. | | Untrusted certificate | Any valid certificate for which the digital certificate chain cannot be validated against a trusted CA. Untrusted certificates are valid certificates, but they cannot be whitelisted because their chain does not terminate with a CA in the Spectra Core certificate store. | | Other | security catalog, revoked certificate, revoked certificate unspecified, revoked certificate key compromise, revoked certificate ca compromise, revoked certificate affiliation changed, revoked certificate superseded, revoked certificate cessation of operation, revoked certificate hold, revoked certificate remove from crl, revoked certificate privilege withdrawn, revoked certificate aa compromise, signed after revocation, blacklisted certificate, whitelisted certificate, bad certificate timestamp | ## Bulk File Analysis This query retrieves the same data as the single query, but for multiple hashes within a single response. It is more network-efficient compared to several consecutive single queries. ### Request ``` POST /api/databrowser/rldata/bulk_query/{post_format} ``` - **post_format** is a required parameter that defines the POST payload format - **post_format** variable rule will accept the options `xml` and `json` The following definitions are valid for both formats: - **hash_type** value must be one of the following options: `md5`, `sha1`, `sha256` - **hash_value** must be a valid hash defined by hash_type #### Request body ``` json { "rl": { "query": { "hash_type": "hash_type", "hashes": [ "hash_value", "hash_value", "hash_value" ] } } } ``` ### Response ``` json { "rl": { "entries": [ {} ], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" ] } } ``` - `invalid_hashes` - A list of ill-formatted hashes provided in the request - `unknown_hashes` - A list of hashes from the request that were not found in the database or don't have multi-AV data ## Examples ### Single Query - changing the response format ``` /api/databrowser/rldata/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json /api/databrowser/rldata/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml ``` ### Single query - changing the hash type ``` /api/databrowser/rldata/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b /api/databrowser/rldata/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd ``` ### Bulk query - changing the POST format ``` /api/databrowser/rldata/bulk_query/xml /api/databrowser/rldata/bulk_query/json ``` ### Bulk query - JSON POST format ``` /api/databrowser/rldata/bulk_query/json ``` ``` json { "rl": { "query": { "hash_type": "md5", "hashes": [ "4bb64c06b1a72539e6d3476891daf17b", "6353de8f339b7dcc6b25356f5fbffa4e", "59cb087c4c3d251474ded9e156964d5d", "6c2eb9d1a094d362bcc7631f2551f5a4", "a82c781ce0f43d06c28fe5fc8ebb1ca9", "920f5ba4d08f251541c5419ea5fb3fb3" ] } } } ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "13e40f38427a55952359bfc5f52b5841ce1b46ba", "831fc2b9075b0a490adf15d2c5452e01e6feaa17", "42b05278a6f2ee006072af8830c103eab2ce045f" ] } } } ``` --- ## Goodware Analysis API (tca-0105) — Spectra Intelligence # File analysis (goodware) (TCA-0105) This service provides sample hashes, trust factor, relationships, size, and sources for goodware samples only. If a malicious hash is queried, a 404 (Not Found) HTTP response will be returned. The service supports single or bulk queries against the ReversingLabs file reputation database. The exact differences between the TCA-0104 - File Analysis and TCA-0105 - File Analysis (Non-Malicious) services are outlined in the table below. | Field | TCA-0104 | TCA-0105 | |------------------------|----------|---------------------| | hashes | Yes | Yes, except imphash | | sample_size | Yes | Yes | | trust_factor | No | Yes | | AV scanner information | Yes | No | | sources | Yes | Yes | | relationships | Yes | Yes | | [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) analysis | Yes | No | | dynamic_analysis | Yes | No | **This API is rate limited to 100 requests per second.** ## General Info about Requests/Responses - All requests support the **format** query field which supports two options: **xml** or **json**. - Default response format is **xml**, except for bulk queries, where default format is the same as the **post_format** - All bulk query rules will accept POST payload of the same format (described below). - The number of hashes in a bulk request must not be larger than a hundred (100). - POST requests must set the **Content-Type: application/octet-stream** field in the HTTP header ## Single File Analysis This query returns a response containing all public knowledge about the given sample identified by hash. The response will contain information such as sample sources, AV scanning information etc. ### Request ``` GET /api/databrowser/rldata/goodware/query/{hash_type}/{hash_value} ``` - **hash_type** accepts these options: *md5*, *sha1*, *sha256* - **hash_value** must be a valid hash defined by the **hash_type** parameter ### Response ``` json { "rl": { "sample": { "sha1": "string", "crc32": "string", "md5": "string", "sha256": "string", "sha384": "string", "sha512": "string", "pe_sha1": "string", "pe_sha256": "string", "ssdeep": "string", "tlsh": "string", "sample_size": 0, "password_uploaded": "bool", "trust_factor": 0, "relationships": { "container_sample_sha1": [ "string" ], "parent_sample_sha1": [ "string" ], "child_sample_sha1": [ "string" ], "more_child_samples_available": "bool" }, "sources": { "entries": [ { "record_time": "string", "tag": "string", "properties": [], "domain": { "name": "string" } } ] } } } } ``` - `sha1` - SHA1 value of the requested sample. This field is mandatory and can be used as a primary key. - `hashes` - List of hashes computed for the requested sample, e.g. MD5, SHA256, SHA384, SHA512, Authenticode hashes (PE_SHA1, PE_SHA256), SSDEEP... - `tlsh` - A hash value which can be used for file similarity comparisons, helping to identify similar, nearly identical, or modified files. TLSH hash is not calculated if `SSDEEP` is enabled and the file size is either smaller than its minimum size (1024 bytes) or larger than its maximum size (734003200 bytes). - `password_uploaded` - Indicates that password was uploaded for unpacking this sample. If password wasn't uploaded, this field is omitted. - `relationships` - Parent, container and child sample lists. - `sources` - A sequence of source items indicating where the sample came from. These can be different domains, specific uploaders, etc. One sample can have multiple sources. The service returns a list of 10 oldest sources, sorted by timestamp in descending order. Response code 404 is returned with a message "Sample is not non-malicious" when the requested hash isn't found in the database, or is not goodware. ---------------------------------------------------------------------- `rl.sample.relationships` - `container_sample_sha1` - List of container hashes. Container is the top-level archive/sample that was uploaded to the system and also contains the requested sample. The response will contain up to 5 container sample hashes, sorted by MD5 hash. - `parent_sample_sha1` - List of samples that directly contain the requested sample. The requested hash is a child to the hashes in this list. The list of children has been acquired by file extraction. The response will contain up to 5 parent sample hashes, sorted by MD5 hash. - `child_sample_sha1` - List of samples the requested sample contains. - `more_child_samples_available` - Indicator that more than 10 child samples are available. ## Bulk File Analysis This query retrieves the same data as the single query, but for multiple hashes within a single response. It is more network-efficient compared to several consecutive single queries. ### Request ``` POST /api/databrowser/rldata/goodware/bulk_query/{post_format} ``` - **post_format** is a required parameter that defines the POST payload format. Supported formats are `xml` and `json` The following definitions are valid for both formats: - **hash_type** value must be one of the following options: `md5`, `sha1`, `sha256` - **hash_value** must be a valid hash defined by **hash_type** #### Request body ``` json { "rl": { "query": { "hash_type": "string", "hashes": [ "string", "string", "string" ] } } } ``` ### Response ``` json { "rl": { "entries": [ {} ], "invalid_hashes": [ "string" ], "unknown_hashes": [ "string" ] } } ``` - item in `entries` are equivalent to the `rl.sample` element from the single query - `invalid_hashes`: A list of ill-formatted hashes provided in request - `unknown_hashes`: A list of hashes from the request that were not found in the database or are not goodware ## Examples ### Format Query Field - changing the response format ``` /api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=json /api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b?format=xml ``` ### Single query - changing the hash type ``` /api/databrowser/rldata/goodware/query/sha1/a25b6db2d363eaa31de348399aedc5651280b52b /api/databrowser/rldata/goodware/query/sha256/10dbb2b27208c5566d326b47950657bf6b3c9a59e302598a128ad7125d5fb4fd ``` ### Bulk query - changing the POST format ``` /api/databrowser/rldata/goodware/bulk_query/xml /api/databrowser/rldata/goodware/bulk_query/json ``` ### Bulk query - JSON POST format ``` /api/databrowser/rldata/goodware/bulk_query/json ``` ``` json { "rl": { "query": { "hash_type": "md5", "hashes": [ "4bb64c06b1a72539e6d3476891daf17b", "6353de8f339b7dcc6b25356f5fbffa4e", "59cb087c4c3d251474ded9e156964d5d", "6c2eb9d1a094d362bcc7631f2551f5a4", "a82c781ce0f43d06c28fe5fc8ebb1ca9", "920f5ba4d08f251541c5419ea5fb3fb3" ] } } } ``` ``` json { "rl": { "query": { "hash_type": "sha1", "hashes": [ "13e40f38427a55952359bfc5f52b5841ce1b46ba", "831fc2b9075b0a490adf15d2c5452e01e6feaa17", "42b05278a6f2ee006072af8830c103eab2ce045f" ] } } } ``` ``` json { "rl": { "query": { "hashes": [ "0001f757f6b9523707462066100aa543", "000202ed4a0fb4c95e68824bc7777a78", "00026f63fd5a2600b73a866d7ef08b6f" ], "hash_type": "md5" } } } ``` --- ## Spectra Intelligence Malware Hunting API — YARA, Search & IoC The Malware Hunting APIs enable threat researchers to search for samples, find similar files, create custom detection rules, and track malware families across the Spectra Intelligence repository. ## Common Use Cases ### Search for samples - **[Advanced search (TCA-0320)](tca-0320.md)** - Build complex queries using keywords and operators to filter samples by classification, file type, threat name, and more. - **[Indicators of Compromise (TCA-0330)](tca-0330.md)** - Retrieve structured IoC data for samples and URLs with filtering by classification, malware family, threat actor, and vertical. ### Find similar files - **[Functionally similar files (TCA-0301)](tca-0301.md)** - Find files with similar code structure using ReversingLabs Hashing Algorithm (RHA1). - **[Functionally similar files (analytics) (TCA-0321)](tca-0321.md)** - Get statistics on how many malicious, suspicious, and known files are functionally similar to a sample. - **[Imphash similarity (TCA-0302)](tca-0302.md)** - Find Windows PE files sharing the same import hash. ### Create custom detection rules - **[YARA hunting (TCA-0303)](tca-0303.md)** - Upload YARA rules to match against new samples entering the system. - **[YARA retro hunting (TCA-0319)](tca-0319.md)** - Run YARA rules against the last 90 days of stored samples. ### Track malware families These APIs provide statistics and search capabilities for the [Targeted and industry-specific file indicator feeds (TCF-0401-0406)](/docs/SpectraIntelligence/Feed/IndustryIndicators/tcf-0401-0406.md). - **[Vertical feeds statistics (TCA-0307-0311, 0317)](tca-0307-0311_0317.md)** - Get weekly statistics on malware families by industry category. - **[Vertical feeds search (TCA-0312-0316, 0318)](tca-0312-0316_0318.md)** - Search for new malware hashes by family name within industry-specific feeds. ## All Malware Hunting APIs --- ## Functionally Similar Files API (tca-0301) — Spectra Intelligence The [RHA (ReversingLabs Hashing Algorithm)](https://www.reversinglabs.com/technology/reversinglabs-hash-algorithm) identifies code similarity between unknown samples and previously seen malware samples. Files have the same RHA1 hash when they are functionally similar. This API provides a list of SHA1 hashes of files that are functionally similar to the provided file (SHA1 hash) at the selected precision level (grouped by their RHA1 hash). Precision level represents the degree to which a file is functionally similar to another file. The following precision levels are supported - **25% and 50% for PE** and **25% for MachO and ELF executable files**. A higher precision level will match fewer files, but the files will have more functional similarity. The 'extended' option provides SHA1 hashes and related sample reputation information in the response, along with some other properties such as sample size, sample type and download availability. By using this API, the user can easily get a list of all functionally similar files for the provided file (SHA1 hash) found in the Spectra Intelligence cloud, along with their reputation information. The user can also filter out results by sample's classification. For example, only malicious files functionally similar to the provided one. ## General Info about Requests/Responses - This query returns a list containing all the SHA1 hashes for the requested SHA1 and precision level (grouped by the RHA1 hash) - All requests support the **format** query field, which supports two options: **xml** and **json** - The default response format is **XML** ## Group By RHA1 Single Query This query returns a list containing all SHA1 hashes of functionally similar samples for the requested SHA1 sample hash and RHA1 precision level. If the extended option is selected, each SHA1 hash in the list will be expanded with additional metadata: - reputation information - 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); ### Request ``` GET /api/group_by_rha1/v1/query/{rha1_type}/{hash_value}[/{next_page_sha1}]?[format=xml|json]&[limit={1-1000}]&[extended=true|false]&[classification=KNOWN|MALICIOUS|SUSPICIOUS|UNKNOWN] ``` #### Path parameters - `rha1_type` - A measure of RHA1 precision level. It 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: **pe01**, **elf01**, **machO01** - 25% precision level; **pe02** - 50% precision level - Required - `hash_value` - Must be a valid SHA1 file hash - Required - `next_page_sha1` - An optional parameter used for pagination. It is the SHA1 hash of the first sample on the next page. - Optional #### Query parameters - `format` - Specifies the response format, with possible values being **xml** (default) and **json** - Optional - `limit` - The maximum number of sample SHA1 hashes to return. This value has to be an integer in the range from 1 and 1000 (1000 is the default value) - Optional - `extended` - An optional parameter. Supported values are true - extended, and false - non-extended data set (default) - Optional - `classification` - If this parameter is provided in the request, the query will return a filtered list of samples that match the requested classification. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN - Optional ### Response - The query will return a list of `limit` samples. If the `limit` parameter is not provided in the request, 1000 records will be returned by default. - Fields in the response depend on the selected data set. If the `extended` parameter is not set to **true**, only the list of sample SHA1 hashes will be returned. - If the requested hash doesn't exist in the database records, the server will respond with the status response code 404 and the message **"Requested data was not found"** ``` json { "rl": { "group_by_rha1": { "query_sha1": "string", "rha1_type": "string", "sha1_list": [] } } } ``` - `query_sha1` - Requested SHA1 - `rha1_type` - Requested RHA1 type - `next_page_sha1` - First SHA1 on the next page. This hash value can be used as the next_page parameter in the next request to retrieve the next page of results - `sha1_list` - A list of hashes of functionally similar files ----------------------------------------------------------------------- `rl.group_by_rha1.sha1_list[]` ```json { "sha1": "string", "sha256": "string", "md5": "string", "classification": "string", "sample_type": "string", "sample_size": 0, "sample_available": 0, "trust_factor": 0, "threat_level": 0, "first_seen": 0, "last_seen": 0 } ``` - `sha1` - SHA1 - `sha256` - SHA256 - `md5` - MD5 - `first_seen` (optional) - time when the sample was first seen in the ReversingLabs system (UTC) - `last_seen` (optional) - time when the sample last received impactful changes to its analysis or classification data (UTC) - `sample_type` - sample type - `sample_size` - sample size - `sample_available` - sample download availability status - `classification` - sample's classification - `platform` (optional) - platform targeted by the malware - `subplatform` (optional) - subplatform targeted by the malware - `threat_name` (optional) - threat name for malicious samples - `malware_type` (optional) - malware type for malicious samples - `malware_family` (optional) - malware family for malicious samples - `threat_level` (optional) - threat level of the sample - `trust_factor` (optional) - trust factor of the sample ## Examples ### Format query field These examples request different response formats: ``` /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?format=json /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?format=xml ``` ### Extended optional parameter used These examples use different extended parameters: ``` /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?extended=true /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?extended=false ``` ### Limit query field These examples use different query response limits: ``` /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?limit=1 /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f?limit=100 ``` ### Different precision levels (RHA1 type) These examples request different rha1_type precision levels: ``` /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f /api/group_by_rha1/v1/query/pe02/1b85cbfa30e181c505ba15211db33247c1f8a63f /api/group_by_rha1/v1/query/elf01/8983043176164b960e10b34307f52e88db894b71 /api/group_by_rha1/v1/query/macho01/f1c2712a3881ca795b5eadf65077788198522362 ``` ### next_page_sha1 query field These examples use the next page parameter: ``` /api/group_by_rha1/v1/query/pe01/1b85cbfa30e181c505ba15211db33247c1f8a63f/cd3710af6638b99666a19b4f098b8788723397ab /api/group_by_rha1/v1/query/pe02/1b85cbfa30e181c505ba15211db33247c1f8a63f/cd3710af6638b99666a19b4f098b8788723397ab ``` --- ## Imphash Similarity API (tca-0302) — Spectra Intelligence Imphash Index provides a list of all available SHA1 hashes for files sharing the same import hash (imphash). An imphash is a hash calculated from a string which contains the libraries imported by a Windows Portable Executable (PE) file. ## General Info about Requests/Responses - All requests support the format query field which supports two options: **xml** or **json** - The default response format is xml ## ImpHash Index Single Query This query returns a response containing SHA1 hashes for the requested imphash value. The response can contain a maximum of 1000 records per page. If more than 1000 records match the requested criteria, the next page of records can be retrieved by providing the SHA1 hash returned in the `next_page_sha1` response field as the `next_page_sha1` parameter of the next request. ### Request ``` GET /api/imphash_index/v1/query/{hash_value}[/next_page_sha1/{next_page_sha1}][?format=xml|json] ``` #### Path parameters - `hash_value` - Must be a valid ImpHash hash - Required - `next_page_sha1` - Optional parameter used for pagination. It is the SHA1 hash of the first sample on the next page. - Optional #### Query parameters - `format` - Specifies the response format. Supported values: **xml** (default), **json** - Optional ### Response Response code 404 is returned with data: *Sample not found* when the hash is not found in the database records. ``` json { "rl": { "imphash_index": { "next_page_sha1": "string", "query_imphash": "string", "sha1_list": [ "string" ] } } } ``` `rl.imphash_index` - `query_imphash` - Imphash value from the query - `next_page_sha1` - First SHA1 on the next page - `sha1_list` - List of SHA1 hashes grouped by RHA1 for given imphash ### Examples #### Format query field Here the format for query response is varying: ``` /api/imphash_index/v1/query/0931e97555ac33eb10aa9539fe890070?format=json /api/imphash_index/v1/query/0931e97555ac33eb10aa9539fe890070?format=xml ``` #### next_page_sha1 query field ``` /api/imphash_index/v1/query/0931e97555ac33eb10aa9539fe890070/next_page_sha1/dccc8cd495be5729742d0a7b75188d2b0f33429a ``` ## ImpHash Index Single Sample Query This query returns a response containing SHA1 hashes for the requested sample SHA1 value. The response can contain a maximum of 1000 records per page. If more than 1000 records match the requested criteria, the next page of records can be retrieved by providing the SHA1 hash returned in the `next_page` response field as the `next_page` parameter of the next request. ### Request ``` GET /api/imphash_index/v1/query/sample/{sha1}[/page/{page}][?format=xml|json] ``` #### Path parameters - `sha1` - Must be a valid sample hash - Required - `page` - Optional parameter used for pagination. It is the SHA1 hash of the first sample on the next page. - Optional #### Query parameters - `format` - Specifies the response format. Supported values: **xml** (default), **json** - Optional ### Response Response code 404 is returned with data: *Sample not found* when the hash is not found in the database records. ``` json { "rl": { "imphash_index": { "next_page": "string", "query_hash": "string", "list": [ "string" ] } } } ``` `rl.imphash_index` - `query_hash` - Sample SHA1 hash value from the query - `next_page` - First SHA1 on the next page - `list` - List of SHA1 hashes grouped by RHA1 for given sample hash ## Examples ### next_page sample query field ``` /api/imphash_index/v1/query/sample/003748c030bb2cb5954fdaf0368c8617cf04b3df/page/dccc8cd495be5729742d0a7b75188d2b0f33429a ``` --- ## YARA Hunting API (tca-0303) — Spectra Intelligence The ReversingLabs YARA Hunting service enables users to create custom YARA rules containing textual or binary patterns, and upload them to the service to obtain matches using the APIs described in this document. When a sample matches the pattern found in a YARA rule, it receives the classification defined by that rule. YARA rules can be grouped into rulesets - collections of one or more rules that are defined inside one YARA code text. Rules inside a single ruleset are allowed to be interdependent; i.e., one rule can reference another (see the ["Referencing other rules"](https://yara.readthedocs.io/en/v3.7.0/writingrules.html#referencing-other-rules) section in the YARA documentation). For users who need to create fine-grained, complex rulesets, YARA provides modules as a way of extending the default set of features. **The ReversingLabs YARA Hunting Service supports the following YARA modules: PE, ELF, Dex, Macho, String, Math, Hash, Time, and Dotnet.** The *Ruleset Administration API* is used to administer one's collection of YARA rulesets. A RESTful interface provides operations to add, delete, and query individual rulesets. The *Matches Feed API* is used to obtain generated matches. YARA rulesets do not become active in the system immediately upon upload/creation. All user-submitted rulesets go through a validation phase where they are tested for correctness and efficacy. Note that a ruleset can be declared invalid even if it is syntactically correct. One reason for validation failure could be that a ruleset is too broad - it matches a disproportionately large number of sample files and would generate an inordinate amount of matches. The YARA Hunting service scans/matches files of up to 200 MB in size. ## Ruleset Administration API ### Create a ruleset This query tries to create a new ruleset with content given inside the POST request. The ruleset name serves as a unique identifier for the ruleset. Uploaded YARA text is treated as a collection of YARA rules, and is subject to ruleset validation procedures. #### Request ``` POST /api/yara/admin/v1/ruleset ``` #### Headers `Content-Type: application/json` #### Request body ```json { "ruleset_name": "string", "text": "string", "sample_available": true } ``` - `ruleset_name` - String, containing the ruleset name, between 3 and 48 characters long and conforming to the following regular expression: `^[a-z,A-Z,0-9,_-]*$` - `text` - UTF-8 encoded string containing YARA rules. YARA rules should be *stringified*, for example using the `json.dumps()` method or other similar tool. To properly escape the string, add a backslash (`\`) before each quotation mark (`"`) and turn each newline into an escaped character (`\n`). - `sample_available` - If set to `true`, the [Matches Feed API](#matches-feed-api) will return only samples that are available for download to the user. - If set to `false`, the Matches Feed API will return only samples that are not available for download to the user. - If the parameter is not set in the request, the Matches Feed API will return all samples, regardless of their download availability status. #### Response ```json { "ruleset_name": "string", "ruleset_sha1": "string", "sample_available": true } ``` - `ruleset_name` - string specified by the user in the request - `ruleset_sha1` - hex-encoded string representing the SHA1 digest of the submitted ruleset text - `sample_available` - this field shows sample download availability status. If this parameter was specified in the POST request body by the user, filtering will be applied and the response will only contain samples that are either available (`true`) or not available (`false`) for download ### Delete a ruleset This query initiates the deletion procedure of an existing ruleset. #### Request ``` DELETE /api/yara/admin/v1/ruleset/{ruleset_name} ``` ##### Path parameters - `ruleset_name` - name of the existing ruleset (specified in the creation request) ### Get ruleset information #### Request ``` GET /api/yara/admin/v1/ruleset/{ruleset_name} ``` ##### Path parameters - `ruleset_name` - name of the existing ruleset (specified in the creation request) #### Response ```json { "ruleset_name": "string", "valid": true, "approved": true } ``` - `ruleset_name` - string specified by the user in the request - `valid` - three possible values: - `null` - ruleset validation is still pending, and it hasn't yet been deployed - `true` - ruleset has undergone the validation procedure, has been declared valid and is either deployed or it will be deployed upon approval - `false` - ruleset has undergone the validation procedure, has been declared invalid and will not be deployed - `approved` - three possible values: - `null` - ruleset approval is still pending, and it hasn't yet been deployed - `true` - ruleset has been reviewed and approved by an administrator, and is either deployed or it will be deployed in the near future - `false` - ruleset has been reviewed by the administrator, has been rejected and will not be deployed ### Get ruleset text This query fetches the ruleset content. #### Request ``` GET /api/yara/admin/v1/ruleset/{ruleset_name}/text ``` ##### Path parameters - `ruleset_name` - name of the existing ruleset (specified in the creation request) #### Response ```json { "text": "string" } ``` ### Get all rulesets This query lists the user's ruleset collection. #### Request ``` GET /api/yara/admin/v1/ruleset ``` #### Response ```json [ { "ruleset_name": "string", "valid": true, "approved": true } ] ``` - `ruleset_name` - string, specified by the user in the creation request - `valid` - three possible values: - `null` - ruleset validation is still pending, and it hasn't yet been deployed - `true` - ruleset has undergone the validation procedure, has been declared valid and is either deployed or it will be deployed upon approval - `false` - ruleset has undergone the validation procedure, has been declared invalid and will not be deployed - `approved` - three possible values: - `null` - ruleset approval is still pending, and it hasn't yet been deployed - `true` - ruleset has been reviewed and approved by an administrator, and is either deployed or it will be deployed in the near future - `false` - ruleset has been reviewed by the administrator, has been rejected and will not be deployed If the authenticated user does not have any uploaded rulesets, this query will return an empty list. The HTTP response code "200 OK" means that all rulesets were successfully fetched, even if the user doesn't have any uploaded rulesets. ## Matches Feed API ### Fetch matches This query returns a set of YARA ruleset matches in the specified time range for a particular user. The feed stores records for the last 365 days. #### Request ``` GET /api/feed/yara/v1/query/{time_format}/{time_value}[?format={response_format}&extended={boolean}] ``` ##### Path parameters - `time_format` - Format in which the time value will be specified. Possible values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the YYYY-MM-DDThh:mm:ss format - Required - `time_value` - Time range start - Required ##### Query parameters - `format` - Specifies the response format. Supported values: **xml** (default), **json** - Optional - `extended` - When set to `true`, the response entries include additional enrichment fields: - `md5` - MD5 hash of the file - `sha256` - SHA256 hash of the file - `first_seen` - timestamp when the sample was first seen - Optional (default: `false`) The time range is defined as the time period from the time specified by the time_value parameter up to the time of the request being made. If the requested timestamp is not within the last 365 days, the service will respond with the status code "400 Bad Request". The latest time value is 10 seconds before the current time. Specifying a time value outside this period will yield a "400 Bad Request" status code. 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. The response data provides the latest timestamp until which events are included. To fetch the next recordset, the timestamp from the response field *last_timestamp* should be increased by 1 and used in the subsequent query as the *time_value* parameter. The maximum time span for a single request is limited to 24h. All time values are in UTC, independent of the input format. **Example Requests** Get all YARA matches from 2026-01-20 00:00:00 as timestamp: ``` /api/feed/yara/v1/query/timestamp/1768953600 ``` Get all the YARA matches from 2026-01-20 00:00:00 UTC as date string: ``` /api/feed/yara/v1/query/utc/2026-01-20T00:00:00 ``` Fetch all YARA matches from 2026-01-20 00:00:00 in the JSON format: ``` /api/feed/yara/v1/query/timestamp/1768953600?format=json ``` Fetch all YARA matches from 2026-01-20 00:00:00 in the XML format: ``` /api/feed/yara/v1/query/timestamp/1768953600?format=xml ``` Fetch all YARA matches from 2026-01-20 00:00:00 with extended metadata (MD5, SHA256, first_seen): ``` /api/feed/yara/v1/query/timestamp/1768953600?format=json&extended=true ``` #### Response A query response will contain zero or more match entries that are found within the specified time period. A single entry represents a match produced by a specific YARA ruleset against a particular sample file. The entry contains information about the sample file (SHA1, file size) as well as information on one or more rules from the ruleset that matched the sample file (rule name, tags and meta fields and their values). Additional data propagated from YARA engine is a list of matching strings contained in matched_data objects. The matched_data object is a 3 dimensional vector with the form `(int match_offset, base64_string string_identifier, base64_string matched_string)`. **Note: Matched data is returned only if it exists and the sample is either public or was previously uploaded by the requesting user.** The `sample_available` field indicates whether a sample can be downloaded using the Spectra Intelligence download API: - `sample_available=true` - The sample is public and downloadable. If matched data exists, it is included in the response. - `sample_available=false` - The sample is not publicly available. Matched data visibility depends on sample ownership: - If the sample was uploaded by the requesting user, matched data is included in the response (when available). - If the sample was uploaded by another user and is private, matched data is hidden from the response. If a sample was matched by several rulesets, each will produce its own entry. **JSON Response Format** ``` json { "rl": { "feed": { "entries": [], "last_timestamp": 0, "name": "string", "time_range": {} } } } ``` ----------------------------------------------------------------------- **Entry Format** `rl.feed.entries[]` ```json { "sha1": "string", "file_type": "string", "timestamp": 0, "ruleset_name": "string", "rule": [ { "meta": [ [ "string", "string" ] ], "identifier": "string", "tag": [ "string" ], "matched_data": [ { "string_identifier": "string", "match_offset": 0, "matched_string": "string" } ] } ], "sample_available": true, // Extended fields (available when extended=true) "md5": "string", "sha256": "string", "first_seen": "string" } ``` --- ## Vertical Feeds Statistics API (tca-0307–0311, tca-0317) — Spectra Intelligence ReversingLabs Malware Detection Family Feed V2 provides information about new malware samples detected in the Spectra Intelligence system, filtered by category (industry). Categories and API codes correspond to ReversingLabs Targeted and Industry-Specific File Indicator Feeds (e.g., Financial, Retail, Exploits...). To make sense of that data, ReversingLabs is creating weekly statistics and providing them via this API (Statistics API). | Code | Feed Name | |----------|----------------------------------------------| | TCA-0307 | APT (Advanced Persistent Threats) Statistics | | TCA-0308 | Financial Services Malware Statistics | | TCA-0309 | Retail Sector Malware Statistics | | TCA-0310 | Ransomware Statistics | | TCA-0311 | CVE Exploits Statistics | | TCA-0317 | Malware Configuration Statistics | **This API is rate limited to 1 request per second.** ## Feed Statistics Query The following endpoints are supported: **Fetch statistics for last week(s) - newly added** This query returns a list of family names and the times when they were added to a particular category. The data is retrieved for up to last 30 weeks, or for all time since the data collecting started. ### Request ``` GET /api/feed/malware/detection/family/v2/statistics/category/{category}/first_seen?[format=xml|json]&[all_time|weeks=0-30] ``` **Fetch statistics for last week(s) - unique counts** This query returns the number of how many unique new samples were added to the statistics for each malware family in a given category. The data is retrieved for up to last 30 weeks, or for all time since the data collecting started. ``` GET /api/feed/malware/detection/family/v2/statistics/category/{category}/counts?[format=xml|json]&[all_time|weeks=0-30] ``` **Fetch statistics for last week(s) - top list** This query returns family names together with their respective counts for the top 20 families in the requested number of weeks. Data for up to 30 latest weeks is available. It is also possible to request all-time top 20 families for the requested category. ``` GET /api/feed/malware/detection/family/v2/statistics/category/{category}/top_list?[format=xml|json]&[all_time|weeks=0-30] ``` ----------------------------------------------------------------------- The request and response formats are the same for all endpoints: ### Request #### Path parameters - `category` - Accepts one of the following: financial, retail, ransomware, apt, exploit, configuration - required - Categories correspond to ReversingLabs Targeted and Industry-Specific File Indicator Feeds. If there is no access to a category, or if a category does not exist, the response will be 403 Forbidden. #### Query parameters - `weeks` - The number of weeks for which the data will be retrieved. The value can be a number between 0 and 30. - When the parameter is not included in the request, defaults to 0 (which returns equal results as all_time). - If an integer from 1 to 30 is provided, then it will return the data for that many latest weeks. - optional - Items are included in the statistics based on the date when they were added to a particular category. - 30 is the maximum number of weeks for which it is guaranteed that the data is preserved. - The statistics will return either a list with data for each week (1-30), or a list with a single item stating that it represents all_time data. - `format` - Allows choosing the response format. Accepts xml or json. When the parameter is not included in the request, defaults to xml - optional - `all_time` - If this parameter is provided instead of weeks, returns statistics for all data since collecting started. - optional ### Response Response example when `weeks=0`, or when using the `all_time` parameter ``` json { "rl": { "feed": { "name": "string", "entries": [] } } } ``` ----------------------------------------------------------------------- `rl.feed.entries[]` ```json { "all_time": true, "category": "string", "entries": [] } ``` - `all_time` - Indicates whether the response includes statistics for all time. Returns true if the optional all_time parameter was included in the request - `week` - Indicates the week number for which statistics are returned. It is not included in the response if the request contained the all_time parameter. - The format is ISO week number YYYY-Ww. For example, week 30 in 2018 would be “2018-W30” - `category` - Indicates the category for which statistics are returned ----------------------------------------------------------------------- `rl.feed.entries[].entries[]` ```json { "family_name": "string", "first_seen": "string", "scanner_coverage": { "entries": [ { "percent": 0.0, "name": "string" } ] } } ``` - `family_name` - Malware family name of the detected malware - `count` - The number of unique occurrences of this family name in a given category - `first_seen` - Date and time when the item was first seen (UTC) - `scanner_coverage` - Returned only for the exploit category. - For every item in the statistics, includes percent and name fields. Names correspond to antivirus scanners which were used to scan the sample. Percentage indicates how confident a specific scanner is that the particular sample belongs to an exploit family. ## Examples ### Request Examples **Fetching the latest counts for apt and exploit categories in JSON format:** ``` /api/feed/malware/detection/family/v2/statistics/category/apt/counts?format=json&weeks=1 /api/feed/malware/detection/family/v2/statistics/category/exploit/counts?format=json&weeks=1 ``` **Fetching the all-time top list for apt, exploit and financial categories in XML format:** ``` /api/feed/malware/detection/family/v2/statistics/category/apt/top_list /api/feed/malware/detection/family/v2/statistics/category/exploit/top_list?format=xml&all_time /api/feed/malware/detection/family/v2/statistics/category/financial/top_list?format=xml&weeks=0 ``` **Fetching families added in the last 3 weeks for retail and financial categories in JSON format:** ``` /api/feed/malware/detection/family/v2/statistics/category/retail/first_seen?format=json&weeks=3 /api/feed/malware/detection/family/v2/statistics/category/financial/first_seen?format=json&weeks=3 ``` ### Response Examples ``` json { "rl": { "feed": { "name": "Verticals Statistics Top List", "entries": [ { "all_time": true, "category": "apt", "entries": [ { "count": 1229365, "family_name": "FAMILY_NAME" }, { "count": 786435, "family_name": "FAMILY_NAME" }, { "count": 219329, "family_name": "FAMILY_NAME" }, { "count": 115916, "family_name": "FAMILY_NAME" }, { "count": 76910, "family_name": "FAMILY_NAME" }, { "count": 10765, "family_name": "FAMILY_NAME" }, { "count": 10386, "family_name": "FAMILY_NAME" }, { "count": 4957, "family_name": "FAMILY_NAME" }, { "count": 3089, "family_name": "FAMILY_NAME" }, { "count": 2847, "family_name": "FAMILY_NAME" }, { "count": 2300, "family_name": "FAMILY_NAME" }, { "count": 1109, "family_name": "FAMILY_NAME" }, { "count": 989, "family_name": "FAMILY_NAME" }, { "count": 755, "family_name": "FAMILY_NAME" }, { "count": 608, "family_name": "FAMILY_NAME" }, { "count": 603, "family_name": "FAMILY_NAME" }, { "count": 445, "family_name": "FAMILY_NAME" }, { "count": 423, "family_name": "FAMILY_NAME" }, { "count": 315, "family_name": "FAMILY_NAME" }, { "count": 268, "family_name": "FAMILY_NAME" } ] } ] } } } ``` ``` json { "rl": { "feed": { "name": "Verticals Statistics Top List", "entries": [ { "category": "exploit", "all_time": true, "entries": [ { "count": 132278, "family_name": "CVE-2008-2992", "scanner_coverage": { "entries": [ { "percent": 95.013291846660422, "name": "SCANNER_NAME" }, { "percent": 97.528924870857622, "name": "SCANNER_NAME" }, { "percent": 95.035948403467955, "name": "SCANNER_NAME" }, { "percent": 94.961936984563337, "name": "SCANNER_NAME" } ] } } ] } ] } } } ``` ``` json { "rl": { "feed": { "name": "Verticals Statistics First Seen", "entries": [ { "week": "2017-W20", "category": "exploit", "entries": [ { "family_name": "FAMILY_NAME", "first_seen": "2017-05-15 00:58:12" }, { "family_name": "FAMILY_NAME", "first_seen": "2017-05-15 14:13:35" }, { "family_name": "FAMILY_NAME", "first_seen": "2017-05-15 20:21:40" } ] }, { "week": "2017-W21", "category": "exploit", "entries": [ { "family_name": "FAMILY_NAME", "first_seen": "2017-05-25 20:40:07" }, { "family_name": "FAMILY_NAME", "first_seen": "2017-05-23 22:03:20" }, { "family_name": "FAMILY_NAME", "first_seen": "2017-05-25 16:23:07" } ] } ] } } } ``` --- ## Vertical Feeds Search API (tca-0312–0316, tca-0318) — Spectra Intelligence This service can be used to retrieve information about new malware samples from ReversingLabs Targeted and Industry-Specific File Indicator Feeds by searching for malware family names. 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 list of malware families for each feed is continually updated by ReversingLabs analysts. An excerpt from the list is available in the Sample Malware Family Names section. For the complete, accurate, and up-to-date list of all malware family names in Targeted and Industry-Specific File Indicator Feeds, it is recommended to obtain access to Statistics APIs (TCA 0307-0311, 0317) Using the API described in this document, it is possible to search for the following information: - new malware hashes belonging to an APT tool - new malware hashes belonging to a banking Trojan or other malware family targeting the financial sector - new malware hashes belonging to a POS malware or other malware family targeting the retail sector - new malware hashes belonging to a ransomware family - new exploit hashes related to a CVE identifier - new malware hashes that contain embedded configuration data Apart from SHA1 hashes, results include information about other file properties: MD5 and SHA256 hashes, file size, file type, download availability of the samples, first seen, last seen (UTC), container hash and time when the file was added into the feed. To make sense of that data, ReversingLabs is creating weekly statistics and providing them via this API (Statistics API). ## Example Malware Family Names The following malware family names can be used to test the API described in this document. For the complete, accurate, and up-to-date list of all malware family names in Targeted and Industry-Specific File Indicator Feeds, it is recommended to obtain access to Statistics APIs (TCA 0307-0311, 0317). | Code | Feed Name | Malware Family Names | | -------- | --------------------------------- | ---------------------------------------------------------- | | TCA-0312 | APT (Advanced Persistent Threats) | CosmicDuke, CozyBear, Stuxnet, Hellsing | | TCA-0313 | Financial Services Malware | Alice, Dorkbot, Ramnit, Ripper | | TCA-0314 | Retail Sector Malware | AbaddonPOS, ChewBacca, Katrina, Poseidon | | TCA-0315 | Ransomware | BitCrypt, Nanolocker, NotPetya, WannaCry | | TCA-0316 | CVE Exploits | CVE-2008-4844, CVE-2014-0495, CVE-2017-0147, CVE-2017-8291 | | TCA-0318 | Malware Configuration | DarkComet, PoisonIvy, XtremeRAT, CyberGate | ## Family Name Index Query The query allows searching for new malware hashes from ReversingLabs Targeted and Industry-Specific File Indicator Feeds by malware family name. Note that the malware family name must match at least one family name from the feeds in order to get the desired results. In other words, if the queried family name is not found in any of the feeds, no detections will be fetched. Since the list of malware family names in each feed changes daily, it is recommended to obtain access to Vertical Feeds Statistics APIs (TCA 0307-0311, 0317) to get the complete and accurate information. For the purposes of testing this query, refer to the list of Sample Malware Family Names. ### Fetch detections since specified time This query returns a recordset of entries from one of Targeted and Industry-Specific File Indicator Feeds in the specified time range for the given malware family name, provided that the family name is found in one of the feeds. Entries are included in the response based on the time when they were added to a particular feed. The time value provided in the query defines the starting point of the time range. If an entry has been added to one of the feeds in that time range, it is included in the response. #### Request ``` GET /api/feed/malware/detection/family/v2/index/family_name/search/{family_name}/from/{time_format}/{time_value}?[format=xml|json]&[count=(1-1000)] ``` ##### Path parameters - `family_name` - Case-sensitive parameter; accepts a malware family name or a CVE identifier - Required - `time_format` - 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 - Required - `time_value` - Accepts values formatted according to the format set in the `time_format` parameter. The latest allowed time value is 60 seconds before the current time. - Required ##### Query parameters - `format` - Specifies the response format. Supported values: **xml** (default), **json** - Optional - `count` - The number of hashes to return in the response. It has to be an integer in the range from 1 to 1000 ( 1 \<= count \<= 1000 ). The default value of the parameter is 100. - Optional The time range is defined as the period between the time specified by the *time_value* parameter and the time when the request is made. The earliest time value that the user can specify is 365 days before the current time. The latest time value is 60 seconds before the current time. Specifying a time value outside of these limits will return the status code **400 Bad Request**. The response can contain up to 1000 results. If the number of samples with the last timestamp included in the response goes above this limit, the results will be cut off. To get the next page of results, provide the `to` value from the previous request as the `timestamp` value of the next request. This will cause some result duplication (specifically, records whose **record_on** value matches the **to** timestamp will reappear on the second page), but it will also return any remaining records with the matching timestamp that didn't fit on the first page. Setting the `count` value too low may result in `from` and `to` timestamps being the same, which will cause a response loop. All time values are in UTC, independent of the input format. ### Fetch the latest detections This query returns a recordset from Targeted and Industry-Specific File Indicator Feeds consisting of the latest entries for the given family name, provided that the family name is found in one of the feeds. #### Request ``` GET /api/feed/malware/detection/family/v2/index/family_name/search/{family_name}/latest?[format=xml|json]&[count=(1-1000)] ``` ##### Path parameters - `family_name` - case-sensitive and accepts a malware family name or a CVE identifier - Required - `count` - Specify how many latest hashes to return in the response. It has to be an integer in the range from 1 to 1000 ( 1 \<= count \<= 1000 ). The default value of the parameter is 100. - Optional ##### Query parameters - `format` - Specifies the response format. Supported values: **xml** (default), **json** - Optional Submitting a GET request to the given URL with no optional request arguments will provide the latest 100 detections for the given family name. The *count* parameter supports all integers between 1 and 1000, including 1 and 1000. Providing *count* with anything other than integers in the given range will result in a "400 Bad Request" response. The feed will return 100 records if the *count* parameter is not provided. Otherwise, it will return the requested number of detections, starting from the most recent record in the data store. The most recent entry value is 60 seconds before the current time. ### Response Format ``` json { "rl": { "feed": { "name": "string", "time_range": { "from": 0, "to": 0 }, "entries": [], "family_name": "string", "categories": [ "string" ] } } } ``` - `family_name` - the requested family name or CVE identifier - `categories` - list of categories this family_name belongs to - `time_range` - Date and time when the item was first seen (UTC) - `time_range \> from` - timestamp from the latest record_on field from entries - `time_range \> to` - time when the request was initiated - `name` - name of the feed - `entries` - Contains a list of entries with fields ----------------------------------------------------------------------- `rl.feed.entries[]` ```json { "record_on": 0, "sha1": "string", "priority": 0, "family_name": "string", "sample_available": true, "container_hash": "string", "sha256": "string", "md5": "string", "sample_size": 0, "sample_type": "string", "first_seen_on": 0, "last_seen_on": 0, "tags": { "actors": [ "string" ] } } ``` - `sha1` - sample SHA1 - `sample_available` - boolean value indicating whether the sample is physically available for download,​ but not if the file is shareable (available for public download). Regardless of this value, use the Sample Download API to attempt a file download. If the Sample Download API returns a 403 error, that indicates that this sample is not available for download, or is private. - `sample_size` - integer value defining the sample size - `priority` - integer value (1-5) describing the importance of the entry for a particular industry (category). The value of 1 indicates the lowest priority, and 5 the highest. Lower values mean that the particular malware family is connected to some actor or other malware families related to the industry; not directly affecting the industry, but relevant to it - `sample_type` - string value describing the sample type (e.g. "Binary/Archive") - `record_on` - time when the record was added to the feed - `family_name` - malware family name - `container_hash` - container SHA1; if this information is the sample itself, then this is identical to SHA1 - `first_seen_on` - time when this hash was first seen in the system (UTC) - `last_seen_on` - time when this hash was last seen in the system (UTC) - `sha256` - sample SHA256, if it exists - `md5` - sample md5, if it exists - `tags` - a dictionary that contains *tag_types* as keys and *tag_list* as the value for each *tag_type* that is found in the configuration for a given detection ## Examples ### Format query field Here the format for query response varies: Fetching the first 100 entries starting from 2017-03-20 00:00:00 GMT till 2016-10-30 23:59:59 GMT for the ChewBacca family name: ``` /api/feed/malware/detection/family/v2/index/family_name/search/ChewBacca/from/timestamp/1489968000 /api/feed/malware/detection/family/v2/index/family_name/search/ChewBacca/from/utc/2017-03-20T00:00:00 ``` Fetching the first 1000 entries starting from 2017-03-20 00:00:00 GMT till 2016-10-30 23:59:59 GMT for the Stuxnet family name ``` /api/feed/malware/detection/family/v2/index/family_name/search/Stuxnet/from/timestamp/1489968000?count=1000 /api/feed/malware/detection/family/v2/index/family_name/search/Stuxnet/from/utc/2017-03-20T00:00:00?count=1000 ``` Fetching the 100 latest entries or entries dating up to the last 30 days for the Ramnit family name ``` /api/feed/malware/detection/family/v2/index/family_name/search/Ramnit/latest ``` Fetching the 10 latest entries or entries dating up to the last 30 days for the CozyBear family name ``` /api/feed/malware/detection/family/v2/index/family_name/search/CozyBear/latest?count=10 ``` Fetching the 10 latest entries or entries dating up to the last 30 days for the NotPetya family name, with requested response in the JSON format ``` /api/feed/malware/detection/family/v2/index/family_name/search/NotPetya/latest?count=10&format=json ``` ### Retrieving the next page in feed The following two examples retrieve the first and second page of results for the ChewBacca family using the timestamp parameter. The first request will search for entries newer than the given timestamp (1490465964) and return 2 entries per page (in practical use, this number should be higher, 2 was chosen as an example): ``` GET /api/feed/malware/detection/family/v2/index/family_name/search/ChewBacca/from/timestamp/1490465964?count=2&format=json ``` #### Response ``` json { "rl": { "feed": { "family_name": "ChewBacca", "entries": [ { "family_name": "ChewBacca", "sha1": "7a6b3(...)e0c35", "record_on": 1490466315, "first_seen_on": 1490465598, "last_seen_on": 1490466240, "sample_type": "PE/Exe", "priority": 5, "sample_size": 1326080, "sample_available": true, "container_hash": "7a6b3(...)e0c35", "sha256": "0d596(...)9b491", "md5": "7ed1cfcf70f2262b14c79ed19ece8bde" }, { "family_name": "ChewBacca", "sha1": "a04cf(...)8c2b5", "record_on": 1490467370, "first_seen_on": 1490466445, "last_seen_on": 1490467320, "sample_type": "PE/Exe", "priority": 5, "sample_size": 1326080, "sample_available": true, "container_hash": "a04cf(...)8c2b5", "sha256": "a37c9(...)f60b8", "md5": "88458d3d784b54097786ee9f2756f405" } ], "name": "Malware Detection Family Feed", "categories": [ "retail" ], "time_range": { "to": 1490467370, "from": 1490465964 } } } } ``` After receiving the response, the timestamp value (**to** timestamp) from the `time_range.to` field can be used for requesting the next page of results. To get the next page of results, provide the `to` value from the previous request as the `timestamp` value of the next request. This will cause some result duplication (specifically, records whose **record_on** value matches the **to** timestamp will reappear on the second page), but it will also return any remaining records with the matching timestamp that didn't fit on the first page. Setting the `count` value too low may result in `from` and `to` timestamps being the same, which will cause a response loop. ``` GET /api/feed/malware/detection/family/v2/index/family_name/search/ChewBacca/from/timestamp/1490466369?count=2&format=json ``` This will return page 2 with two entries: ``` json { "rl": { "feed": { "family_name": "ChewBacca", "entries": [ { "family_name": "ChewBacca", "sha1": "a04cf(...)8c2b5", "record_on": 1490467370, "first_seen_on": 1490466445, "last_seen_on": 1490467320, "sample_type": "PE/Exe", "priority": 5, "sample_size": 1326080, "sample_available": true, "container_hash": "a04cf(...)8c2b5", "sha256": "a37c9(...)f60b8", "md5": "88458d3d784b54097786ee9f2756f405" }, { "family_name": "ChewBacca", "sha1": "96aef904580e435fbdf3b1e22d8cd8dde351b4e6", "record_on": 1490468400, "first_seen_on": 1490376320, "last_seen_on": 1490468340, "sample_type": "PE/Exe", "priority": 5, "sample_size": 1837056, "sample_available": true, "container_hash": "96aef(...)1b4e6", "sha256": "0d9e3e(...)649bd", "md5": "b1898d0e1998ce17aa7e20e328ac5d14" } ], "name": "Malware Detection Family Feed", "categories": [ "retail" ], "time_range": { "to": 1490468400, "from": 1490466369 } } } } ``` --- ## YARA Retro Hunting API (tca-0319) — Spectra Intelligence The ReversingLabs YARA Retro Hunting service enables users to run their own YARA rules and retroactively match them against files from the ReversingLabs sample set. The YARA Retro Hunting sample set is based on the last 90 days of stored samples, excluding samples larger than 200 MB and archives. Samples extracted from archives are not excluded. Note: this service cannot be used without access to the YARA Hunting service (TCA-0303). Users need to upload their YARA rules to the service using the API described in the YARA Hunting service (TCA-0303) documentation. In this document, the term ruleset represents a collection of one or more YARA rules that are defined inside one YARA code text. One ruleset can contain up to 300 rules. Rules inside a single ruleset are allowed to be interdependent; i.e., one rule can reference another (see the [Referencing other rules](https://yara.readthedocs.io/en/v3.7.0/writingrules.html#referencing-other-rules) section in the official YARA documentation). For users who need to create fine-grained, complex rulesets, YARA provides modules as a way of extending the default set of features. **The ReversingLabs YARA Hunting Service supports the following YARA modules: PE, ELF, Dex, Macho, String, Math, Hash, Time, and Dotnet.** The `retro-admin` API allows users to manage their own YARA retro hunts. A RESTful interface provides operations to enable, start, check status, and cancel a particular retro hunt. Retro hunts are referenced by a ruleset name. The `retro-matches` API is used to retrieve retro hunt matches generated for a specific user. **This API is rate limited to 1 request per second.** This service has specific explanations for certain response status codes. See the individual endpoint sections for more information. ## YARA Retro Administration API ### Start Retro Hunt This query starts the retro hunt for the specified ruleset. #### Request ``` POST /api/yara/admin/v1/ruleset/start-retro-hunt ``` #### Request Format ``` Content-Type: application/json { "ruleset_name" : } ``` - `ruleset_name` - String containing the name of a YARA ruleset previously uploaded by the user. The name should be between 3 and 48 characters long, and conform to the following regular expression: ^\[a-z,A-Z,0-9,\_-\]\*\$ #### Response Format ``` Content-Type: application/json { "ruleset_name" : , "ruleset_sha1": } ``` - **ruleset_name** - string specified by the user in the request - **ruleset_sha1** - hex-encoded string representing the SHA1 digest of the ruleset text #### Status Codes | Code | Name | Description | | ---- | ----------- | -----------------------------------------------------------------------------------| | 200 | OK | The ruleset was successfully queued for retro hunt. | | 400 | Bad Request | The received request was malformed and cannot be processed. | | 403 | Forbidden | The server understood the request, but is refusing to fulfill it or quota reached. | | 404 | Not Found | The ruleset with *ruleset_name* does not exist for the authenticated user. | | 409 | Conflict | Retro hunt for the ruleset with *ruleset_name* has already been started. | ### Check Retro Hunt Status This query checks the retro hunt status for the specified ruleset. #### Request ``` GET /api/yara/admin/v1/ruleset/{ruleset_name}/status-retro-hunt ``` #### Request Format - `ruleset_name` - String containing the name of a YARA ruleset previously uploaded by the user. The name should be between 3 and 48 characters long, and conform to the following regular expression: ^\[a-z,A-Z,0-9,\_-\]\*\$ #### Response Format ``` Content-Type: application/json { "ruleset_name" : , "retro_status" : , "reason" : , "progress" : , "start_time" : , "finish_time" : , "estimated_finish_time" : } ``` - `ruleset_name` - String specified by the user in the request - `retro_status` - Current ruleset retro hunt status. The value can be one of the following: PENDING, IN_VALIDATION, VALIDATION_FAILURE, VALIDATION_SUCCESS, RUNNING, FINISHED, CANCELLED - `reason` - Textual description of the reason for the current status (if applicable) - `progress` - Estimated retro hunt progress, expressed as a float number from interval \[0,1\] (0 meaning that the hunt has not yet started, 1 meaning that the hunt is finished) - `start_time` - Timestamp in the *YYYY-MM-DDThh:mm:ss* format indicating when the retro hunt was started. Returns null if the retro hunt has not been started yet - `finish_time` - Timestamp in the *YYYY-MM-DDThh:mm:ss* format indicating when the retro hunt was finished. Returns null if the retro hunt is still running - `estimated_finish_time` - Timestamp in the *YYYY-MM-DDThh:mm:ss* indicating when the retro hunt is estimated to finish. Returns null if it has already finished #### Status Codes | Code | Name | Description | | ---- | ----------- | ---------------------------------------------------------------------------| | 200 | OK | The ruleset retro hunt status was successfully retrieved. | | 400 | Bad Request | The received request was malformed and cannot be processed. | | 404 | Not Found | The ruleset with *ruleset_name* does not exist for the authenticated user. | ### Cancel Retro Hunt This query cancels the retro hunt for the specified ruleset. #### Request ``` POST /api/yara/admin/v1/ruleset/cancel-retro-hunt ``` #### Request Format ``` Content-Type: application/json { "ruleset_name" : } ``` - `ruleset_name` - String containing the name of a YARA ruleset previously uploaded by the user. The name should be between 3 and 48 characters long, and conform to the following regular expression: ^\[a-z,A-Z,0-9,\_-\]\*\$ #### Response Format ``` Content-Type: application/json { "ruleset_name" : , "ruleset_sha1" : } ``` - **ruleset_name** - string specified by the user in the request - **ruleset_sha1** - hex-encoded string representing the SHA1 digest of the ruleset text #### Status Codes | Code | Name | Description | | ---- | ----------- | -----------------------------------------------------------------------------------| | 200 | OK | Retro hunt for the specified ruleset was successfully cancelled. | | 400 | Bad Request | The received request was malformed and cannot be processed. | | 403 | Forbidden | The server understood the request, but is refusing to fulfill it or quota reached. | | 404 | Not Found | The ruleset with *ruleset_name* does not exist for the authenticated user. | ## YARA Retro Matches Feed API ### Fetch Retro matches This query returns a recordset of YARA ruleset matches in the specified time range for a particular user. #### Request ``` GET /api/feed/yara/retro/v1/query/{time_format}/{time_value}[?format=xml|json&extended={boolean}] ``` #### Request Format - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - `time_value` - The value defining the start of the requested time range - `format` - Optional parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json** - `extended` - When set to `true`, the response entries include additional enrichment fields: - `md5` - MD5 hash of the file - `sha256` - SHA256 hash of the file - `first_seen` - timestamp when the sample was first seen - Optional (default: `false`) The time range is defined as the time period from the time specified by the *time_value* parameter up to the time when the request is being 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. Specifying a time value outside this period will yield a "400 Bad Request" status code. 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. The response data provides the latest timestamp until which events are included. To fetch the next recordset, the timestamp from the response field *last_timestamp* should be increased by 1 and used in the next query as the *time_value* parameter. The maximum time span for a single request is limited to 24 hours. All time values are in UTC, independent of the input format. **Example Requests** Get all YARA matches from 2026-01-20 00:00:00 as timestamp: ``` /api/feed/yara/retro/v1/query/timestamp/1768953600 ``` Get all the YARA matches from 2026-01-20 00:00:00 UTC as date string: ``` /api/feed/yara/retro/v1/query/utc/2026-01-20T00:00:00 ``` Fetch all YARA matches from 2026-01-20 00:00:00 in the JSON format: ``` /api/feed/yara/retro/v1/query/timestamp/1768953600?format=json ``` Fetch all YARA matches from 2026-01-20 00:00:00 in the XML format: ``` /api/feed/yara/retro/v1/query/timestamp/1768953600?format=xml ``` Fetch all YARA matches from 2026-01-20 00:00:00 with extended metadata (MD5, SHA256, first_seen): ``` /api/feed/yara/retro/v1/query/timestamp/1768953600?format=json&extended=true ``` #### Response Format A query response will contain zero or more match entries that are found within the specified time period. A single entry represents a match produced by a specific YARA ruleset against a particular sample file. The entry contains information about the sample file (SHA1, file size) as well as information on one or more rules from the ruleset that matched the sample file (rule name, tags, meta fields and their values). Additional data propagated from YARA engine is a list of matching strings contained in matched_data objects. The matched_data object is a 3 dimensional vector with the form `(int match_offset, base64_string string_identifier, base64_string matched_string)`. **Note: Matched data is returned only if it exists and the sample is either public or was previously uploaded by the requesting user.** The `sample_available` field indicates whether a sample can be downloaded using the Spectra Intelligence download API: - `sample_available=true` - The sample is public and downloadable. If matched data exists, it is included in the response. - `sample_available=false` - The sample is not publicly available. Matched data visibility depends on sample ownership: - If the sample was uploaded by the requesting user, matched data is included in the response (when available). - If the sample was uploaded by another user and is private, matched data is hidden from the response. If a sample was matched by several rulesets, each will produce its own entry. **JSON Response Format** ``` json { "rl": { "feed": { "name": "YARA Retro Match Continuous Feed", "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "last_timestamp": timestamp_value, "entries": [ { "timestamp": timestamp_value, "sha1": sample_sha1_value, "file_type": file_type_value, "file_size": file_size_in_bytes, "ruleset_sha1": ruleset_sha1_value, "ruleset_name": ruleset_name, "rule": [ { "identifier": rule_name, "meta": [[name_0, value_0], ..., [name_n, value_n]], "tag": [tag_0, ..., tag_m] }, ... { "identifier": rule_name, "meta": [[name_0, value_0], ..., [name_n, value_n]], "tag": [tag_0, ..., tag_m] } ], "sample_available": boolean, // Extended fields (available when extended=true) "md5": "string", "sha256": "string", "first_seen": "string" }, ... ] } } } ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 200 | The ruleset was successfully queued for retro hunt. | | 201 | The request has been fulfilled, resulting in the creation of a new resource. | | 400 | The received request was malformed and cannot be processed. | | 404 | The ruleset with *ruleset_name* does not exist for the authenticated user. | | 409 | Retro hunt for the ruleset with *ruleset_name* has already been started. | --- ## Advanced Search API (TCA-0320) — Spectra Intelligence The Advanced Search enables users to filter samples by search criteria submitted in a POST request. A wide range of search keywords is available, and they can be combined using search operators to build advanced queries. **This API is rate limited to 1 request per second.** ## General Information - Default response format is **xml** - POST requests must contain **Content-Type: application/json** in the HTTP header field - The maximum amount of API results that can be returned for a search query is 100,000. Although there may be more samples matching the query in the Spectra Intelligence system, the API will only allow browsing through 100,000 of them. - Limitation for one request (records_per_page) is 10,000 samples. - If there are more results than the requested amount of results per page, you can retrieve them by fetching the next page of results using the next_page value from the response as the page value in the next request with the same query. The maximum amount of pages that can be fetched is the overall limit of results (100000) divided by the requested amount of results per page. For example, if the requested number of results per page is 1000, the maximum number of pages is 100. When there are no more results, the **more_pages** value in the response will be false. If the requested page doesn't exist, or the overall amount of results is over 100,000, the response "Max limit reached" with status code 400 is returned. - To ensure quicker response times for long and complex queries, the response may contain fewer results than are available in the database i.e. the service will only return newest matches found within a reasonable timeframe. - Longer and complex queries can result in a "Search query too long, shorten and/or simplify your query" message being displayed. Although the maximum search query length is 7000 characters, even shorter queries can get expanded during input sanitization and exceed that character limit. ## Search Results Algorithm If the number of search query results is smaller than 1000, the Search Results Algorithm returns the exact total number of results. For search queries where the number of results is greater than 10,000, the Search Results Algorithm returns an estimated total number of results, rounded down to a lower value. Depending on the number of results, the algorithm will return the results in the following way. If the number of search results is: - between 1000 and 10k - the total results number is rounded to hundreds - between 10k and 100k - the total results number is rounded to thousands - between 100k and 1M - the total results number is rounded to ten-thousands - between 1M and 10M - the total results number is rounded to hundred-thousands - etc. ## Non-keyword search Advanced search queries can be quickly built without using keywords. Non-keyword search is available only for a particular subset of indicators of compromise: - SHA1, SHA256 and MD5 hashes - URLs - IP addresses - domains - emails - exploits (`CVE-XXXX-YYYYY`) - threatnames - filenames ### Non-keyword Search Queries Non-keyword searches can be performed as standalone queries containing one or more non-keyword values, or be combined with traditional keyword searches. Email and IP (IPv4, IPv6) non-keyword queries support wildcard matching. **Single non-keyword search** This can be any one of the IOCs listed above. **Multiple non-keyword search** When combining multiple non-keyword search values delimited by spaces, the whole query will be enclosed in brackets and the spaces will be interpreted as the operator OR. Users can explicitly provide different operators (AND/NOT) to build more complex queries. **Non-keyword with keyword** When combining non-keyword search values with keywords, consecutive non-keyword values will be enclosed in brackets and the spaces between them will be interpreted as the operator OR. Spaces between non-keyword search values and keywords will be interpreted using the operator AND, meaning that the order of keywords and non-keyword values in the query is important. **Combining queries with the NOT operator** The **NOT** operator excludes search results that match the defined criteria. **Additional Notes** If a list of non-keyword search values contains invalid entries, the API will respond with the status code `400 Bad Request` and return the first invalid non-keyword. In cases where the query contains only hashes, invalid entries will be returned in the `invalid_hashes` response field. Using commas between non-keyword search values will result in an invalid query. Searching for strings containing commas and other special characters is supported by using quotation marks. For example, IPV6 addresses or URLs containing colons, commas, or brackets must be enclosed in quotation marks: - `'2001:0db8:85a3:0000:0000:8a2e:0370:7334'` - `'http://www.evildomain.com/gate.php?13,35869'` ### Non-keyword Search Examples | Query Type | Example | Syntax | Outcome | |-------------------------------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------|-----------------------------------------------------| | Single non-keyword | `0000038704cb5f0e1bd87d6a75e904529af0d6ac` | NK | NK | | Non-keyword search values combined with keywords | `'hope-bd.com/googledocs.php' class:KNOWN` | NK K | NK **AND** K | | Multiple non-keyword values (hashes only) | `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb` | NK NK | (NK **OR** NK) | | Multiple non-keyword values | `127.0.0.1 '2620:119:35::35' google.com` | NK NK NK | (NK **OR** NK **OR** NK) | | Multiple non-keyword values with an AND operator | `mock@mockmail.com 127.0.*.1 AND google.com 'https://hope-bd.com/googledocs.php'` | NK NK AND NK NK | (NK **OR** NK) **AND** (NK **OR** NK) | | Multiple keywords combined with multiple non-keyword values | `class:MALICIOUS mock@mockmail.com google.com firstseen:2018-04-05T21:11:47Z` | K NK NK K | K **AND** (NK **OR** NK) **AND** K | | Combining queries with the NOT operator | `NOT *@mockmail.com 'https://hope-bd.com/googledocs.php' AND NOT 0000038704cb5f0e1bd87d6a75e904529af0d6ac class:MALICIOUS` | NOT NK NK AND NOT NK AND K | (**NOT** NK **OR** NK) **AND** **NOT** NK **AND** K | ## Bulk search Bulk search can be used to search for a large number of samples in a single request. It supports the following keywords: - sha1 - sha256 - md5 - hashes The keyword **hashes** can be used to perform mixed hash searches without grouping or explicitly naming large numbers of hashes. All keywords can be used in any combination with each other. **Examples with IN criteria:** ``` hashes:[b2cc741853154e2f08057e117cc74f2338d6ffe1, 554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294, …, e7a7392e53c55c1c66c1fa9839264c00] ``` **Example with OR:** ``` sha1:b2cc741853154e2f08057e117cc74f2338d6ffe1 OR sha256:554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294 … OR md5:e7a7392e53c55c1c66c1fa9839264c00 ``` **Example with IN and OR:** ``` hashes:[b2cc741853154e2f08057e117cc74f2338d6ffe1, 554eb577df9e7c3c7cfcb0fc08518dce6ae86f2f4346f57c1e99e80329dd6294, …, e7a7392e53c55c1c66c1fa9839264c00] OR sha1:beeb467c917af6fd0064a265c31803e0977b6ae ``` Bulk search queries support only the operator OR, while AND or NOT are not supported. The maximum number of unique hashes per request is 10 000. Response can take up to one minute. The response will always contain a field with a list of all samples that matched the queried hashes. If the query contained some invalid hashes, they will be returned in the "invalid hashes" field of the response. Valid hashes without matches will be returned in the "unknown_hashes" field of the response. Daily sample processing can cause some differences between sample metadata returned by bulk search and regular search. ## Supported Search Keywords ### User-friendly modifiers Some keywords support **modifiers** that serve as shorthand notation for search expressions. These modifiers are available both in [string queries](#string-query) and in [JSON queries](#json-query). #### Numbers Keywords that accept numbers as values also accept a trailing plus or minus sign. For example: - `5+` (five or more) - `42-` (fourty-two or less) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries. For example, `[3+ to 5-]` is invalid.
List of keywords that accept numbers - `av-count` - `document-pages` - `elf-section-count` - `filecount` - `macho-section-count` - `macho-segment-count` - `pe-section-count` - `size` - `submissions` - `threatlevel`
#### Dates Keywords that accept dates also accept period abbreviations and trailing plus/minus. Accepted abbreviations: - `h` for hours - `d` for days - `w` for weeks - `m` for months - `y` for years The trailing plus or minus sign behaves just like for numbers. For example: - `2023-04-11T08:10:00+` (on April 11 2023 at 08:10, or after that time) - `3d+` (three days or more) - `1w-` (one week or less) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries. For example, `[3d to 5w]` is invalid.
List of keywords that accept dates - `firstseen` - `lastanalysis` - `lastseen` - `pe-timestamp` - `signer-valid-from` - `signer-valid-to` - `taggant-valid-from` - `taggant-valid-to`
#### Sizes Keywords that accept sizes also accept unit abbreviations (KB, MB, GB...) and trailing plus/minus. The abbreviations are case-insensitive. If an abbreviation is not specified, the expression is evaluated in bytes. [Byte multiples](https://en.wikipedia.org/wiki/Byte#Multiple-byte_units) are supported in both decimal (kilo-, mega-, giga-...) and binary (kibi-, mebi-, gibi-...) form. For example: - `5MB+` (five megabytes or larger) - `13kib-` (thirteen kibibytes or smaller) Exceptions: - Spaces are not allowed. - Prefixes are also not allowed (only trailing plus or minus). - Modifiers can't be used in range queries if they contain a trailing plus or minus sign. For example, `[3kB+ to 5MB]` is invalid. However, if you use them without a trailing plus/minus, they can be used in a range query. For example, `[3kb TO 5mb]` is allowed. The only keyword that accepts a size is `size`. ### Group keywords When using group keywords, the provided search query will be used with all single keywords in the group's respective list. Refer to the single keyword descriptions for more information. Keyword aliases are enclosed in parentheses. | `certificate` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `cert-issuer-name` `cert-issuer-org` `cert-issuer-unit` `cert-subject-name` `cert-subject-org` `cert-subject-unit` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `certificate:*micr*` | | `certificate-country` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `cert-issuer-country` `cert-subject-country` | | Examples | Case-insensitive wildcard matching is supported.List (any of the values): `certificate-country:[HR, US]` | | `document` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `document-author` `document-subject` `document-title` `document-description` `document-language` | | Examples | Case-insensitive wildcard matching is supported.List (any of the values): `document:[adobe, microsoft, *confidencial]`Wildcard: `document:*soft` | | `language` (`lang`) | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `document-language` `pe-language` | | Examples | Case-insensitive wildcard matching is supported.List (any of the values): `language:[english, german]` | | `mutex` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `mutex-config` `mutex-dynamic` | | Examples | The keyword is case-sensitive and doesn't accept wildcards.Exact: `mutex:111c`List (any of the values): `mutex:[111c, 2124]` | | `ipv4` (`ip`) | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `ipv4-static` `ipv4-dynamic` | | Examples | Wildcard matching supported.Wildcard: `ipv4:192.*`List (any of the values): `ipv4:[1.0.0.0,1.0.2.1]` | | `ipv6` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `ipv6-static` (IPv6 address strings detected by ReversingLabs Dynamic Services) | | Examples | If the address contains colons or brackets, enclose it in quotation marks.Wildcard matching supported.Wildcard: `ipv6:c*`Exact: `ipv6:"2002::/16"`List (any of the values): `ipv6:["2001:db8*", "3731:54:"]` | | `section` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `pe-section-name` `elf-section-name` `macho-section-name` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `section:*data`List (Any of the values): `section:[.ndata, bss]` | | `segment` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `macho-segment` `macho-segment-name` `elf-segment-sha1` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `segment:page*`List (any of the values): `segment:[pagezero, text]` | | `software` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `software-package` `software-description` `software-author` | | Examples | Case-insensitive wildcard matching is supported.Wildcard: `software:*Microsoft*`List (any of the values): `software:[Microsoft, "This package consists of multiple activities that simplify the processes in Excel."]` | | `uri` | Group keyword | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Includes | `uri-source` `uri-static` `uri-config` `uri-dynamic` | | Examples | Case-insensitive wildcard matching is supported. (`uri*` keywords don't support IP addresses. For that, use `ip*` keywords.)Wildcard: `uri:mozilla.org*`List (any of the values): `uri:[\*.tor,*.onion,*.exit]` | ### Single keywords | `actor` | | |-------------|-----------------------------------------------------------------------------------------------------------------------| | Description | Search for files based on the associated APT actor name. Case-insensitive wildcard matching is supported. | | Examples | Exact: `actor:apt28`Wildcard: `actor:*apt*`List (any of the values): `actor:[apt28, lazarus]` | | `android-app-name` | | |--------------------|----------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their process name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-app-name:*SkypeApplication*`List (any of the values): `android-app-name:[MainApp, *alt.ywuajgf*]` | | `android-features` | | |--------------------|----------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their features. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-features:*hardware.camera*`List (any of the values): `android-features:[camera, telephony]` | | `android-import` | | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by one or more shared libraries that the applications are linked against. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-import:org.apache.http.legacy*`List (any of the values): `android-import:[sec_fe?ture, *google*]` | | `android-package` | | |-------------------|--------------------------------------------------------------------------------------------------------------------------------------| | Description | Search for Android applications by their package name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-package:*com.picklieapps.player*`List (any of the values): `android-package:[*ruckygames*, *skype.raider*]` | | `android-permission` || |----------------------|------| | Description | Search for Android applications by their permissions. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `android-permission:*WRITE_SETTINGS*`List (any of the values): `android-permission:[*storage*, *disable_keyguard*]` | | `appid-company-name` (`appid-author`) || |-------------|------| | Description | Search for applications and libraries by their publisher. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-company-name:"Mozilla Foundation"`List (any of the values): `appid-company-name:["Mozilla Foundation", "Microsoft Corporation"]` | | `appid-description` || |-------------|------| | Description | Search for applications and libraries by their description. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `appid-description:"*Firefox Plugin Hang UI*"*` | | `appid-product-name` | | |-------------|------| | Description | Search for files with a matching product name. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-product-name:"Mozilla Firefox Plugin Hang UI"`List (any of the values): `appid-product-name:["Mozilla Firefox Plugin Hang UI", "Mozilla Firefox Helper"]` | | `appid-product-type` (`appid-category`) | | |-------------|------| | Description | Search for applications and libraries by their type. Case-insensitive wildcard matching is supported. | | Examples | Exact: `appid-product-type:browser`List (any of the values): `appid-product-type:[browser, development]` | | `attack-tactic` | | |-------------|------| | Description | Search for files that use a specific Mitre ATT&CK tactic. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `attack-tactic:TA0007`List (any of the values): `attack-tactic:[TA0007, TA0005]` | | `attack-technique` | | |-------------|------| | Description | Search for files that use a specific Mitre ATT&CK technique. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `attack-technique:T1222`List (any of the values): `attack-technique:[T1222, T1112]` | | `av-count` (`positives`, `p`, `antivirus`) | | |-------------|------| | Description | The number of antivirus scanners that have detected a sample as malicious. Currently supports any integer from 0 to 46 (46 being the number of active AV scanners). | | Examples | Exact: `av-count:5`Range: `positives:[10 TO 20]`Greater than 5: `positives:[5 TO *]`List (any of the values): `av-count:[5,3]` | | `av-detection` (`engines`) | | |-------------|------| | Description | Detection string generated by the antivirus engines. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `av-detection:micro*`List (any of the values): `av-detection:[W32.Duqu, *Vitro]` | | `av-` (``) | | |-------------|------| | Description | Search for all samples or samples of specific malware detected by a selected antivirus vendor. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `av-[vendor]:*wannacry*`List (any of the values): `[vendor]:[win32, emotet]` | | `available` (`in`, `shareable`) | | |-------------|------| | Description | Indicates whether a sample is available for download from the cloud. The only supported values are true and false (case-insensitive). | | Examples | `available:TRUE``in: false` | | `browser-package` | | |-------------|------| | Description | Search for web browser extensions by their package name. Supported package formats: Chrome, Safari, Firefox. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `browser-package:*Click2Save*`List (any of the values): `browser-package:[*priiceechOp*, *iCalc*]` | | `cert-issuer-country` | | |-------------|------| | Description | Search for files by the country code in the country name property field of the issuer of the certificate used to sign the file. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-issuer-country: US`List (any of the values): `cert-issuer-country:[Z?,G*]` | | `cert-issuer-name` | | |-------------|------| | Description | Search for files by the name of the certificate authority (CA). Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-issuer-name: COMODO`List (any of the values): `cert-issuer-name:[microsoft,*VeriSign*]` | | `cert-issuer-org` | | |-------------|------| | Description | Search for files by the organization name of the certificate issuer. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `cert-issuer-org:*authority`List (any of the values): `cert-issuer-org:[verisign, microsoft]` | | `cert-issuer-unit` | | |-------------|------| | Description | Search for files by the organizational unit name of the issuer unit of the certificate authority (CA). Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `cert-issuer-unit:*root*` List (any of the values): `cert-issuer-unit:["trust network", *root*]` | | `cert-serial` | | |-------------|------| | Description | Search for a file by the serial number of the file certificate provided by the CA that issued the certificate. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `cert-serial:6101CF3E00000000000F`List (any of the values): `cert-serial:[,]` | | `cert-subject-country` | | |-------------|------| | Description | Search for files by the country code in the country name property field of the subject to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-country:DE`List (any of the values): `cert-subject-country:[US, B*]` | | `cert-subject-name` | | |-------------|------| | Description | Search for files by the name of the organization/system to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-name:Piriform`List (any of the values): `cert-subject-name:[cinectic*, google]` | | `cert-subject-org` | | |-------------|------| | Description | Search for files by the organization name of the certificate authority organization (CA). Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-org:apple`List (any of the values): `cert-subject-org:[apple, Microsoft]` | | `cert-subject-unit` | | |-------------|------| | Description | Search for files by the organizational unit name inside the organization to which the certificate has been issued. Case-insensitive wildcard matching is supported. | | Examples | Exact: `cert-subject-unit:"Developer Relations"`List (any of the values):`cert-subject-unit:[Developer*, "Trust Network"]` | | `cert-thumbprint` | | |-------------|------| | Description | Search for files by their unique certificate thumbprint. A thumbprint of a file certificate is a hash value (SHA256). The keyword doesn't accept wildcards. | | Examples | Exact: `cert-thumbprint:277D42[...]2A17DD`List (any of the values): `cert-thumbprint:[, ]` | | `classification` (`class`) | | |-------------|------| | Description | Search for files by their Malware Presence status designation. Accepted values: malicious, known, suspicious, unknown (case-insensitive). | | Examples | Exact: `classification:malicious`List (any of the values): `classification:[KNOWN, suspicious]` | | `dex-class-name` | | |-------------|------| | Description | Search for DEX files by the names of classes they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dex-class-name:android.content.DialogInterface.On*`List (any of the values): `dex-class-name:[android.content.DialogInterface.On*, android.support.v4.*]` | | `dex-method-name` | | |-------------|------| | Description | Search for DEX files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dex-method-name:unregisterCallB*`List (any of the values): `dex-method-name:[getLocation, invok*]` | | `document-author` | | |-------------|------| | Description | Search for files by the contents of their document author metadata property. Case-insensitive wildcard matching is supported. | | Examples | List (any of the values): `document-author:[adobe, microsoft]`Wildcard: `document-author:*soft` | | `document-description` (`doc-description`) | | |-------------|------| | Description | Search for files by the document description field, as provided by the document author. Case-insensitive wildcard matching is supported. | | Examples | List (any of the values): `document-description:["Carta personal", *confidencial]`Wildcard: `document-description:*Math*` | | `document-pages` (`doc-pages`) | | |-------------|------| | Description | Search for files by their number of pages. In case of spreadsheet documents, this number represents the number of sheets. The keyword accepts only integer values. | | Examples | Exact: `document-pages:73`Range: `document-pages:[4 TO 20]`More than 4: `document-pages:[4 TO *]` | | `document-subject` | | |-------------|------| | Description | Search for files by the contents of their document subject metadata property. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `document-subject:*search`List (any of the values): `document-subject:[free, download]` | | `document-title` | | |-------------|------| | Description | Search for files by the contents of their document title metadata property. Case-insensitive wildcard matching is supported. | | Examples | Exact: `document-title:"Powered by"`List (any of the values): `document-title:[*free*, README]` | | `document-version` | | |-------------|------| | Description | Search for files by the contents of their document version metadata property. Wildcard matching is supported. | | Examples | Wildcard: `document-version:1.1*`List (any of the values): `document-version:[1.7, 2.*]` | | `document-language` | | |-------------|------| | Description | Search for files by the contents of their document language metadata property. Wildcard matching is supported. | | Examples | Wildcard: `document-language:*`List (any of the values): `document-language:[english, german]` | | `domain` | | |-------------|------| | Description | Search for files by any associated domain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `domain:mozilla.org*`List (any of the values): `domain:[*.tor,google.com,*.exit]` | | `dotnet-assembly` | | |-------------|------| | Description | Search for .NET files by assemblies they reference. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-assembly:*mscorlib*`List (any of the values): `dotnet-assembly:[*iJnJWYUQA*, "NanoCore Client"]` | | `dotnet-method-name` | | |-------------|------| | Description | Search for .NET files by method names their classes call to perform an action. Method names are indexed regardless of their visibility, meaning both public and private methods are searchable. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-method-name:get_Url`List (any of the values): `dotnet-method-name:[?oadCompl*, *HoldEnd]` | | `dotnet-module-id` | | |-------------|------| | Description | Search for .NET files by IDs of modules they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-module-id:*20DEC3DA-523F*`List (any of the values): `dotnet-module-id:[*9249F5D0-1821*, *E133ACC7-60C9*]` | | `dotnet-module-name` | | |-------------|------| | Description | Search for .NET files by names of modules they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-module-name:*TeSt.exe*`List (any of the values): `dotnet-module-name:[Posh.exe, adobe.exe]` | | `dotnet-pinvoke-function` | | |-------------|------| | Description | Search for .NET files by pinvoke functions. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-pinvoke-function:EncodePointer*`List (any of the values): `dotnet-pinvoke-function:["EncodePointer", "DecodePointer"]` | | `dotnet-pinvoke-import` | | |-------------|------| | Description | Search for .NET files by pinvoke imports. Case-insensitive wildcard matching is supported. | | Examples | Exact: `dotnet-pinvoke-import:kernel32.dll`List (any of the values): `dotnet-pinvoke-import:["kernel32.dll", "user32.dll"]` | | `dotnet-resource` | | |-------------|------| | Description | Search for .NET files by resources they contain. Case-insensitive wildcard matching is supported. | | Examples | Exact: `dotnet-resource:"Hidden Tear"`List (any of the values): `dotnet-resource:[*Orcus*, *Clientloaderform*]` | | `dotnet-type-name` | | |-------------|------| | Description | Search for .NET files by type names found in them. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `dotnet-type-name:Form1*`List (any of the values): `dotnet-type-name:[Form1*, NetscapeRevocationUrl]` | | `elf-section-count` | | |-------------|------| | Description | Search for ELF files by the amount of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `elf-section-count:5`Range: `elf-section-count:[5 TO 15]`More than 5: `elf-section-count:[5 TO *]` | | `elf-section-name` | | |-------------|------| | Description | Search for ELF files by names of the sections they contain. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `elf-section-name:*data`List (any of the values): `elf-section-name:[.rodata, .ndata, .bss]` | | `elf-segment-sha1` (`elf-segment-hash`) | | |-------------|------| | Description | Search for files by the SHA1 hash of their ELF segment. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `elf-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc` | | `elf-symbol` | | |-------------|------| | Description | Search for ELF files by their symbol names. Case-insensitive wildcard matching is supported. | | Examples | Exact: `elf-symbol:exit`Wildcard: `elf-symbol:*exit*`List (any of the values): `elf-symbol:[exit, malloc, umask]` | | `email-from` | | |-------------|------| | Description | Search for files by the sender of an email associated to a file. Includes "from", "reply-to" and "sender" fields. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-from:*@kiski.net`List (any of the values): `email-from:[*@domain.com, *@orbitz.com]` | | `email-static` (`email`) | | |-------------|------| | Description | Search for files by associated email address(es) detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis). Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-static:*@Compartir.es`List (any of the values): `email-static:[*@gmail.com, *@hotmail.com]` | | `email-subject` | | |-------------|------| | Description | Search for files by the subject of an email associated to a file. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-subject:*HackTool`List (any of the values): `email-subject:[Invitation*, *Nova*]` | | `email-to` | | |-------------|------| | Description | Search for files by the receiver of an email associated to a file, specified in the "to" field. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-to:*@netnook.com`List (any of the values): `email-to:[*@dekalb.net, *@rogers.com]` | | `email-x-key` | | |-------------|------| | Description | Search for files with non-standard header fields, called X-extensions. Security vendors use X-extensions to annotate emails that have been scanned using their product. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-x-key:*MDRemoteIP`List (any of the values): `email-x-key:[*Indiv, *Markup]` | | `email-x-value` | | |-------------|------| | Description | Search for files by values stored in non-standard (X-extension) header fields. Case-insensitive wildcard matching is supported. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `email-x-value:?HAILAND`List (any of the values): `email-x-value:[Produced*, BHUTAN]` | | `exif` | | |-------------|------| | Description | Search for multimedia files by the contents of their EXIF metadata fields. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `exif:Picasa*`List (any of the values): `exif:["Paint.NET v3.5.8", Picasa*]` | | `exploit` | | |-------------|------| | Description | Search for samples that are exploiting a specific vulnerability, identified either by ReversingLabs or by antivirus scanners. | | Examples | Examples Wildcard: `exploit:cve-2024-*`*List (any of the values): `exploit:["CVE-2014-0114", "CVE-2018-15982"]` | | `filecount` | | |-------------|------| | Description | Search for a file by the number of unpacked files it contains (if it's a container). Accepts any integer number. **Note: this keyword currently returns only Local samples as results.** | | Examples | Exact: `filecount:25`Range: `filecount:[3 TO 10]`More than 20: `filecount:[20 TO *]` | | `filename` (`name`) | | |-------------|------| | Description | Search for a file by its full or partial file name, predicted file name (generated by Spectra Core for samples without a file name), or file extension. The file name must contain at least one dot, have an extension from the supported extensions list below, and not contain any disallowed characters (forward slash `/`, backslash `\`, vertical line `\|`, or colon `:`). Case-insensitive wildcard matching is supported. | | Examples | Exact: `filename:notepad.exe`List (any of the values): `filename:[*.PDF, *.epub]` |
Supported `filename` extensions - 7z - a - aar - ace - adml - aif - al - am - anim - api - apk - app - appx - appxbundle - arc - arsc - asc - asp - aspx - assetbundle - assets - aux - ax - bat - beam - bin - bmp - bpl - br - bundle - bz2 - c - cab - caf - cat - cc - ccbi - ccx - ccz - cdr - cfg - cfm - cgi - chk - chm - class - cmake - cmd - com - conda - conf - cpp - crate - crx - cs - csproj - css - csv - cxx - dat - db - dbf - dcu - deb - def - desktop - dex - dll - dmg - doc - docm - docx - download - drv - dsc - dtd - dylib - egg - elf - emf - eml - enc - eps - epub - exe - f - file - fits - fob - fr - ftl - gem - gif - go - gz - h - hpp - html - ico - img - inc - ini - ipa - iso - jar - java - jpeg - jpg - js - json - jsp - kdc - lha - lib - log - lua - lz - lzma - m - m4a - man - map - md - mdb - mkv - mo - mod - mp3 - mp4 - msi - npy - o - ogg - opus - pdf - php - pkg - pl - png - ppt - pptm - pptx - ps - py - pyc - pyo - rar - rb - rc - reg - rpm - rs - rst - rtf - s - sh - so - sql - svg - swf - tar - tbz - tbz2 - tex - tga - tgz - tif - tiff - toml - torrent - ts - tsx - txt - uasset - udeb - war - wav - webp - whl - wim - woff - woff2 - x86 - xaml - xap - xhtml - xls - xlsb - xlsm - xlsx - xml - xpi - xpm - yaml - yml - zip - zst
| `firstseen` (`fs`) | | |-------------|------| | Description | Time when a file was first analyzed by Spectra Intelligence. Supported time format is UTC timestamp. | | Examples | Exact: `fs:2018-04-03T12:58:27Z`Range (time period):`firstseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z]` | | `hashes` | | |-------------|------| | Description | Allows mixing different types of hashes in one search query, without the need to explicitly name the hash type or to group hashes by type. All hash types (MD5, SHA1, SHA256) can be used with this keyword. The maximum length of a single query is 1024 characters. The keyword is case-sensitive and doesn't support wildcards. | | Examples | Exact: `hashes: `List (any of the values): `hashes:[, , , , ]` | | `imphash` | | |-------------|------| | Description | Hash based on library/API names and their specific order within the executable. Used to find similar PE files. The keyword doesn't support wildcards. | | Examples | Exact: `imphash:f34d5f2d4577ed6d9ceec516c1f5a744`List (any of the values): `imphash:[, ]` | | `indicators` | | |-------------|------| | Description | Search for files by their static analysis behaviors. The keyword is case-sensitive and doesn't accept wildcards. The full list of indicator IDs and their descriptions can be found [here](/General/SpectraCore/indicators/). | | Examples | Exact: `indicators:"2150"`List (any of the values): `indicators:["2150", "2102"]` | | `ios-app-name` | | |-------------|------| | Description | Search for iOS applications by their name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-app-name:FruitNinja*`List (any of the values): `ios-app-name:[FruitNinja*, *facebook*]` | | `ios-author` | | |-------------|------| | Description | Search for iOS applications by their author name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-author:*halfbrick*`List (any of the values): `ios-author:[*halfbrick*, Apple*]` | | `ios-package` | | |-------------|------| | Description | Search for iOS applications by their package name. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `ios-package:*FruitNinja*`List (any of the values): `ios-package:[*FruitNinja*, *facebook*]` | | `ipv4-dynamic` | | |-------------|------| | Description | Search for files by IPv4 address strings detected by ReversingLabs Dynamic Services. Wildcard matching supported. | | Examples | Wildcard: `ipv4-dynamic:192.*`List (any of the values): `ipv4-dynamic:[1.0.0.0,1.0.2.1]` | | `ipv4-static` | | |-------------|------| | Description | Search for files by IPv4 address strings detected by Spectra Core analysis. Wildcard matching supported. | | Examples | Wildcard: `ipv4-static:192.*`List (any of the values): `ipv4-static:[1.0.0.0,1.0.2.1]` | | `ipv6-static` | | |-------------|------| | Description | Search for files by IPv6 address strings detected by Spectra Core analysis. If the address contains colons or brackets, enclose it in quotation marks. Wildcard matching supported. | | Examples | Wildcard: `ipv6-static:c*`Exact: `ipv6-static:"2002::/16"`List (any of the values): `ipv6-static:["2001:db8*", "3731:54:"]` | | `lastanalysis` (`la`) | | |-------------|------| | Description | Search for files by the date and time of their last AV scan. Supported time format is UTC timestamp. | | Examples | Exact: `lastanalysis:2018-05-17T11:27:19Z`Range (time period):`lastanalysis:[2018-05-17T11:27:19Z TO 2018-05-24T11:27:19Z]` | | `lastseen` (`ls`) | | |-------------|------| | Description | Time when a file was last analyzed by Spectra Intelligence. Supported time format is UTC timestamp. | | Examples | Exact: `ls:2018-04-03T12:58:27Z`Range (time period):`lastseen:[2017-12-01T11:36:59Z TO 2018-03-06T11:36:59Z]` | | `macho-import` | | |-------------|------| | Description | Search for MachO files by the names of imported libraries found in them. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `macho-import:*/usr/lib/*`List (any of the values): `macho-import:[/usr/lib/libgcc_s.1.dylib, /usr/lib/libSystem.B.dylib]` | | `macho-section-count` | | |-------------|------| | Description | Search for MachO files by the number of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `macho-section-count:10`Range: `macho-section-count:[5 TO 15]`More than 5: `macho-section-count:[5 TO *]` | | `macho-section-name` | | |-------------|------| | Description | Search for MachO files by the names of the sections they contain. Case-insensitive wildcard matching supported. | | Examples | Exact: `macho-section-name:data`List (any of the values): `macho-section-name:[bss, common, data]` | | `macho-segment` (`macho-segment-name`) | | |-------------|------| | Description | Search for MachO files by their segment names. Case-insensitive wildcard matching supported. | | Examples | Exact: `macho-segment:pagezero`List (any of the values): `macho-segment:[linkedit, pagezero, text]` | | `macho-segment-count` | | |-------------|------| | Description | Search for MachO files by the count of segments they contain. The keyword accepts only integer values. | | Examples | Exact: `macho-segment-count:30`Range: `macho-segment-count:[2 TO 8]`More than: `macho-segment-count:[11 TO *]` | | `macho-segment-sha1` (`macho-segment-hash`) | | |-------------|------| | Description | Search for files by the SHA1 hash of their MachO segment. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `macho-segment-sha1:116e279b55b58e5b9619aac80a8e85bfa9c839fc` | | `macho-symbol` | | |-------------|------| | Description | Search for MachO files by their symbol names. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `macho-symbol:f*`List (any of the values): `macho-symbol:[exit, malloc, umask]` | | `md5` | | |-------------|------| | Description | String of hexadecimal digits representing a MD5 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `md5:76baa04885ec40af25294a51d8e7c006`List (any of the values): `md5:[, ]` | | `mutex-config` | | |-------------|------| | Description | Search for files by their malware configuration mutexes detected by Spectra Core. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `mutex-config:")!VoqA.I4"`Exact: `mutex-config:"--((Mutex))--"`List (any of the values): `mutex-config:[111c, 2124]` | | `mutex-dynamic` | | |-------------|------| | Description | Search for files by malware configuration mutexes detected by ReversingLabs Dynamic Services. The keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `mutex-dynamic:111c`List (any of the values): `mutex-dynamic:[111c, 2124]` | | `pdb-path (pdb)` | | |-------------|------| | Description | Search for files associated with specific PDB (program database) paths. Used to find files with the same PDB path created during file sample compilation. If the path contains restricted characters, enclose it in quotation marks. | | Examples | Exact: `pdb:"D:DevTin7InstallDir"`List (any of the values):`pdb:["C:Windows", "c:Program FilesPerforce"]` | | `pe-company-name` | | |-------------|------| | Description | Search for PE files by the contents of their company name field in the version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-company-name:*enix`List (any of the values): `pe-company-name:[microsoft, ADOBE]` | | `pe-copyright` | | |-------------|------| | Description | Search for PE files by the contents of their legal copyright field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-copyright:Copyright*`List (any of the values): `pe-copyright:[*Corporation, regsvr32]` | | `pe-description` | | |-------------|------| | Description | Search for PE files by the contents of their file description field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-description:*proged`List (any of the values): `pe-description:[DisplaySwitch, WizardFramework]` | | `pe-export` (`exports`) | | |-------------|------| | Description | Search for PE files by exported symbol names. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-export:MS*`List (any of the values): `exports:[GetMemoSize, DeleteFile]` | | `pe-function` | | |-------------|------| | Description | Search for PE files by the name of the function that the PE file imports. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-function:RegEnum*`List (any of the values):`pe-function:[RegEnumKeyW, GetUserNameA]` | | `pe-import (imports)` | | |-------------|------| | Description | Search for PE files by the name of the dynamic link library that the PE file imports. Case-insensitive wildcard matching supported. | | Examples | Exact: `pe-import:URLMON.DLL`List (any of the values): `imports:[win*, url*]` | | `pe-language` | | |-------------|------| | Description | Find PE files by languages mentioned in the PE file resources. Case-insensitive wildcard matching supported. [Appendix C - Available Languages for PE and Document Formats](#appendix-c---available-languages-for-pe-and-document-formats). | | Examples | Exact: `pe-language:russian`List (any of the values): `pe-language:[eng*, Russian]` | | `pe-original-name` | | |-------------|------| | Description | Search for PE files by the contents of their file description field in version information metadata, and any other fields using the original name of the file. The keyword can be used to investigate how the file was named during compilation. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-original-name:crack*`List (any of the values): `pe-original-name:[*install.exe, "sample doc.exe"]` | | `pe-overlay-sha1` (`pe-overlay-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their overlay part. Overlay hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-overlay-sha1:4b4a2436b827d42b204b1f112b45d7a6d1b7ca52`List (any of the values): `pe-overlay-sha1:[, , ]` | | `pe-product-name` | | |-------------|------| | Description | Search for PE files by the contents of their product name field in version information metadata. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-product-name:*shop`List (any of the values):`pe-product-name:[Firefox, "Microsoft Word"]` | | `pe-resource` | | |-------------|------| | Description | Search for PE files by name or type of resources they contain. Case-insensitive wildcard matching supported. | | Examples | Exact: `pe-resource:Properties`List (any of the values): `pe-resource:[Tcpview, Aboutbox]` | | `pe-resource-sha1` (`pe-resource-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their resources part. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-resource-sha1:4260284ce14278c397aaf6f389c1609b0ab0ce51`List (any of the values): `pe-resource-sha1:[, ]` | | `pe-section-count` | | |-------------|------| | Description | Search for PE files by the count of sections they contain. The keyword accepts only integer values. | | Examples | Exact: `pe-section-count:15`Range: `pe-section-count:[2 TO 10]`More than: `pe-section-count:[5 TO *]` | | `pe-section-name` | | |-------------|------| | Description | Search for PE files by names of the sections they contain. The maximum section name length is 8 characters. Case-insensitive wildcard matching supported. | | Examples | Wildcard: `pe-section-name:*rdata`List (any of the values): `pe-section-name:[.Rdata, .Ndata, *rsrc]` | | `pe-section-sha1` (`pe-section-hash`) | | |-------------|------| | Description | Find PE files by the SHA1 hash calculated for their section part. Section hashes are calculated by Spectra Core to better represent the true boundary of the file region. Users should use hash values calculated by ReversingLabs products with this keyword. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `pe-section-sha1:7640a007e39b487bf1dbbde6487724faa131f6a8`List (any of the values): `pe-section-sha1:[, , ]` | | `pe-timestamp` (`pets`) | | |-------------|------| | Description | Search for a PE file by the date when it was compiled. Supported time format is UTC timestamp. | | Examples | Exact: `pets:2017-06-26T00:00:00Z`Range (newer than): `pets:[2018-03-06T10:57:29Z TO *]` | | `sampletype` (`filetype`, `type`, `format`) | | |-------------|------| | Description | Search for files by type as detected by Spectra Core. Case-insensitive wildcard matching supported. [Appendix B - Supported Sample Types](#appendix-b---supported-sample-types). | | Examples | Exact: `sampletype:Image/None`List (any of the values): `type:[elf*,macho*]` | | `sha1` | | |-------------|------| | Description | String of hexadecimal digits representing a SHA-1 hash of the file. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `sha1:f1a62a7092e49577206b7361bf1a7ff0776bb6a4`List (any of the values):`sha1:[, ]` | | `sha256` | | |-------------|------| | Description | String of hexadecimal digits representing a SHA-256 hash of the file sample. Keyword is case-sensitive and doesn't accept wildcards. | | Examples | Exact: `sha256:f35a3(...)1d2d5`List (any of the values): `sha256:[, ]` | | `signer-valid-from` (`cert-valid-from`) | | |-------------|------| | Description | Search for files that have been signed by certificates valid from a specific time. | | Examples | Range (newer than): `signer-valid-from:[2018-03-06T10:57:29Z TO *]` | | `signer-valid-to` (`cert-valid-to`) | | |-------------|------| | Description | Search for files that have been signed by certificates valid to a specific time. | | Examples | Range (newer than): `signer-valid-to:[2018-03-06T10:57:29Z TO *]` | | `ssdeep` | | |-------------|------| | Description | Retrieves a single page of up to 1000 samples that are similar to the provided SSDEEP fuzzy hash. SSDEEP values need to be escaped. The keyword is case-sensitive and doesn't support wildcards. **This keyword cannot be combined with any other keywords.** | | Examples | Exact: `ssdeep:"3:AXGBicFlgVNhBGcL6wCrFQEv:AXGHsNhxLsr2C"` | | `similar-to` | | |-------------|------| | Description | Search for files that are functionally similar to the requested file hash. Functionally similar files are defined by RHA (ReversingLabs Hashing Algorithm) that identifies code similarity between unknown samples and previously seen malware samples. All hash types (MD5, SHA1, SHA256) can be used with this keyword. Only one similar-to keyword can be used in a single query. The keyword is case-sensitive and doesn't support wildcards. | | Examples | Exact: `similar-to: ` | | `size` | | |-------------|------| | Description | Search for files by size (in bytes). Accepts integers up to 2147483647. | | Examples | Exact: `size:30000`Range: `size:[1000 TO 50000]`Greater than: `size:[500000 TO *]` | | `software-author` | | |-------------|------| | Description | Search for software packages by their author/publisher. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `software-author:*Amazon*`List (any of the values): `software-author:["Amazon Web Services", Microsoft]` | | `software-description` | | |-------------|------| | Description | Search for software packages by their description. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `software-description:*Excel*`List (any of the values): `software-description:[*Excel*, *activities*]` | | `software-package` | | |-------------|------| | Description | Search for specific software packages. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `software-package:tid*`List (any of the values): `software-package:[tidal, "AWSSDK.WorkLink"]` | | `submissions` | | |-------------|------| | Description | Search for files by the amount of times they have been submitted for analysis. The keyword accepts only integer values. | | Examples | Exact: `submissions:3`Greater than: `submissions:[3 TO *]`Less than: `submissions:[* TO 4]` | | `tag` | | |-------------|------| | Description | Search for files by metadata tags generated by Spectra Core. Tags identify interesting properties of a sample, such as being packed, password-protected, or digitally signed. [Appendix D - Supported Tags](#appendix-d---supported-tags). | | Examples | Exact: `tag:packed`List (any of the values): `tag:[capability-execution, cert, crypto]` | | `tag-yara` | | |-------------|------| | Description | YARA supports adding custom tags to rules. Files that match those rules get automatically tagged after analysis. This keyword looks for files tagged by YARA rules, including those that were classified by YARA tags ("malicious" and "suspicious"). Case-insensitive wildcard matching is supported. Note that changes to YARA tags are not immediately reflected in search results. For example, if a tag is removed from a YARA rule, it will still return search results until files that match the rule are reanalyzed with Spectra Core. | | Examples | Exact: `tag-yara:malicious`List (any of the values): `tag-yara:[malicious, suspicious]` | | `taggant-name` | | |-------------|------| | Description | Search for PE files by name of the packer that was used to pack them. Taggant is a technology that guarantees the packed file came from a reliable source. Case-insensitive wildcard matching supported. | | Examples | Exact: `taggant-name:themida`List (any of the values): `taggant-name:[enigma*, vmprotect*]` | | `taggant-valid-from` | | |-------------|------| | Description | Search for files by the time it was signed using taggant. | | Examples | Range (newer than): `taggant-valid-from:[2018-03-06T10:57:29Z TO *]` | | `taggant-valid-to` | | |-------------|------| | Description | Search for files by the expiry time provided by taggant. | | Examples | Range (newer than): `taggant-valid-to:[2018-03-06T10:57:29Z TO *]` | | `third-party-library` | | |-------------|------| | Description | Search for PE files by the name(s) of third-party libraries they contain. Case-insensitive wildcard matching is supported. | | Examples | Exact: `third-party-library:Microsoft.WindowsAPICodePack-Core`List (any of the values): `third-party-library:[*oak-json*, Microsoft.Web.WebJobs*]` | | `third-party-publisher` | | |-------------|------| | Description | Search for PE files by publishers of the third-party libraries found in the files. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `third-party-publisher:Microsoft*`List (any of the values): `third-party-publisher:[Microsoft*, "Xamarin Inc."]` | | `tlsh` | | |-------------|------| | Description | Retrieves a single page of up to 1000 samples that are similar to the provided TLSH hash. Similarity is determined using TLSH distance. The keyword is case-sensitive and doesn't support wildcards. **This keyword cannot be combined with any other keywords.** | | Examples | Exact: `tlsh:T1DAD0EA4FB4588923C706647566135756AFA3C89034C5B646A3187B1A283A11DEBA1F4C` | | `threatlevel` | | |-------------|------| | Description | Search for files by ReversingLabs scale of threat severity. Higher number indicates higher severity. Accepted values are 0-5. | | Examples | Exact: `threatlevel:3`Greater than: `threatlevel:[2 TO *]`Range: `threatlevel:[0 TO 3]`List (any of the values): `threatlevel:[2, 3]` | | `threatname` | | |-------------|------| | Description | Search for files by malware threat name according to the [ReversingLabs Malware Naming Standard](#appendix-a---reversinglabs-malware-naming-standard). Case-insensitive wildcard matching supported. | | Examples | Exact: `threatname:Win32.PUA.Casonline`List (any of the values):`threatname:["WIN32.PUA.casino eldorado", *crytex]` | | `trustfactor` | | |-------------|------| | Description | Search for files by the ReversingLabs trust factor. Trust factor indicates the trustworthiness of files. Lower number means higher trust. Accepted values are 0-5. | | Examples | Exact: `trustfactor:1`List (any of the values): `trustfactor:[4, 5]`Range: `trustfactor:[1 TO 3]`Greater than: `trustfactor:[3 TO *]` | | `uri-config` (`c2`) | | |-------------|------| | Description | Malware configuration C&C (Command & Control), extracted by Spectra Core. C&C infrastructure is used to control malware, particularly botnets. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `c2:*dns*`List (any of the values): `uri-config:[dydns.org, hldns.ru]` | | `uri-dynamic` | | |-------------|------| | Description | Search for files by URI strings (URLs, domains) detected by ReversingLabs Dynamic Services. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-dynamic:mozilla.org*`List (any of the values): `uri-dynamic:[*.tor,*.onion,*.exit]` | | `uri-source` (`itw`) | | |-------------|------| | Description | Search for files by the URI source from which they were downloaded. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-source:*warez*`List (any of the values): `itw:[softonic.com, *cnet.com]` | | `uri-static` | | |-------------|------| | Description | Search for files by URI strings (URLs, domains) detected by Spectra Core. Case-insensitive wildcard matching is supported. | | Examples | Wildcard: `uri-static:mozilla.org*`List (any of the values): `uri-static:[*.tor,*.onion,*.exit]` | | `vertical` | | |-------------|------| | Description | Search for files by the type of vertical feed in which they were found. Case-insensitive wildcard matching is supported. | | Examples | Exact: `vertical:ransomware`List (any of the values): `vertical:[ransomware,apt,financial]` | ## Search query ### Request ``` POST /api/search/v1/query ``` This query returns a **\** records of new samples matching the search criteria sent in the request. If more than **\** records match the requested criteria, the response will have a **next_page** field, which can be used in the request to fetch the next page with up to **\** results. The maximum amount of API results that can be returned for a search query is 100,000. To avoid going over the maximum limit of results, set the increment limit to 100, and stop incrementing when the response contains `more_pages = false` value, or the response status code is 400 Bad Request. #### Request body ``` { "query": "string", "page": 0, "records_per_page": 0, "format": "string", "sort": "string" } ``` - `query` - User query in [string](#string-query) or [JSON](#json-query) format. - Required - `page` - Possibility to select a page number when there are more than **\** samples in the result. Defaults to first page (**"page": 1**) if omitted. The maximum amount of pages that can be fetched is the overall limit of results (100000) divided by the requested amount of results per page. For example, if the requested amount of results per page is 1000, the maximum amount of pages is 100. When there are no more results, the **more_pages** value in the response will be false. If the requested page doesn't exist, or the overall amount of results would be over 100000, the response "Max limit reached" with status code 400 is returned. - Optional - `records_per_page` - The number of records returned in the response. Defaults to 10000 if omitted - Optional - `format` - Possibility to choose an optional return format. Allowed values are **xml** (default) and **json**. - Optional - `sort` - Possibility to sort results by one of these fields: **sha1**, **firstseen**, **threatname**, **sampletype**, **filecount**, **size**. Query results can be sorted in ascending or descending order by using the asc or desc keywords (example: **"sort": threatname asc**). By default, the results are sorted by **firstseen** date in descending order (most recent to oldest). To ensure optimal sorting and paging of large datasets, the results are sorted in sequential 10000 row blocks. - Optional ### Quotation marks Quotation marks match an exact string, and are necessary if the string contains spaces or any other restricted characters. To submit a query in quotation marks, they have to be escaped (for example, `filename:\"Visual Studio Installer\"`). Note that this matches only those samples that are called exactly "Visual Studio Installer", and will not find "Visual Studio Installer.exe". To match files by substrings, use wildcard characters. If the query doesn't contain any restricted characters, quotation marks can be omitted without changing the results. ### Wildcard characters The character `*` matches any sequence of characters. The character `?` matches any single character. Wildcards cannot be mixed with quotation marks, as that makes them a literal part of the string to match. To properly use wildcards, submit the query without escaping the quotation marks (`threatname:"ThreatNam*"`). In this case, search will return all `ThreatName` samples, but also `ThreatName2` or anything else that matches the wildcard placement. Another example, using both the asterisk and the question mark: `threatname:"*ThreatName?"` matches "SomeThreatName" and "OtherThreatName1". With escaped quotes, `threatname:\"*ThreatName?\"` matches `*ThreatName?`, and nothing else. Wildcards can be placed anywhere in the query. The following example searches for any word that starts with `p` and ends with `ton` in the **threatname** field: `threatname:p*ton`. ### Restricted Words and Characters All restricted words and characters should be escaped with double quotation marks in the search expression. Backslashes (`\`) also have to be escaped, but don't have to be inside quotation marks. **Example:** a query contains one of the restricted characters ( `[`, `]`, `(`, `)`, `:`). This example also contains an escaped `\` character. ``` pdb:\"C:\\Windows*\" ``` **Example:** a query contains one of the restricted words (`AND`, `OR`, `NOT`) ``` cert-subject-name:\"AND\" ``` If the search query contains spaces, use (escaped) double quotation marks around it. ``` cert-subject-org:\"microsoft corporation\" ``` ### String query String that represents the user's search query. Example request body: ``` { "query": ": : ...", "page": 1, "records_per_page": 1000, "format": "xml" } ``` #### Expression Syntax Every search expression must contain at least one keyword and one criterion. Search expressions are built according to the following formula: **\:\**. **field_name** The name of the parameter queried on. Allowed values are listed in the table of `supported-keywords`. **field_value** The value against which the parameter is tested. The following operators are supported: **Equals operator** Syntax: ``` : ``` Examples: ``` classification:malicious available:true firstseen:2018-01-01T00:00:00Z ``` **Range operator** Range of values between **from_value** and **to_value**, including the upper and lower boundary. An asterisk (\*) may be used for either one or for both endpoints to specify an open-ended range query. Syntax: ``` :[ TO ] :[ TO *] :[* TO ] ``` Examples: ``` firstseen:[2018-01-01T00:00:00Z TO 2018-01-02T00:00:00Z] threatlevel:[0 TO *] size:[* TO 500] ``` **In operator** The value of a field equals any value in the specified list. Syntax: ``` :[, , ...] ``` Examples: ``` classification:[malicious, suspicious] ``` #### Creating Multi-keyword Search Expressions Search operators and parentheses can be used to combine multiple keywords and create advanced search expressions. The following search operators are supported: **AND**, **OR**, **NOT**. If an operator is not provided, **AND** is used as the default. Operators are case-insensitive, so the following queries all return the same result: ``` firstseen:2018-01-01T00:00:00Z AND classification:malicious firstseen:2018-01-01T00:00:00Z and classification:malicious firstseen:2018-01-01T00:00:00Z classification:malicious ``` The **NOT** operator excludes search results that match the defined criteria. In the following example, malicious and suspicious files will be excluded from the results. ``` av-detection:linux NOT classification:[malicious, suspicious] ``` The **OR** operator can be used to look for any of the values supported by a single keyword: classification:suspicious OR classification:malicious It can also be used to look for any of the different keywords and their values: ``` pdb:JigsawRansomware.pdb OR uri:"http://btc.blockr.io/api/v1/" ``` Note that the **OR** operator cannot be used instead of a comma when searching for a list of values. The following example is **not** a valid query: ``` av-detection:[emotet OR wannacry] ``` **Parentheses** can be used to combine keywords. The following two queries show how to format the same expression using square brackets versus parentheses: ``` firstseen:`2018`-01-01T00:00:00Z av-detection:[trojan,wannacry] firstseen:2018-01-01T00:00:00Z (av-detection:trojan OR av-detection:wannacry) ``` Apart from using parentheses for the same keyword, you can use them to combine multiple different keywords, operators, and even a range: ``` firstseen`:2018-01-01T00:00:00Z (av-detection:trojan AND type:binary NOT positives:[* TO 3]) ``` List of search_field objects that represent the user query. Each search_field object is a part of the whole query. Example: ``` json { "query":[ { "name": , "criteria": , "value": }, { "name": , "criteria": , "value": , "operator": }, … ], "page": 1, "records_per_page": 1000, "format": "xml" } ``` ### JSON query Instead of using a string, the `query` field can accept an array of objects structured like so: ``` { "name": , "criteria": , "value": , "operator": } ``` - **name (required)** The name of the parameter queried on. Allowed values are listed in the table of `supported-keywords`. - **value (required)** The value against which the parameter is tested. The structure of the value field depends on the criteria field - **criteria (required)** Operator used for testing condition. Allowed values for this field are: | | | |-----------|---------------------------------------------------------------------| | **eq** | equal | | **neq** | does not equal | | **gt** | greater than | | **gte** | greater or equal | | **lt** | less than | | **lte** | less than or equal | | **range** | range of values between **from_value** and **to_value** | | **in** | the value of a field equals any value in the specified list | | **nin** | the value of a field does not equal any value in the specified list | For **eq**, **neq**, **gt**, **gte**, **lt**, and **lte** the field value is a simple string, integer or datetime, depending on **\**. Example: ``` { "name":"classification", "criteria":"eq", "value": "malicious" } ``` For **range** criteria, the field value is a JSON object with the structure: ``` { "from": , "to": } ``` An asterisk (\*) may be used for either one or for both endpoints to specify an open-ended range query. Example: ``` { "name":"firstseen", "criteria":"range", "value": { "from": "2017-06-20T00:00:00Z", "to": "*" } } ``` For **in** and **nin** criteria, field value is a list of string, integer or datetime values. Example: ``` { "name":"classification", "criteria":"in", "value": ["malicious", "suspicious"] } ``` - **operator (optional)** Operator is used to combine two search fields (it is not necessary for the first element in the list). Operators are case-insensitive. Allowed values are **AND** and **OR**. If an operator is not provided, **AND** will be used. Example: ``` [ { "name": "classification", "criteria": "eq", "value": "malicious" }, { "name": "classification", "criteria": "eq", "value": "suspicious", "operator": "OR" } ] ``` This can be interpreted as: **classification:malicious OR classification:suspicious** ### Wildcard Characters The character `*` matches any sequence of characters. The character `?` matches any single character. The following example searches for any word that starts with **"p"** and ends with **"ton"** in the threatname field. ``` { "name":"threatname", "criteria":"eq", "value":"p*ton" } ``` ### Field Restrictions | **Field Name** | actor * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | android-app-name * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | android-features * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | android-import * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | android-package * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | android-permission * | | -------------- | -------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | appid-company-name (appid-author) | | -------------- | --------------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | appid-description * | | -------------- | ------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | appid-product-name | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | appid-product-type (appid-category) * | | -------------- | ------------------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | attack-tactic | | -------------- | ----------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | attack-technique | | -------------- | ------------------ | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | av-count (positives, p, antivirus) | | -------------- | ---------------------------------- | | Type | integer | | String Query | eq, range, in | | JSON Query | eq, range, gt, gte, lt, lte, in | | **Field Name** | av-detection * (engines *) | | -------------- | -------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | av-(name) * ((name) *) | | -------------- | ---------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | available (in, shareable) | | -------------- | ------------------------- | | Type | boolean | | String Query | eq | | JSON Query | eq | | **Field Name** | browser-package * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-issuer-country * | | -------------- | --------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-issuer-name * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-issuer-org * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-issuer-unit * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-serial | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | cert-subject-country * | | -------------- | ---------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-subject-name * | | -------------- | ------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-subject-org * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-subject-unit * | | -------------- | ------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | cert-thumbprint | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | classification | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | dex-class-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dex-method-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-author * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-description (doc-description) * | | -------------- | ---------------------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-pages (doc-pages) | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | document-subject * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-title * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-version * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | document-language * | | -------------- | ------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | domain * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-assembly * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-method-name * | | -------------- | -------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-module-id * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-module-name * | | -------------- | -------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-pinvoke-function * | | -------------- | ------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-pinvoke-import * | | -------------- | ----------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-resource * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | dotnet-type-name * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | elf-section-count | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | elf-section-name * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | elf-segment-sha1 (elf-segment-hash) | | -------------- | ----------------------------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | elf-symbol * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-from * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-static * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-subject * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-to * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-x-key * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | email-x-value * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | exif * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | exploit * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | filecount | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | filename * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | firstseen (fs) | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | hashes | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | imphash | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | indicators | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | ios-app-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ios-author * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ios-package * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ipv4 * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ipv4-dynamic * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ipv4-static * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ipv6 * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | ipv6-static * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | lastanalysis (la) | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | lastseen (ls) | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | macho-import * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | macho-section-count | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | macho-section-name * | | -------------- | -------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | macho-segment (macho-segment-name) * | | -------------- | ------------------------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | macho-segment-count | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | macho-segment-sha1 (macho-segment-hash) | | -------------- | --------------------------------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | macho-symbol * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | md5 | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | mutex | | -------------- | ----------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | mutex-config | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | mutex-dynamic | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | pdb-path * (pdb *) | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-company-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-copyright * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-description * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-export * (exports) | | -------------- | --------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-function * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-import * (imports) | | -------------- | --------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-language * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-original-name * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-overlay-sha1 (pe-overlay-hash) | | -------------- | --------------------------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | pe-product-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-resource * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-resource-sha1 (pe-resource-hash) | | -------------- | ----------------------------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | pe-section-count | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | pe-section-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | pe-section-sha1 (pe-section-hash) | | -------------- | --------------------------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | pe-timestamp pets | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | sampletype * (filetype *, type *, format *) | | -------------- | ------------------------------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | sha1 | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | sha256 | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | signer-valid-from (cert-valid-from) | | -------------- | ----------------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | signer-valid-to (cert-valid-to) | | -------------- | ------------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | ssdeep | | -------------- | ---------- | | Type | string | | String Query | eq | | JSON Query | eq | | **Field Name** | similar-to | | -------------- | ---------- | | Type | string | | String Query | eq | | JSON Query | eq, neq | | **Field Name** | size | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | software-author * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | software-description * | | -------------- | ---------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | software-package * | | -------------- | ------------------ | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | submissions (s) | | -------------- | --------------------------- | | Type | integer | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | tag | | -------------- | ---------------- | | Type | string | | String Query | eq, in | | JSON Query | eq, neq, in, nin | | **Field Name** | tag-yara * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | taggant-name * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | taggant-valid-from | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | taggant-valid-to | | -------------- | --------------------------- | | Type | datetime | | String Query | eq, range | | JSON Query | eq, range, gt, gte, lt, lte | | **Field Name** | third-party-library * | | -------------- | --------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | third-party-publisher * | | -------------- | ----------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | tlsh | | -------------- | ---------- | | Type | string | | String Query | eq | | JSON Query | eq | | **Field Name** | threatlevel | | -------------- | ------------------------------- | | Type | integer | | String Query | eq, range, in | | JSON Query | eq, range, gt, gte, lt, lte, in | | **Field Name** | threatname * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | trustfactor | | -------------- | ------------------------------- | | Type | integer | | String Query | eq, range, in | | JSON Query | eq, range, gt, gte, lt, lte, in | | **Field Name** | uri * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | uri-config * (c2 *) | | -------------- | ------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | uri-dynamic * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | uri-source * (itw *) | | -------------- | -------------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | uri-static * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | | **Field Name** | vertical * | | -------------- | ----------------- | | Type | string | | String Query | eq*, in | | JSON Query | eq*, neq, in, nin | ### Response Format `rl.web_search_api` ```json { "total_count": 0, "next_page": 0, "more_pages": true, "sample_count": 0, "entries": [] } ``` - `total_count` - Number of samples that match the search criteria. - `next_page` - Page number that can be used in the request to retrieve the next batch of results. - `more_pages` - Indicates whether there are multiple batches of results available. - `sample_count` - Number of samples in the response. ----------------------------------------------------------------------- `rl.web_search_api.entries` ```json { "sha1": "string", "sha256": "string", "md5": "string", "classification": "string", "threatlevel": 0, "trustfactor": 0, "threatname": "string", "size": 0, "available": true, "antivirus": 0, "firstseen": "string", "lastseen": "string", "sampletype": "string", "filename": "string", "filecount": 0 } ``` - `sha1` - The SHA1 hash of the analyzed sample. - `sha256` - The SHA256 hash of the analyzed sample. - `md5` - The MD5 hash of the analyzed sample. - `classification` - File classification. Possible values are MALICIOUS, SUSPICIOUS, KNOWN, UNKNOWN. - `threatlevel` - Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). **Applies to malicious and suspicious samples only**. - `trustfactor` - Trustworthiness indicator for goodware samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). **Applies to known samples only**. - `threatname` - Complete malware threat name. Conforms to [ReversingLabs Malware Naming Standard](#appendix-a---reversinglabs-malware-naming-standard): *platform-subplatform.type.familyname*. - `size` - Sample size in bytes, specified as an integer. Accepts integers up to 2147483647. - `available` - Indicates whether the analyzed sample was available or not (at the time of the analysis). - `antivirus` - The number of antivirus scanners that have detected the sample as malicious, specified as an integer. - `firstseen` - Indicates the date and time when the file was first uploaded to the system, or when it was scanned for the first time. - `lastseen` - Indicates the date and time when the file was last uploaded to the system, or when it was scanned for the last time. - `sampletype` - Detected sample type for the requested sample. - `filename` - The name of the file. - `filecount` - The number of unpacked files the sample contains (if it's a container). - `tlsh` - The TLSH fuzzy hash of the sample. **Returned only when using the `tlsh` search keyword.** - `distance` - The TLSH distance between the queried hash and the sample's hash, expressed as an integer between 0 and 150. Lower values indicate higher similarity. **Returned only when using the `tlsh` search keyword.** - `ssdeep` - The SSDEEP fuzzy hash of the sample. **Returned only when using the `ssdeep` search keyword.** - `similarity` - The SSDEEP similarity score between the queried hash and the sample's hash, expressed as an integer between 60 and 100. Higher values indicate higher similarity. **Returned only when using the `ssdeep` search keyword.** ### Empty Response Format If no records for given criteria are available, the following response is returned: ``` json { "rl":{ "web_search_api":{ "total_count":0, "next_page":null, "more_pages": false, "sample_count":0, "entries":[] } } } ``` ## Examples ### Example 1 - Fetching new Win32 malware from 2017-06-20 00:00:00 till 2017-06-21 00:00:00 `/api/search/v1/query` POST data: String query: ``` { "query":"firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z] classification:[malicious, suspicious] threatname:win32" } ``` JSON query: ``` json { "query":[ { "name":"firstseen", "criteria":"range", "value":{ "from":"2017-06-20T00:00:00Z", "to":"2017-06-21T00:00:00Z" } }, { "name":"classification", "criteria":"in", "value":[ "malicious", "suspicious" ] }, { "name":"threatname", "criteria":"eq", "value":"Win32" } ] } ``` ### Example 2 - The same query from Example 1 with response format as JSON and 100 records per page `/api/search/v1/query` POST data: String Query: ``` { "query":"firstseen:[2017-06-20T00:00:00Z TO 2017-06-21T00:00:00Z] classification:[malicious, suspicious] threatname:win32", "format":"json", "records_per_page":100 } ``` JSON query: ``` json { "query":[ { "name":"firstseen", "criteria":"range", "value":{ "from":"2017-06-20T00:00:00Z", "to":"2017-06-21T00:00:00Z" } }, { "name":"classification", "criteria":"in", "value":[ "malicious", "suspicious" ] }, { "name":"threatname", "criteria":"eq", "value":"Win32" } ], "format":"json", "records_per_page":100 } ``` ### Example 3 - Fetching the next 100 results for the same query `/api/search/v1/query` POST data: String Query: ``` { "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 } ``` JSON query: ``` json { "query":[ { "name":"firstseen", "criteria":"range", "value":{ "from":"2017-06-20T00:00:00Z", "to":"2017-06-21T00:00:00Z" } }, { "name":"classification", "criteria":"in", "value":[ "malicious", "suspicious" ] }, { "name":"threatname", "criteria":"eq", "value":"Win32" } ], "page":2, "format":"json", "records_per_page":100 } ``` ## Additional Information ### Appendix A - ReversingLabs Malware Naming Standard ### Appendix B - Supported Sample Types **Sample Type** | | | | |-------------|----------------|-----------------| | Audio | Binary | DEX | | Document | ELF32 Big | ELF32 Little | | ELF64 Big | ELF64 Little | Image | | MZ | MachO32 Big | MachO32 Little | | MachO64 Big | MachO64 Little | Media Container | | None | PE | PE+ | | PE16 | PE32 | PE32+ | | Text | Unknown | Video | **Sample Type/Subtype** | | | | |-------------------------|--------------------------|--------------------------| | Audio/Archive | Audio/HTML | Audio/None | | Audio/Unknown | Binary/Archive | Binary/None | | Binary/Unknown | Binary/.Net | Binary/.Net | | Binary/.Net | Binary/Executable | Binary/HTML | | Binary/Relocatable | Binary/SO | Binary/VXD | | DEX/Exe | Document/Archive | Document/HTML | | Document/None | Document/Unknown | ELF32 Big/Core | | ELF32 Big/Exe | ELF32 Big/None | ELF32 Big/Relocatable | | ELF32 Big/SO | ELF32 Little/Core | ELF32 Little/Exe | | ELF32 Little/None | ELF32 Little/Relocatable | ELF32 Little/SO | | ELF64 Big/Core | ELF64 Big/Exe | ELF64 Big/None | | ELF64 Big/Relocatable | ELF64 Big/SO | ELF64 Little/Core | | ELF64 Little/Exe | ELF64 Little/None | ELF64 Little/Relocatable | | ELF64 Little/SO | Image/Archive | Image/Dll | | Image/Exe | Image/None | Image/Unknown | | Image/BMP | Image/DCM | Image/GIF | | Image/JNG | Image/JPEG | Image/MNG | | Image/PBM | Image/PCT | Image/PGM | | Image/PNG | Image/PPM | Image/PSD | | Image/RAS | Image/TIFF | Image/XCF | | Media_Container/None | MZ/DOS | MachO32 Big/Bundle | | MachO32 Big/Exe | MachO32 Big/None | MachO32 Big/SO | | MachO32 Little/Bundle | MachO32 Little/Core | MachO32 Little/Exe | | MachO32 Little/None | MachO32 Little/SO | MachO64 Big/Bundle | | MachO64 Big/Exe | MachO64 Big/None | MachO64 Big/SO | | MachO64 Little/Bundle | MachO64 Little/Core | MachO64 Little/Exe | | MachO64 Little/None | MachO64 Little/SO | Media Container/DOS | | Media Container/Dll | Media Container/Exe | Media Container/None | | Media Container/Unknown | None/None | None/DLL | | None/DOS | None/Exe | None/HTML | | None/Relocatable | None/SO | None/VXD | | PE+/.Net Dll | PE+/.Net Exe | PE+/Dll | | PE+/Exe | PE/.Net Dll | PE/.Net Exe | | PE/Dll | PE/Exe | PE/VXD | | PE16/Dll | PE16/Exe | PE32+/DLL | | PE32+/Executable | PE32/DLL | PE32/Executable | | PE32/VXD | Text/Acrobat JavaScript | Text/ActionScript | | Text/Assembly | Text/Batch | Text/CCPP | | Text/Ada | Text/AutoIt | Text/Archive | | Text/CMake | Text/CSS | Text/CSharp | | Text/Clojure | Text/CoffeeScript | Text/Common Lisp | | Text/D | Text/Dart | Text/Eiffel | | Text/Emacs Lisp | Text/Erlang | Text/FORTRAN | | Text/FSharp | Text/Factor | Text/Go | | Text/Groovy | Text/HTML | Text/Haskell | | Text/Java | Text/JavaScript | Text/LLVM | | Text/Lua | Text/Makefile | Text/Matlab | | Text/Nix | Text/None | Text/OCaml | | Text/Objective-C | Text/PHP | Text/Pascal | | Text/Perl | Text/Perl6 | Text/PowerShell | | Text/Python | Text/R | Text/Ruby | | Text/Scala | Text/Scheme | Text/Shell | | Text/Smalltalk | Text/Smarty | Text/Swift | | Text/Tcl | Text/TeX | Text/TypeScript | | Text/Unknown | Text/VBA | Text/VHDL | | Text/Verilog | Text/VimL | Text/Visual Basic | | Unknown/Unknown | Video/Archive | Video/None | | Video/Unknown | | | ### Appendix C - Available Languages for PE and Document Formats | | | | |---------------------|-----------------------------|----------------------------| | afrikaans | albanian | arabic algeria | | arabic bahrain | arabic egypt | arabic iraq | | arabic jordan | arabic kuwait | arabic lebanon | | arabic libya | arabic morocco | arabic oman | | arabic qatar | arabic saudi arabia | arabic syria | | arabic tunisia | arabic uae | arabic yemen | | arabic | armenian | assamese | | azeri cyrillic | azeri latin | azeri | | basque | belarusian | bengali | | breton | bulgarian | catalan | | chinese hongkong | chinese macau | chinese simplified | | chinese singapore | chinese traditional | chinese | | cornish | croatian | croatian | | czech | danish | default | | divehi | dutch belgian | dutch surinam | | dutch | dutch | english aus | | english belize | english can | english caribbean | | english eire | english jamaica | english nz | | english philippines | english south africa | english trinidad | | english uk | english us | english zimbabwe | | english | esperanto | estonian | | faeroese | farsi | finnish | | french belgian | french canadian | french luxembourg | | french monaco | french swiss | french | | french | gaelic manx gaelic scottish | gaelic | | gaelic | galician | georgian | | german austrian | german liechtenstein | german luxembourg | | german swiss | german | german | | greek | gujarati | hebrew | | hindi | hungarian | icelandic | | indonesian | invariant | italian swiss | | italian | italian | japanese | | kannada | kashmiri india | kashmiri sasia | | kashmiri | kazak | konkani | | korean | korean | kyrgyz | | latvian | lithuanian classic | lithuanian | | lithuanian | macedonian | malay brunei darussalam | | malay malaysia | malay | malayalam | | maltese | manipuri | maori | | marathi | mongolian | nepali india | | nepali | neutral | norwegian bokmal | | norwegian nynorsk | norwegian | oriya | | polish | portuguese brazilian | portuguese | | portuguese | punjabi | rhaeto_romance | | romanian moldavia | romanian | romanian | | russian moldavia | russian | russian | | saami | sanskrit | serbian cyrillic | | serbian latin | serbian | sindhi | | slovak | slovenian | sorbian | | spanish argentina | spanish bolivia | spanish chile | | spanish colombia | spanish costa rica | spanish dominican republic | | spanish ecuador | spanish el salvador | spanish guatemala | | spanish honduras | spanish mexican | spanish modern | | spanish nicaragua | spanish panama | spanish paraguay | | spanish peru | spanish puerto rico | spanish uruguay | | spanish venezuela | spanish | spanish | | sutu | swahili | swedish finland | | swedish | swedish | syriac | | sys default | tamil | tatar | | telugu | thai | tsonga | | tswana | turkish | ukrainian | | urdu india | urdu pakistan | urdu | | uzbek cyrillic | uzbek latin | uzbek | | venda | vietnamese | walon | | welsh | xhosa | zulu | ### Appendix D - Supported Tags **Generic tags - can be applied to many file formats** | | | |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| | access-control-information | The file contains access control descriptors such as file permissions, group memberships or similar information about a securable object | | anonymous-email | The file contains e-mail addresses from anonymous e-mail providers | | cert-appendix | The file contains additional data after the certificate | | cert-bad-timestamp | The file is digitally signed with a certificate that has a bad timestamp | | cert-expired | The file's certificate chain has at least one expired certificate | | cert-impersonate | The file is digitally signed with a certificate that impersonates one of well-known entities (e.g. Microsoft or Google) | | cert-invalid | The file was signed with an invalid certificate (it didn't pass the validation process) | | cert-malformed | The file is digitally signed with a certificate that was malformed | | cert-revoked | The file is digitally signed with a certificate that has been revoked | | cert-revoked-aa-compromise | The file is digitally signed with a certificate that has been revoked due to AA compromise | | cert-revoked-affiliation-changed | The file is digitally signed with a certificate that has been revoked due to change in affiliation | | cert-revoked-ca-compromise | The file is digitally signed with a certificate that has been revoked due to CA compromise | | cert-revoked-cert-hold | The file is digitally signed with a certificate that has been put on hold (the signer has been suspended) | | cert-revoked-cessation-of-operation | The file is digitally signed with a certificate that has been revoked because the signer has ceased its operations | | cert-revoked-key-compromise | The file is digitally signed with a certificate that has been revoked due to private key compromise | | cert-revoked-privilege-withdrawn | The file is digitally signed with a certificate that has been revoked because the signer privilege has been withdrawn | | cert-revoked-remove-from-crl | The file is digitally signed with a certificate that has been removed from the revocation list | | cert-revoked-superseded | The file is digitally signed with a certificate that has been revoked because it has been superseded | | cert-revoked-unspecified | The file is digitally signed with a certificate that has been revoked due to unspecified reason | | cert-self-signed | The file is digitally signed with a self-signed certificate (e.g. JAR or APK) | | cert-signed | The file is digitally signed with a certificate (signature may or may not be valid) | | cert-signed-after-expiration | The file was digitally counter-signed after at least one certificate in certificate chain expired | | cert-signed-after-revocation | The file is digitally signed with a certificate that has been revoked at the time of signing | | cert-untrusted | The file is digitally signed with a certificate that is valid, but its root CA certificate is not in the Spectra Core certificate store | | cert-weak-crypto | The file was digitally signed with certificates using an old hashing algorithm (e.g. MD5) or with a short key | | contains-archive | The file contains one or more archive files (such as ZIP, RAR, Jar) | | contains-document | The file contains one or more document files | | contains-elf | The file contains one or more ELF (Executable and Linkable Format) files | | contains-macho | The file contains one or more Mach-O files | | contains-pe | The file contains one or more PE (Portable Executable) files | | contains-script | The file contains one or more script files | | cryptocurrency | The file has cryptocurrency-related indicators (e.g. accesses BitCoin wallet files) | | dde | The file has Dynamic Data Exchange capabilities that may be used to interact with other applications | | desktop | The file appears to be a desktop application (e.g. PE or ELF) | | email-outlook | The file has Outlook-related indicators (e.g. accesses mailbox files, credentials) | | email-pattern | The file has generic e-mail-related indicators (e.g. accesses mailbox files, credentials) | | email-thunderbird | The file has Thunderbird-related indicators (e.g. accesses mailbox files, credentials) | | encrypted | Contains encrypted files (e.g. password-protected archive) | | entropy-high | The file has unusually high entropy (i.e. entropy \> 7) | | entropy-zero | The file is zero-filled (full of 00 bytes) | | exif | The file has EXIF metadata (such as camera information or GPS metadata) | | geotagging | The file has EXIF metadata containing GPS coordinates | | guid-activex-killbit | The file contains ActiveX GUIDs with the Kill-Bit flag set | | im-skype | The file has Skype-related indicators (e.g. accesses chat history, credentials) | | image-corrupt | The image is corrupt because of some format discrepancy (e.g. invalid segment size) | | image-malformed | The image is malformed (e.g. frame dimension is zero) | | image-segment-duplicate | The image has a duplicate segment | | image-segment-unexpected-location | An image segment has been found in an unexpected location | | image-segment-unknown | An unknown image segment has been encountered | | linguist | The file's subtype was determined by a ReversingLabs machine learning model | | machine-learning | The file was classified by a ReversingLabs machine learning model | | nsis-table-invalid-offset | The NSIS installer is corrupt due to invalid table offset | | nsis-table-invalid-size | The NSIS installer is corrupt due to invalid table size | | ntfs-alternate-data-stream | The file contains data which was part of an NTFS Alternate Data Stream | | obfuscated | The file contains obfuscated code or data | | probably-packed | A heuristic method determined that the PE file may be packed | | overlay | The file has an overlay (appended data at the file's end) - applies only to PE files | | password | The file is password-protected (e.g. a password-protected archive) | | ransomware-artifact | The file contains artifacts associated with ransomware (e.g. mail addresses, domains) | | ransomware-encrypted | The file was encrypted by known ransomware (e.g. TeslaCrypt encrypted files) | | script | The file appears to be a script (e.g. shell or Javascript) | | sql-query | The file contains generic SQL queries | | ssh-key | The file can use or modify SSH keys | | stego | The file is a result of stego extraction | | stego-compressed | The file contains compressed embedded PE files | | stego-embedded | The file contains plain embedded PE files | | stego-encoded | The file contains encoded embedded PE files | | stego-encrypted | The file contains encrypted embedded PE files | | uri-banking-website | The file contains URLs related to banking and monetary institutions | | uri-credentials | The file contains URLs that embed sign-in credentials in plaintext due to protocol requirements | | uri-deceptive-file | The file contains URLs that point to executable content hidden behind double extensions | | uri-domain-blacklisted | The file contains URLs that point to a known blacklisted domain | | uri-domain-homoglyph | The file contains URLs that try to trick the user into thinking they are visiting a trusted domain | | uri-domain-punycode | The file contains URLs that try to trick the user into thinking they are visiting a trusted domain | | uri-domain-spoofed | The file contains URLs that try to trick the user into thinking they are visiting a trusted domain | | uri-domain-typosquat | The file contains URLs that try to trick the user into thinking they are visiting a trusted domain | | uri-dynamic-dns | The file contains URLs pointing to domains hosted on dynamic DNS | | uri-hostname-length | The file contains URLs pointing to domains that are unusually long | | uri-interesting-file | The file contains URLs that point to interesting files or file extensions | | uri-ip-address | The file contains URLs pointing to webservers hosted on IP addresses | | uri-malicious-redirect | The file contains URLs that redirect to malicious domains | | uri-malware-regex | The file contains URLs that match a known malware regex pattern | | uri-onion-website | The file contains URLs pointing to domains hosted on TOR network | | uri-open-redirect | The file contains URLs that redirect to other domains | | uri-path-length | The file contains URLs pointing to paths that are unusually long | | uri-path-spoofed | The file contains URLs that point to a known sign-in path but don't reside on the trusted domain | | uri-security-website | The file contains URLs related to security product vendors | | uri-shortened | The file contains shortened URLs | | uri-subdomain-count | The file contains URLs pointing to paths that contain excessive number of subdomains | | uri-suspicious-path | The file contains URLs that contain a suspicious path section | | uri-suspicious-port | The file contains URLs that utilize non-standard ports for the specified protocol | | uri-suspicious-query | The file contains URLs that include suspicious SQL query commands | | uri-suspicious-tld | The file contains URLs pointing to domains hosted on suspicious TLDs | **Behavior tags - describe behavior of executables, documents, scripts, and mobile applications** | | | |--------------------------------|-----------------------------------------------------------------------------------------------------| | account-settings-tamper | The file can tamper with user account settings | | autorun | The file can tamper with autorun settings (e.g. autorun registry keys, autorun locations) | | av-disable | The file can disable services related to security products | | av-impersonate | The file can impersonate services related to security products | | av-service-detect | The file can detect services related to security products | | av-tamper | The file can tamper with services related to security products | | backup-tamper | The file can tamper with backup (e.g. erases backup copies, tampers with backup settings) | | bitlocker-tamper | The file can tamper with BitLocker settings | | data-exfiltration | The file can exfiltrate various data (e.g. stored credentials, mailbox files, configuration data) | | dns-tamper | The file can tamper with DNS configuration | | dns-use | The file can use the DNS protocol (e.g. issues DNS queries, locates network services) | | file-download | The file has the capability to download files | | file-upload | The file has the capability to upload files | | firewall-tamper | The file can tamper with firewall settings | | ftp-use | The file can use the FTP protocol (e.g. to upload files, to download files) | | hosts-modifier | The file can tamper with hosts file or registry keys | | impersonate-native | The file can impersonate native services (e.g. impersonates Windows Explorer) | | irc-use | The file can use the IRC communication protocol | | log-tamper | The file can tamper with logging configuration or log files | | netntlm-hash-leak | The file contains references to SMB resources that leak NetNTLM hashes | | network-settings-tamper | The file can tamper with network settings | | nfs-tamper | The file can tamper with NFS settings | | privacy-intrusion | The file has indicators related to privacy intrusion (e.g. takes screenshots, monitors users input) | | privilege-escalation | The file has the capability to elevate user privileges | | process-injection | The file has the capability to write into other processes | | process-termination | The file can terminate other processes | | proxy | The file can access or modify proxy settings | | registry-tamper | The file can tamper with the registry | | security-settings-tamper | The file can tamper with various security settings (e.g. security or audit policies) | | service-disable | The file can disable services | | smb-tamper | The file can tamper with the SMB protocol | | startup-tamper | The file can tamper with startup settings (e.g. Windows bootup process) | | storage-settings-tamper | The file can tamper with storage settings | | storage-tamper | The file can tamper with external storage | | uac-bypass | The file can bypass User Account Control | | update-disable | The file can disable update services | | virtualization-settings-tamper | The file can tamper with virtualization settings | | vpn-tamper | The file can tamper with VPN settings | | vpn-use | The file has the capability to use VPN | | web-request | The file has the capability to generate web requests | | wmi-use | The file can use Windows Management Instrumentation (WMI) | **Application-related tags - apply only to files with application metadata (PE, ELF, OSX, DEX, …)** | | | |-------------------------|----------------------------------------------------------------------------------------------------| | arch-mips | The file's target CPU architecture is MIPS | | arch-powerpc | The file's target CPU architecture is PowerPC | | arch-sparc | The file's target CPU architecture is SPARC | | arch-x86 | The file's target CPU architecture is x86 | | arch-x86-64 | The file's target CPU architecture is x86-64 | | arch-arm-64 | The file's target CPU architecture is ARM64 | | arch-arm | The file's target CPU architecture is ARM | | codeview | The application has debugging symbols metadata | | cui | The application uses Console User Interface subsystem (applies to PE files) | | gui | The application uses Graphical User Interface subsystem (applies to PE files) | | installer | The file is an installer package | | library-ad | The application contains advertising-related libraries (e.g. Adfonic) | | library-analytics | The application contains advertising and usage analytics-related libraries (e.g. Google Analytics) | | library-audio | The application contains audio playback related libraries (e.g. Vorbis) | | library-browser | The application contains browser-related libraries | | library-cloud | The application contains cloud networking-related libraries (e.g. Dropbox) | | library-compression | The application contains compression-related libraries (e.g. Zip) | | library-crypto | The application contains cryptography-related libraries (e.g. OAuth) | | library-database | The application contains database-related libraries (e.g. MySQL) | | library-development | The application contains development-related libraries | | library-driver | The application contains driver-related libraries | | library-educational | The application contains education-related libraries | | library-email | The application contains email-related libraries | | library-entertainment | The application contains entertainment-related libraries | | library-gaming | The application contains gaming-related libraries | | library-graphics | The application contains drawing or rendering libraries (e.g. Unity) | | library-messaging | The application contains network messaging-related libraries (e.g. RabbitMQ) | | library-multimedia | The application contains multimedia-related libraries (e.g. Amazon Game Circle) | | library-networking | The applications contains network communication-related libraries (e.g. curl) | | library-productivity | The application contains productivity-related libraries | | library-security | The application contains security-related libraries | | library-social | The application contains social networking-related libraries (e.g. Facebook) | | library-utility | The application contains programming utility libraries (e.g. ICU) | | library-virtualization | The application contains virtualization-related libraries | | lolbin | The file was identified as a LoLBin (living-off-the-land binary) | | plugin | The application is plugin for particular software | | protection-aslr | The file has the Address Space Layout Randomisation exploit protection enabled | | protection-dep | The file has the Data Execution Prevention exploit protection enabled | | protection-ehc | The file has the Exception Handling Continuation exploit protection enabled | | protection-cfg | The file has the Control Flow Guard exploit protection enabled | | protection-ret | The file has the Retpoline exploit protection enabled | | protection-rfg | The file has the Return Flow Guard exploit protection enabled | | protection-mpx | The file has the Intel Memory Protection guard enabled | | protection-xfg | The file has the Extreme Flow Guard exploit protection enabled | | protection-cet | The file has the Intel Control-Flow Enforcement Technology guard enabled | | protection-sdl | The file has been compiled to follow the Secure Development Lifecycle guidelines | | protection-seh | The file has safe exception handling protection enabled | | protection-stack | The file has buffer overrun exploit protection enabled | | force-integrity | The file has integrity protection checks that prevent execution on change | | packed | The application is packed with a known packer (e.g. with UPX) | | rich-header | The application has rich header metadata (applies to PE files) | | reproducible-build | The application has been compiled in a reproducible way which invalidates all timestamps | | sfx | The file is a self-extracting archive (an application that embeds an archive) | | taggant | The application has Taggant-related metadata | | tool-hacktool | The application is used to assist hacking | | tool-steganography | The application has steganography capabilities | | uefi | The application is designed for the UEFI subsystem (applies to PE files) | | uninstaller | The application is uninstaller for particular software | | unsupported-application | The application is deprecated and no longer supported by vendor | | updater | The application is updater for particular software | | version-info | The application has version information metadata | | vulnerable-with-cve | The application has vulnerability with assigned CVE | | vulnerable-without-cve | The application has vulnerability without assigned CVE | | xbox | The application is designed for the XBOX subsystem (applies to PE files) | **Mobile-related tags - apply only to mobile applications** | | | |----------------------------|--------------------------------------------------------------------------------------------------| | android-cupcake | The mobile application uses the Android API level 3 | | android-donut | The mobile application uses the Android API level 4 | | android-eclair | The mobile application uses the Android API levels 5 to 7 | | android-froyo | The mobile application uses the Android API level 8 | | android-gingerbread | The mobile application uses the Android API levels 9 to 10 | | android-honeycomb | The mobile application uses the Android API levels 11 to 13 | | android-ice-cream-sandwich | The mobile application uses the Android API levels 14 to 15 | | android-jelly-bean | The mobile application uses the Android API levels 16 to 18 | | android-kitkat | The mobile application uses the Android API levels 19 to 20 | | android-lollipop | The mobile application uses the Android API levels 21 to 22 | | android-marshmallow | The mobile application uses the Android API level 23 | | android-nougat | The mobile application uses the Android API levels 24 to 25 | | android-oreo | The mobile application uses the Android API levels 26 to 27 | | android-pie | The mobile application uses the Android API level 28 | | android-10 | The mobile application uses the Android API level 29 | | android-11 | The mobile application uses the Android API level 30 | | mobile | The file appears to be a mobile application (e.g. Android APK or Windows Phone applications) | | mobile-custom-permissions | The mobile application has user-defined permissions | | mobile-data-access | The mobile application can read and write to the external storage on the device | | mobile-deprecated | The mobile application can abuse permissions from deprecated APIs | | mobile-gps | The mobile application can access location services | | mobile-infostealer | The mobile application can access and read information such as call logs, contacts, calendars... | | mobile-logging | The mobile application can read and modify call logs | | mobile-settings | The mobile application can change system settings on the device | | mobile-sms | The mobile application can read, write, or receive SMS messages | | mobile-telco | The mobile application can access and use the telecom connection service | | mobile-voicemail | The mobile application can access and send voicemail messages | **Malware tags - identify malware types and refer to other malware metadata** | | | |---------------|--------------------------------------------------------------------------------| | backdoor | The malware was identified as a backdoor | | c2 | The malware has an embedded malware/data configuration (e.g. C2 info or mutex) | | custom-packed | The file appears to be packed with a custom packer | | downloader | The malware was identified as a downloader | | keylogger | The malware was identified as a keylogger | | pos | The malware was identified as a point-of-sale malware | | ransomware | The malware was identified as ransomware | **Packer tags - refer to packer-related metadata** | | | |--------------------|---------------------------------------------------------------------------------| | antidebugging | The file uses anti-debugging techniques | | antidumping | The file uses anti-dumping techniques | | antiemulation | The file uses anti-emulation techniques | | antisandbox | The file uses anti-sandbox techniques | | antitracing | The file uses anti-tracing techniques | | fake-signature | The file uses fake signatures to thwart signature-based identification | | import-elimination | The packed file eliminates or has eliminated its import information | | import-redirection | The packed file redirects imports to make unpacking harder | | pe-compression | The file has a compressed payload/configuration | | pe-encryption | The file has an encrypted payload/configuration | | pe-encryption-rc4 | The file uses RC4 to encrypt the payload/configuration | | pe-encryption-tea | The file uses TEA to encrypt the payload/configuration | | polymorphic | The file was packed with a polymorphic packer | | remove-ep | The packed file has a stolen original entry point | | remove-header | The packed file removes the PE header during unpacking to make unpacking harder | | tamper-protection | The file checks for signs of modification to make unpacking harder | **Browser tags - refer to browser-related metadata** | | | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | chrome-reference | The file contains references to Chrome or Chrome-related data (e.g. accesses settings, contains Chrome user agent strings) | | chrome-tamper | The file can tamper with Chrome or Chrome-related settings (e.g. performs process injection into the Chrome executable) | | chromium-reference | The file contains references to Chromium or Chromium-related data (e.g. accesses settings, contains Chromium user agent strings) | | chromium-tamper | The file can tamper with Chromium or Chromium-related settings (e.g. performs process injection into the Chromium executable) | | firefox-reference | The file contains references to Firefox or Firefox-related data (e.g. accesses settings, contains Firefox user agent strings) | | firefox-tamper | The file can tamper with Firefox or Firefox-related settings (e.g. performs process injection into the Firefox executable) | | internet-explorer-reference | The file contains references to Internet Explorer or Internet Explorer-related data (e.g. accesses settings, contains Internet Explorer user agent strings) | | internet-explorer-tamper | The file can tamper with Internet Explorer or Internet Explorer-related settings (e.g. performs process injection into the Internet Explorer executable) | | netscape-reference | The file contains references to Netscape or Netscape-related data (e.g. accesses settings, contains Netscape user agent strings) | | netscape-tamper | The file can tamper with Netscape or Netscape-related settings (e.g. performs process injection into the Netscape executable) | | opera-reference | The file contains references to Opera or Opera-related data (e.g. accesses settings, contains Opera user agent strings) | | opera-tamper | The file can tamper with Opera or Opera-related settings (e.g. performs process injection into the Opera executable) | | safari-reference | The file contains references to Safari or Safari-related data (e.g. accesses settings, contains Safari user agent strings) | | safari-tamper | The file can tamper with Safari or Safari-related settings (e.g. performs process injection into the Safari executable) | **Classification tags - apply only to classified files** | | | |--------------------|----------------------------------------------------------------------------------------------------------------------| | cert-blacklisted | The file was digitally signed with a blacklisted certificate | | cert-whitelisted | The file was digitally signed with a whitelisted certificate | | cloud | The file was classified by ReversingLabs Malware Presence (e.g. the hash is a well-known threat) | | exploit | The file was classified by Spectra Core exploit detection from an unpacker or a validator (e.g. RTF) | | graylisting | The file was classified by graylisting (e.g. an archive containing only text files) | | hierarchy-analyzer | The file was classified by Spectra Core file hierarchy analysis (e.g. embedded executables within a document format) | | image-analyzer | The file was classified by Spectra Core image analyzer (e.g. suspicious data was found within an image) | | ricc | The file was classified by Spectra Core RICC (e.g. RHA classification, RICC rule classifications) | | signature | The file was classified by Spectra Core signature | | antivirus | The file was classified by an AntiVirus component | | ng-antivirus | The file was classified by a NextGen AntiVirus component | | yara | The file was classified by a YARA rule | **Capability tags - refer to capabilities of executables, documents, and mobile applications** | | | |---------------------------|-----------------------------------------------------------------------------------------------------------------| | capability-advertising | The file has advertising-related capabilities (e.g. AdMob) - applies to documents and mobile formats | | capability-bluetooth | The file can use Bluetooth to communicate with other devices - mobile-specific tag | | capability-camera | The file has access to the camera - applies to documents and mobile formats | | capability-cryptography | The file has cryptography-related capabilities (e.g. it can encrypt or hash data and files) | | capability-deprecated | The file uses deprecated APIs | | capability-embeds | The file has other files embedded within (e.g. an iframe or an OLE object) - document-specific tag | | capability-execution | The file has execution-related capabilities (e.g. an application can spawn new processes or threads) | | capability-filesystem | The file has filesystem-related capabilities (e.g. it can open and read files) | | capability-identification | The file has access to user or device identity - mobile-specific tag | | capability-microphone | The file has access to the microphone - applies to documents and mobile formats | | capability-networking | The file has networking-related capabilities (e.g. it can open a socket and send/receive data) | | capability-nfc | The file can use Near Field Communication (NFC) to communicate with other devices - mobile-specific tag | | capability-scripting | The file uses a scripting language (e.g. a document contains and uses macros) - document-specific tag | | capability-security | The file has security-related capabilities | | capability-social | The file has access to social components or providers (e.g. Facebook) - applies to documents and mobile formats | | capability-undocumented | The file uses undocumented functions | | capability-vpn | The file can access VPNs - mobile-specific tag | | capability-wallet | The file has access to user's wallet - mobile-specific tag | **Indicator tags - refer to indicators found in executables, documents, scripts, and mobile applications** An indicator tag will be emitted by Spectra Core only if the priority of a particular indicator is not low (i.e. priority \> 3). | | | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | indicator-anomaly | The file contains unusual characteristics (e.g. contains known whitelisted executable filenames) | | indicator-autostart | The file tampers with autostart settings (e.g. tampers with autorun locations) | | indicator-behavior | The file automatically executes activities as a user (e.g. changes username or password, prints a document) | | indicator-disable | The file disables system services (e.g. tampers with Windows Update) | | indicator-document | The file exhibits unusual activities when handling documents (e.g. PDF that creates new documents) | | indicator-evasion | The file tries to evade common debuggers, sandboxes or analysis tools (e.g. VM environment detection) | | indicator-execution | The file creates other processes or starts other applications (e.g. creates a service, installs system drivers) | | indicator-exploit | The file contains known exploits against the system | | indicator-family | The file is associated with known malicious families | | indicator-file | The file accesses other files on the filesystem in an unusual way (e.g. creates a cryptographic hash of file contents) | | indicator-flow | The file leaks sensitive information to external hosts or creates new files with sensitive data (e.g. exports PDF form fields to files) | | indicator-macro | The file contains or executes macro functions or scripts (e.g. contains UNIX shell scripts, executes actions associated with bookmarks) | | indicator-memory | The file tampers with memory of foreign processes (e.g. does process injection) | | indicator-monitor | The file has the ability to monitor host activities (e.g. accesses a list of logged on users) | | indicator-network | The file has network-related indicators (e.g. downloads a file, tampering with DNS settings) | | indicator-packer | The file contains obfuscated or encrypted code or data (e.g. base64 encoded streams) | | indicator-payload | The file extracts and launches new behavior in an unusual way (e.g. injects CSS into a page) | | indicator-permissions | The file tampers with or request additional permissions for execution (e.g. tampers with user/account privileges) | | indicator-registry | The file accesses registry and configuration files in an unusual way (e.g. tampers with Windows registry settings) | | indicator-search | The file enumerates or collects information from a system (e.g. enumerates network shares or mounted drives) | | indicator-settings | The file accesses or tampers with system settings (e.g. enumerates system information) | | indicator-signature | The file matches a known signature (e.g. contains known compression libraries, HTTP header fields) | | indicator-steal | The file steals and leaks sensitive information (e.g. accesses Outlook account information and address book) | | indicator-stealth | The file tries to hide its presence (e.g. tampers with window transparency settings, tampers with firewall settings) | **String tags - related to Spectra Core interesting strings** | | | |---------------|----------------------------------------------------------------------------------------------| | string-file | The file contains interesting strings related to the file URI scheme | | string-scp | The file contains SCP-related interesting strings | | string-callto | The file contains interesting strings related to the CallTo communication protocol | | string-h323 | The file contains interesting strings related to the H.323 multimedia communication protocol | | string-webcal | The file contains interesting strings related to iCalendar files | | string-ftp | The file contains FTP-related interesting strings | | string-http | The file contains HTTP-related interesting strings | | string-https | The file contains HTTPS-related interesting strings | | string-mailto | The file contains mailto-related interesting strings | | string-sftp | The file contains SFTP-related interesting strings | | string-sip | The file contains SIP-related interesting strings | | string-ssh | The file contains SSH-related interesting strings | | string-telnet | The file contains Telnet-related interesting strings | **Compression and crypto tags - related to identified compression and crypto content** | | | |-------------------------|--------------------------------------------------------------------------| | compression-brotli | The file has content related to Brotli compression algorithm | | compression-bzip2 | The file has content related to BZip2 compression algorithm | | compression-deflate | The file has content related to Deflate compression algorithm | | compression-dicky | The file has content related to Dicky compression algorithm | | compression-gipfeli | The file has content related to Gipfeli compression algorithm | | compression-gzip | The file has content related to GZip compression | | compression-inflate | The file has content related to Inflate compression algorithm | | compression-lz4 | The file has content related to LZ4 compression algorithm | | compression-lzfse | The file has content related to LZFSE compression algorithm | | compression-lzhuf | The file has content related to LZHUF compression algorithm | | compression-lzma | The file has content related to LZMA compression algorithm | | compression-ncompress42 | The file has content related to Ncompress42 compression algorithm | | compression-pithy | The file has content related to Pithy compression algorithm | | compression-pkzip | The file has content related to PKZIP compression algorithm | | compression-pucrunch | The file has content related to Pucrunch compression algorithm | | compression-snappy | The file has content related to Snappy compression algorithm | | compression-unlzx | The file has content related to UnLZX compression algorithm | | compression-unrarlib | The file has content related to unrarlib compression algorithm | | compression-zip | The file has content related to Zip compression | | compression-zlib | The file has content related to Zlib compression algorithm | | compression-zstd | The file has content related to Zstd compression algorithm | | crypto-acss | The file has content related to ACSS algorithm | | crypto-adler-crc32 | The file has content related to Adler-32 algorithm | | crypto-base32 | The file has content related to Base32 algorithm | | crypto-base64 | The file has content related to Base64 algorithm | | crypto-base64url | The file has content related to Base64URL algorithm | | crypto-bcrypt | The file has content related to BCrypt algorithm | | crypto-bhencode | The file has content related to Bhencode algorithm | | crypto-blake | The file has content related to Blake algorithm | | crypto-blowfish | The file has content related to Blowfish algorithm | | crypto-bmw512 | The file has content related to BMW-512 algorithm | | crypto-botan | The file has content found in Botan cryptography library | | crypto-camellia | The file has content related to Camellia algorithm | | crypto-cast | The file has content related to CAST algorithm | | crypto-cast256 | The file has content related to CAST-256 algorithm | | crypto-clefia | The file has content related to CLEFIA algorithm | | crypto-collision | The file contains blocks used in SHA-1 collision attacks | | crypto-crc32 | The file has content related to CLEFIA algorithm | | crypto-cryptlib | The file has content found in Cryptlib cryptography library | | crypto-cryptopp | The file has content found in Cryptopp (Crypto++) cryptography library | | crypto-des | The file has content related to DES algorithm | | crypto-desx | The file has content related to DESX algorithm | | crypto-dsa | The file has content related to Digital Signature Algorithm (DSA) | | crypto-ecc | The file has content related to Elliptic-curve cryptography (ECC) | | crypto-frog | The file has content related to FROG algorithm | | crypto-gnupg | The file has content found in GnuPG cryptography library | | crypto-gnutls | The file has content found in GnuTLS cryptography library | | crypto-gost | The file has content related to GOST algorithm | | crypto-haval | The file has content related to HAVAL algorithm | | crypto-hmac | The file has content related to HMAC algorithm | | crypto-ike | The file has content related to Internet Key Exchange (IKE) | | crypto-kasumi | The file has content related to KASUMI algorithm | | crypto-keccak | The file has content related to Keccak algorithm | | crypto-mars | The file has content related to MARS algorithm | | crypto-md2 | The file has content related to MD2 algorithm | | crypto-md4 | The file has content related to MD4 algorithm | | crypto-md5 | The file has content related to MD5 algorithm | | crypto-md5mac | The file has content related to MD5-MAC algorithm | | crypto-misty1 | The file has content related to Misty1 algorithm | | crypto-misty2 | The file has content related to Misty2 algorithm | | crypto-nacl | The file has content found in NaCl cryptography libray | | crypto-nettle | The file has content found in Nettle cryptography library | | crypto-noekeon | The file has content related to NOEKEON algorithm | | crypto-nss | The file has content found in NSS cryptography library | | crypto-nush | The file has content related to NUSH algorithm | | crypto-openbsd-base64 | The file has content related to OpenBSD Base64 algorithm | | crypto-openssl | The file has content found in OpenSSL cryptography library | | crypto-pbkdf2 | The file has content related to PBKDF2 algorithm | | crypto-pkcs | The file has content related to Public Key Cryptography Standards (PKCS) | | crypto-rawdes | The file has content related to RawDES algorithm | | crypto-rc2 | The file has content related to RC2 algorithm | | crypto-rijndael | The file has content related to AES (Rijandel) algorithm | | crypto-ripemd128 | The file has content related to RIPEMD-128 algorithm | | crypto-ripemd160 | The file has content related to RIPEMD-160 algorithm | | crypto-ripemd256 | The file has content related to RIPEMD-256 algorithm | | crypto-ripemd320 | The file has content related to RIPEMD-320 algorithm | | crypto-rsa | The file has content related to RSA algorithm | | crypto-rtss | The file has content related to Robust Threshold Secret Sharing (RTSS) | | crypto-safer | The file has content related to SAFER algorithm | | crypto-salsa20 | The file has content related to Salsa20 algorithm | | crypto-seed | The file has content related to SEED algorithm | | crypto-serpent | The file has content related to Serpent algorithm | | crypto-sha1 | The file has content related to SHA-1 algorithm | | crypto-sha224 | The file has content related to SHA-224 algorithm | | crypto-sha256 | The file has content related to SHA-256 algorithm | | crypto-sha384 | The file has content related to SHA-384 algorithm | | crypto-sha512 | The file has content related to SHA-512 algorithm | | crypto-shark | The file has content related to Shark algorithm | | crypto-siphash | The file has content related to SipHash algorithm | | crypto-skein | The file has content related to Skein algorithm | | crypto-skipjack | The file has content related to Skipjack algorithm | | crypto-sms4 | The file has content related to SMS4 algorithm | | crypto-sosemanuk | The file has content related to Sosemanuk algorithm | | crypto-square | The file has content related to Square algorithm | | crypto-tiger | The file has content related to Tiger algorithm | | crypto-tripledes | The file has content related to TripleDES algorithm | | crypto-turing | The file has content related to Turing algorithm | | crypto-twofish | The file has content related to Twofish algorithm | | crypto-unicorn | The file has content related to Unicorn algorithm | | crypto-uuencode | The file has content related to UUencode algorithm | | crypto-wake | The file has content related to Wake algorithm | | crypto-whirlpool | The file has content related to Whirlpool algorithm | | crypto-x509 | The file has content related to X.509 standard | | crypto-xxencode | The file has content related to XXencode algorithm | **Email specific tags - related to email content** | | | |-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | email-deceptive-sender | The display name of one of the senders contains a string resembling an email address with a domain different from the specified email address | | email-returnpath-mismatch | The "Return-Path" header contains an email address with a domain that is different from the domain of the sender | | email-replyto-mismatch | The "Reply-To" header contains an email address with a domain that is different from the domain of the sender | | email-sender-mismatch | The "Sender" header contains an email address with a domain that is different from the domain specified in the "From" header | | email-envelopefrom-mismatch | The "X-Envelope-From" header contains an email address with a domain that is different from the domain of the sender | | email-receivedtime-mismatch | The "Date" header indicates a time that is in the future or more than 1 hour before the time specified in the "Received" header | | email-spf-fail | Headers indicate that the SPF (Sender Policy Framework) check has failed | | email-dkim-fail | Headers indicate that the DKIM (Domain Keys Identified Mail) check has failed | | email-dmarc-fail | Headers indicate that the DMARC (Domain-based Message Authentication, Reporting & Conformance) check has failed | | email-pgp | Email is signed and/or encrypted using "Pretty Good Privacy" | | email-smime | Email is signed and/or encrypted using "Secure/Multipurpose Internet Mail Extensions" | | email-attachment | Email contains at least one attachment | | email-deceptive-extension | Email attachment contains multiple extensions (eg. "file.doc.exe") | | email-body-plain | Content of email body is available in plain text format | | email-body-rtf | Content of email body is available in RTF format | | email-body-html | Content of email body is available in HTML format | | email-impersonation | The display name of one of the senders impersonates a popular service | | email-signature-impersonation | Email contents impersonate an email commonly sent by a popular service | | email-urgency | Email contains multiple phrases that imply a sense of urgency | | email-sensitive-topic | Email contains multiple phrases related to sensitive topics | | email-hidden-text | Email contains a hidden block of text designed to trick classification systems | | email-subject-spam | Email subject contains phrases common to spam messages | | email-subject-phishing | Email subject is commonly used in phishing messages | | email-anonymous-provider | Email is sent using an anonymous email provider | **Format specific tags - apply only specific file formats** | | | |------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | html-frame | The HTML file contains one or more IFRAME tags | | html-form | The HTML file contains one or more FORM tags | | html-input | The HTML file contains one or more INPUT tags | | html-password | The HTML file contains one or more tags with the "password" attribute | | html-image | The HTML file contains one or more IMAGE tags | | html-canvas | The HTML file contains one or more CANVAS tags | | html-object | The HTML file contains any of the following tags: APPLET, AUDIO, EMBED, OBJECT, SOURCE, VIDEO | | html-download | The HTML file contains one or more links with the "download" attribute | | html-local-link | The HTML file contains one or more links to local files | | html-tracking | The HTML file contains one or more tracking pixels | | html-popup | The HTML file contains an A tag with target="\_blank" attribute | | html-wsffile | The HTML file contains an A tag with href="jsffile:..." or href="wsffile:..." or href="wsfhile:..." | | font-embedded | The HTML file contains embedded fonts | | deceptive-link | The HTML file contains potentially deceptive links | | platform-unix | The quarantine file was created by a security solution running on a UNIX-like operating system | | platform-windows | The quarantine file was created by a security solution running on the Microsoft Windows operating system | | quarantine-manual | The quarantine file was added to the quarantine manually by a user, not as a result of an automatic detection by the security solution | | quarantine-malicious-content | The quarantine file contains any number of remediated malicious content associated with a detected threat | | quarantine-threat-metadata | The quarantine file contains metadata describing the antivirus specific threat which triggered the remediation | --- ## Functionally Similar Files Analytics API (TCA-0321) — Spectra Intelligence The [ReversingLabs Hashing Algorithm (RHA)](https://www.reversinglabs.com/technology/reversinglabs-hash-algorithm) identifies code similarity between unknown samples and previously seen malware samples. Files have the same RHA1 hash when they are functionally similar. This API provides real-time statistics (counters) for malicious, suspicious and known samples that are functionally similar to the provided SHA1 hash at the requested precision level. Precision level represents the degree to which a file is functionally similar to another file. The following precision levels are supported - **25% and 50% for PE** and **25% for MachO and ELF executable files**. A higher precision level will match fewer files, but the files will have more functional similarity. Through this API, users can easily submit executable files and get important statistics - counters of functionally similar files mapped to their classification. By using the **'extended'** option, additional sample metadata such as file hashes (SHA1, MD5, SHA256), classification and reputation information (threat level, threat name, malware family, malware type...) will be returned for the submitted SHA1 hash. ## General Info about Requests/Responses - All requests support the **format** parameter with two possible values: **xml** or **json**. - Default response format is **xml**, except for bulk queries where the response format is the same as the post_format. - POST requests must contain an HTTP header field *Content-Type: application/octet-stream*. - All bulk queries will accept POST payload in XML or JSON (described below) ## RHA1 Analytics Single Query This query returns statistics (counters) of files mapped to their classifications that are functionally similar to the submitted file at the given precision level. The response will contain a count of malicious, suspicious and known files, as well as the total number of files. If the extended option is selected, the response will contain additional metadata for the provided SHA1 hash. ### Request ``` GET /api/rha1/analytics/v1/query/{rha1_type}/{sha1}[?format=xml|json][&extended=false|true] ``` - `rha1_type` - A measure of the RHA1 precision level. It 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: - Required - **pe01**, **elf01**, **machO01** - 25% precision level - **pe02** - 50% precision level - `sha1` - Must be a valid SHA1 hash - Required - `format` - Specifies the response format, with possible values being **xml** (default) and **json** - Optional - `extended` - An optional parameter. Possible values are **true** - extended, and **false** - non-extended data set (default) - Optional ### Response If the requested hash doesn't exist in the database records or doesn't match the requested RHA1 precision level, the server will respond with the status response code 404 and the message **"Requested data was not found"** All possible response fields are described in the following tables. Example responses can be found further in the document. - `rha1_counters` - Parent node for classification counters rl (default rl root) - `sha1` - The requested SHA1 hash - `rha1_type` - Type of RHA1 hash (the precision level of the RHA1) - `rha1_first_seen` - RHA1 bucket first seen - `rha1_last_seen` - RHA1 bucket last seen - `sample_counters` - List of counters - `sample_metadata` - Sample metadata fields, if extended is set to **true** rl \> rha1_counters - `malicious` - Number of malicious samples that are functionally similar to the provided SHA1 hash at the requested precision level (RHA1 type) - `suspicious` - Number of suspicious samples that are functionally similar to the provided SHA1 hash at the requested precision level (RHA1 type) - `known` - Number of known samples that are functionally similar to the provided SHA1 hash at the requested precision level (RHA1 type) - `total` - Sum of all counters rl \> rha1_counters \> sample_counters Returned response fields depend on the selected data set. If the **extended** option is set to **true**, the following fields will be returned for the requested SHA1 sample hash. Empty fields are not included in the response. - `md5` - MD5 hash of the sample - `sha256` - SHA256 hash of the sample - `sample_available` - Sample's download availability status - `classification` - Current Malware Presence status designation. The status designation is calculated by a proprietary ReversingLabs algorithm that adapts and improves as new information about the file and the threat is discovered. The algorithm takes the following into account: [Spectra Core](https://www.reversinglabs.com/products/automated-static-analysis-tools) static analysis results, [ReversingLabs RHA1 similarity hashing algorithm](https://www.reversinglabs.com/technology/reversinglabs-hash-algorithm), complex malformation rules, YARA rules, ReversingLabs signatures, [Spectra Intelligence](https://www.reversinglabs.com/products/spectra-intelligence) antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information - `threat_level` - Threat level of the sample - `trust_factor` - Trust factor of the sample - `threat_name` - Detected threat name - `malware_family` - Malware family for malicious and suspicious samples - `malware_type` - Malware type for malicious and suspicious samples - `sample_type` - Sample type - `sample_size` - Sample size (in bytes) - `first_seen` - Time when the sample was first seen in the ReversingLabs system (UTC) - `last_seen` - Time when the sample last received impactful changes to its analysis or classification data (UTC) #### Response Examples ``` json { "rl": { "rha1_counters": { "sha1": "4f21ad6781bfbee641ecd075fc079b5e6145f03f", "rha1_type": "pe01", "rha1_first_seen": "2011-05-21T09:36:00", "rha1_last_seen": "2012-12-17T00:00:00", "sample_counters": { "known": 4116, "malicious": 138, "suspicious": 182, "total": 4436 }, "sample_metadata": { "md5": "6ede26d354a3956573291361f754ea10", ... } } } } ``` ## RHA1 Analytics Bulk Query This query retrieves the same data as the single query, but for multiple hashes within a single response. It is more network-efficient compared to multiple single queries. Bulk query accepts a maximum of 1000 hashes in a single request. ### Request ``` POST /api/rha1/analytics/v1/query/{post_format} ``` - `post_format` - Defines the POST payload format. Supported options are `xml` and `json` - Required #### Request body - `rha1_type` - A measure of the RHA1 precision level. It 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: - Required - **pe01**, **elf01**, **machO01** - 25% precision level - **pe02** - 50% precision level - `hash_value` - Must be a valid SHA1 hash - Required - `response_format` - Specifies the response format, with possible values being **xml** (default) and **json** - Optional - `extended` - An optional parameter. Possible values are **true** - extended, and **false** - non-extended data set (default) - Optional ``` json { "rl" : { "query" : { "rha1_type" : "(pe01|pe02|elf01|macho01)", "response_format" : "(xml|json)", "extended" : "(true|false)", "hashes" : [ "hash_value", "hash_value", ..., "hash_value" ] } } } ``` ### Response - `entries` - Contains a sequence of counters data - `invalid_hashes` - List of ill-formatted hashes from the request - `unknown_hashes` - List of hashes from the request that were not found in the database rl (default rl root) - `item` - The \ is equivalent to the `table` node from the RHA1 Analytics single query rl \> entries ``` json { "rl": { "entries": [ { ... }, - { ... } ], "invalid_hashes": [ "zzze764af2be3711ce1147fa762562188b57dae83z" ], "unknown_hashes": [ "1147fa762562188b57dae8cf3e764af2be3711ce" ] }} ``` ## Examples ### Format query field **These examples request different response formats:** \[GET\] ``` /api/rha1/analytics/v1/query/pe01/25cefc6fc048fbac9eccf2d65af736dd12e2c62a?format=json /api/rha1/analytics/v1/query/pe01/eb7f7f9b7744d0f28ab82f8272fbe643e56a070c?format=xml ``` ### Format query field **These examples request different RHA1 types** \[GET\] ``` /api/rha1/analytics/v1/query/pe01/25cefc6fc048fbac9eccf2d65af736dd12e2c62a /api/rha1/analytics/v1/query/pe02/00e710e430e5558f06b1b3c85d518fbcfa118eef /api/rha1/analytics/v1/query/elf01/9c489fcaee9abedd736b474d7f9076d23ea2bb9b /api/rha1/analytics/v1/query/macho01/b7a1143b04aa93e0b236968c6cded7807aa5e89c ``` ### Extended optional parameter used **These examples demonstrate the use of the extended field:** \[GET\] ``` /api/rha1/analytics/v1/query/pe01/25cefc6fc048fbac9eccf2d65af736dd12e2c62a?extended=true /api/rha1/analytics/v1/query/elf01/9c489fcaee9abedd736b474d7f9076d23ea2bb9b?extended=false ``` ### Bulk query **These examples use different POST formats:** \[POST\] ``` /api/rha1/analytics/v1/query/xml /api/rha1/analytics/v1/query/json ``` ### Bulk JSON POST **This example varies the requested RHA1 type, response_format and extended options, but the post_type is staying the same:** ``` /api/rha1/analytics/v1/query/json ``` **Example 1** ``` json { "rl": { "query": { "rha1_type":"pe01", "response_format":"xml", "extended":"false", "hashes": [ "70d1d32e783dac03a7000616e63207f17b996809", "0dd1bc46e96d41591294e8c13c6eb7f6212be2ed", "57dafb1b1f5c0e0217fc90e25355386cb087886f", "eb7f7f9b7744d0f28ab82f8272fbe643e56a070c", "70d1d32e783dac03a7000616e63207f17b996807" ] } } } ``` **Example 2** ``` json { "rl": { "query": { "rha1_type":"pe02", "response_format":"xml", "extended":"false", "hashes": [ "70d1d32e783dac03a7000616e63207f17b996809", "0dd1bc46e96d41591294e8c13c6eb7f6212be2ed", "57dafb1b1f5c0e0217fc90e25355386cb087886f", "eb7f7f9b7744d0f28ab82f8272fbe643e56a070c", "70d1d32e783dac03a7000616e63207f17b996807" ] } } } ``` **Example 3** ``` json { "rl": { "query": { "rha1_type":"pe01", "response_format":"xml", "extended":"false", "hashes": [ "70d1d32e783dac03a7000616e63207f17b996809", "0dd1bc46e96d41591294e8c13c6eb7f6212be2ed", "57dafb1b1f5c0e0217fc90e25355386cb087886f", "eb7f7f9b7744d0f28ab82f8272fbe643e56a070c", "70d1d32e783dac03a7000616e63207f17b996807" ] } } } ``` --- ## Indicators of Compromise API (TCA-0330) — Spectra Intelligence ReversingLabs Indicators of Compromise (IoC) service delivers access to large volumes of structured threat intelligence data for samples and URLs. It supports both detailed data retrieval and summary statistics, with filtering by type (sample or URL), time format (timestamp or UTC), classification, threat level, malware family, malware type, threat actor, sample type, platform, and vertical. The results are returned in JSON format, and can be limited and paginated. ## General Info about Requests/Responses - Default response format is JSON. - When a non-existing value is provided for a string field (`malware_family`, `threat_actor`, `sample_type`), the API will validate only the allowed characters. If disallowed characters are used, a `400` status code is returned with an error message (e.g., "Not allowed characters in `threat_actor` used"). And if the value contains only allowed characters, but does not match any known entries, a `200` status code is returned with an empty response. ## Indicators of Compromise Query This query returns IoC data based on the specified parameters. ### Request ``` GET /api/ioc/v1/query/{type}/{time_format}/{time_value}/page/{page} ``` #### Path parameters - `type` - The type of the IoC to query. Supported values: `sample` or `url`. - Required - `time_format` - The format of the time value. Supported values: `timestamp` or `utc`. - Required - `time_value` - The time value to query. The format depends on the `time_format` parameter. - Required - `page` - Specifies the page of results to retrieve. Use the `next_page` value from the response to get the next page of results. - Optional #### Query parameters - `limit` - The maximum number of results to be retrieved. Default is 1000. - `classification` - The classification of the IoC. Supported values: `malicious` or `suspicious`. - `threat_level` - The threat level of the IoC. Supported values: `1` - `5`. - `vertical` - The vertical of the IoC. Supported values: `financial`, `ransomware`, `apt`, `exploit`, `retail`, `bots`, `healthcare`. **Applicable only for samples.** - `malware_family` - The family of the malware associated with the IoC. - `malware_type` - The type of the malware associated with the IoC. Supported values: `Infostealer`, `Dropper`, `Spyware`, `Trojan`, `Backdoor`, `Dialer`, `Worm`, `Downloader`, `Keylogger`, `Adware`, `Malware`, `Rogue`, `PUA`, `Packed`, `Exploit`, `Virus`, `Hacktool`, `Browser`, `Network`, `Rootkit`, `Phishing`, `Ransomware`, `Coinminer`, `Spam`. Applies only when the type is `sample`. If the type is `url`, any string value is accepted (e.g., `hyperlink`). - `threat_actor` - The threat actor associated with the IoC. **Applicable only for samples.** - `sample_type` - The type of the sample associated with the IoC. **Applicable only for samples.** - `platform` - The platform of the IoC. Supported values: `ABAP`, `Android`, `AOL`, `Archive`, `Audio`, `Binary`, `Blackberry`, `Boot`, `ByteCode`, `Console`, `Document`, `DOS`, `Email`, `EPOC`, `Firmware`, `FreeBSD`, `Image`, `iOS`, `Linux`, `MacOS`, `Menuet`, `Novell`, `OS2`, `Package`, `Palm`, `Script`, `Shortcut`, `Solaris`, `SunOS`, `Symbian`, `Text`, `Unix`, `Video`, `WebAssembly`, `Win32`, `Win64`, `WinCE`. **Applicable only for samples.** ### Response The response is a JSON object containing the query parameters and the entries that match the requested query. ``` json { "rl": { "query": { "time_range": { "to": "string", "from": "string" } }, "entries": [ { "sha1": "string", "sha256": "string", "md5": "string", "threat_level": 1, "malware_family": "string", "malware_type": "string", "platform": "string", "threat_name": "string", "classification": "string", "sample_type": "string", "first_seen": "string", "threat_actors": [ "string", "string" ], "verticals": [ "string", "string" ], "reason": "string" } ], "next_page": "string" } } ``` `rl.query` - Contains the query parameters used in the request. `rl.entries` - `sha1` - The SHA1 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `sha256` - The SHA256 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `md5` - The MD5 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `URL` - The URL of the IoC. **Applicable only for URLs.** - `threat_level` - The threat level of the IoC. Malware severity indicator for suspicious and malicious samples, expressed as an integer between 1 and 5, where 5 indicates the most dangerous threats (highest severity). - `malware_family` - The family of the malware associated with the IoC. - `malware_type` - The type of the malware associated with the IoC. Supported values: `Infostealer`, `Dropper`, `Spyware`, `Trojan`, `Backdoor`, `Dialer`, `Worm`, `Downloader`, `Keylogger`, `Adware`, `Malware`, `Rogue`, `PUA`, `Packed`, `Exploit`, `Virus`, `Hacktool`, `Browser`, `Network`, `Rootkit`, `Phishing`, `Ransomware`, `Coinminer`, `Spam`. Applies only when the type is `sample`. If the type is `url`, any string value is accepted (e.g., `hyperlink`). - `platform` - The platform of the IoC. **Applicable only for samples.** - `threat_name` - The name of the threat associated with the IoC. Complete malware threat name. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). - `classification` - The classification of the IoC. - `sample_type` - The type of the sample associated with the IoC. **Applicable only for samples.** - `first_seen` - The first time the IoC was seen. - `threat_actors` - A list of threat actors associated with the IoC. **Applicable only for samples.** - `verticals` - A list of verticals associated with the IoC. Supported values: `financial`, `ransomware`, `apt`, `exploit`, `retail`, `bots`, `healthcare`. **Applicable only for samples.** - `reason` - The reason for the classification of the IoC. `rl.next_page` - Specifies the page of results to retrieve. Provides a value to get the next page of results. ### Examples Fetch 4 malicious samples with `threat_level` 4 or 5, `retail` industry starting from timestamp `1736497955000`. ``` GET /api/ioc/v1/query/sample/timestamp/1736497955000?classification=MALICIOUS&threat_level=4|5&vertical=retail&limit=4 ``` Fetch 1000 URLs with `malware_type` `exploit` from `2025-01-01T10:00:00` starting from page `1641083310a45ab18fb7a06dd5ecb44bf6c221a951f974059f`. ``` GET /api/ioc/v1/query/url/utc/2025-01-01T10:00:00/page/1641083310a45ab18fb7a06dd5ecb44bf6c221a951f974059f?malware_type=Exploit ``` ## Indicators of Compromise Latest Query This query returns the latest IoC data based on the specified parameters. ### Request ``` GET /api/ioc/v1/query/{type}/latest/page/{page} ``` #### Path parameters - `type` - The type of the IoC to query. Supported values: `sample` or `url`. - Required - `page` - Specifies the page of results to retrieve. Use the `next_page` value from the response to get the next page of results. - Optional #### Query parameters - `limit` - The maximum number of results to be retrieved. Default is 1000. - `classification` - The classification of the IoC. Supported values: `malicious` or `suspicious`. - `threat_level` - The threat level of the IoC. Supported values: `1` - `5`. - `vertical` - The vertical of the IoC. Supported values: `financial`, `ransomware`, `apt`, `exploit`, `retail`, `bots`, `healthcare`. **Applicable only for samples.** - `malware_family` - The family of the malware associated with the IoC. - `malware_type` - The type of the malware associated with the IoC. Supported values: `Infostealer`, `Dropper`, `Spyware`, `Trojan`, `Backdoor`, `Dialer`, `Worm`, `Downloader`, `Keylogger`, `Adware`, `Malware`, `Rogue`, `PUA`, `Packed`, `Exploit`, `Virus`, `Hacktool`, `Browser`, `Network`, `Rootkit`, `Phishing`, `Ransomware`, `Coinminer`, `Spam`. Applies only when the type is `sample`. If the type is `url`, any string value is accepted (e.g., `hyperlink`). - `threat_actor` - The threat actor associated with the IoC. **Applicable only for samples.** - `sample_type` - The type of the sample associated with the IoC. **Applicable only for samples.** - `platform` - The platform of the IoC. Supported values: `ABAP`, `Android`, `AOL`, `Archive`, `Audio`, `Binary`, `Blackberry`, `Boot`, `ByteCode`, `Console`, `Document`, `DOS`, `Email`, `EPOC`, `Firmware`, `FreeBSD`, `Image`, `iOS`, `Linux`, `MacOS`, `Menuet`, `Novell`, `OS2`, `Package`, `Palm`, `Script`, `Shortcut`, `Solaris`, `SunOS`, `Symbian`, `Text`, `Unix`, `Video`, `WebAssembly`, `Win32`, `Win64`, `WinCE`. **Applicable only for samples.** ### Response The response is a JSON object containing the query parameters and the entries that match the requested query. ```json { "rl": { "query": { "time_range": { "to": "string", "from": "string" } }, "entries": [ { "URL": "string", "threat_level": 1, "malware_type": "string", "classification": "string", "first_seen": "string", "reason": "string" } ], "next_page": "string" } } ``` `rl.query` - Contains the query parameters used in the request. `rl.entries` - `sha1` - The SHA1 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `sha256` - The SHA256 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `md5` - The MD5 hash of the IoC. Hexadecimal hash value of the sample. **Applicable only for samples.** - `URL` - The URL of the IoC. **Applicable only for URLs.** - `threat_level` - The threat level of the IoC. Malware severity indicator for suspicious and malicious samples, expressed as an integer between 1 and 5, where 5 indicates the most dangerous threats (highest severity). - `malware_family` - The family of the malware associated with the IoC. - `malware_type` - The type of the malware associated with the IoC. Supported values: `Infostealer`, `Dropper`, `Spyware`, `Trojan`, `Backdoor`, `Dialer`, `Worm`, `Downloader`, `Keylogger`, `Adware`, `Malware`, `Rogue`, `PUA`, `Packed`, `Exploit`, `Virus`, `Hacktool`, `Browser`, `Network`, `Rootkit`, `Phishing`, `Ransomware`, `Coinminer`, `Spam`. Applies only when the type is `sample`. If the type is `url`, any string value is accepted (e.g., `hyperlink`). - `platform` - The platform of the IoC. **Applicable only for samples.** - `threat_name` - The name of the threat associated with the IoC. Complete malware threat name. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). - `classification` - The classification of the IoC. - `sample_type` - The type of the sample associated with the IoC. **Applicable only for samples.** - `first_seen` - The first time the IoC was seen. - `threat_actors` - A list of threat actors associated with the IoC. **Applicable only for samples.** - `verticals` - A list of verticals associated with the IoC. **Applicable only for samples.** - `reason` - The reason for the classification of the IoC. `rl.next_page` - Specifies the page of results to retrieve. Provides a value to get the next page of results. ### Examples Fetch 100 latest samples entries. ``` GET /api/ioc/v1/query/sample/latest?limit=100 ``` ## Indicators of Compromise Summary Query This query returns a summary of IoC data based on the specified parameters. ### Request ``` GET /api/ioc/v1/query/{type}/{time_format}/{time_value}/summary ``` #### Path parameters - `type` - The type of the IoC to query. Supported values: `sample` or `url`. - Required - `time_format` - The format of the time value. Supported values: `timestamp` or `utc`. - Required - `time_value` - The time value to query. The format depends on the `time_format` parameter. - Required #### Query parameters - `classification` - The classification of the IoC. Supported values: `malicious` or `suspicious`. - `threat_level` - The threat level of the IoC. Supported values: `1` - `5`. - `vertical` - The vertical of the IoC. Supported values: `financial`, `ransomware`, `apt`, `exploit`, `retail`, `bots`, and `healthcare`. **Applicable only for samples.** - `malware_family` - The family of the malware associated with the IoC. - `malware_type` - The type of the malware associated with the IoC. Supported values: `Infostealer`, `Dropper`, `Spyware`, `Trojan`, `Backdoor`, `Dialer`, `Worm`, `Downloader`, `Keylogger`, `Adware`, `Malware`, `Rogue`, `PUA`, `Packed`, `Exploit`, `Virus`, `Hacktool`, `Browser`, `Network`, `Rootkit`, `Phishing`, `Ransomware`, `Coinminer`, and `Spam`. Applies only when the type is `sample`. If the type is `url`, any string value is accepted (e.g., `hyperlink`). - `threat_actor` - The threat actor associated with the IoC. **Applicable only for samples.** - `vertical` - The vertical of the IoC. Supported values: `financial`, `ransomware`, `apt`, `exploit`, `retail`, `bots`, `healthcare`. **Applicable only for samples.** - `sample_type` - The type of the sample associated with the IoC. **Applicable only for samples.** - `platform` - The platform of the IoC. Supported values: `ABAP`, `Android`, `AOL`, `Archive`, `Audio`, `Binary`, `Blackberry`, `Boot`, `ByteCode`, `Console`, `Document`, `DOS`, `Email`, `EPOC`, `Firmware`, `FreeBSD`, `Image`, `iOS`, `Linux`, `MacOS`, `Menuet`, `Novell`, `OS2`, `Package`, `Palm`, `Script`, `Shortcut`, `Solaris`, `SunOS`, `Symbian`, `Text`, `Unix`, `Video`, `WebAssembly`, `Win32`, `Win64`, `WinCE`. **Applicable only for samples.** ### Response The response is a JSON object containing the query parameters and the entries that match the requested query. ``` json { "rl": { "query": { "time_range": { "to": "string", "from": "string" } }, "entries_count": 12345 } } ``` `rl.query` - Contains the query parameters used in the request. `rl.entries_count` - The total number of entries that match the requested query parameters in the last 90 days. ### Examples Fetch a number of samples from start time `2025-01-01T10:00:00` with `sample_type` PE/EXE. ``` GET /api/ioc/v1/query/sample/utc/2025-01-01T10:00:00/summary?sample_type=pe/exe ``` --- ## Migrating Custom API Code and Enrichment Pipelines to Spectra Intelligence Security teams and security vendors that call the VirusTotal API directly, in custom scripts, enrichment pipelines, internal tooling, or embedded product features, can now move those calls to Spectra Intelligence by changing only a base URL and an API key. The response schema, field names, and authentication pattern are preserved, saving time and effort when migrating. SOAR and SIEM platforms ship pre-built VT connectors maintained by platform vendors and reconfigured inside the platform, not through direct API calls. The audience for the **VirusTotal Compatible API Suite** is different: engineers who write code that calls the VT API directly, and security companies that have embedded VT calls into their own products. For that class of integration, the compatibility layer, a Spectra Intelligence endpoint that accepts VT v3 requests and returns VT v3 responses, reduces migration to just a configuration change. ## Integration patterns this covers ### Custom Python scripts using the vt-py SDK The official VirusTotal Python client, `vt-py`, is the most common way engineers write custom VT integrations. Its `vt.Client` constructor accepts a `host` parameter that overrides the default base URL. Redirecting a `vt-py`-based script to the RL VT-compatible endpoint requires one additional constructor argument: ```python # Before client = vt.Client(apikey=VT_API_KEY) # After — one parameter added, all downstream calls unchanged client = vt.Client( apikey=RL_API_KEY, host="https://data.reversinglabs.com", ) # Existing code continues to work without modification file = client.get_object("/files/{}", sha256) print(file.last_analysis_stats) # {'malicious': 14, 'undetected': 58} ``` :::caution The `vt-py` `host=` parameter is documented as overridable for testing purposes. Compatibility covers file and URL reputation lookups. SDK features that depend on VT-specific capabilities, retrohunt, file feeds, VT Intelligence search, have no RL equivalent behind this layer. ::: ### Direct HTTP calls with requests or other HTTP clients Scripts that call the VT v3 API directly via `requests` or equivalent HTTP libraries typically hardcode the base URL as a constant alongside the API key. Changing those two values is the entire migration: ```python # Before VT_BASE = "https://www.virustotal.com/api/v3/" headers = {"x-apikey": VT_API_KEY} resp = requests.get(VT_BASE + "files/" + sha256, headers=headers) # After — two values changed, everything else untouched RL_BASE = "https://data.reversinglabs.com/api/v3/" headers = {"x-apikey": RL_API_KEY} resp = requests.get(RL_BASE + sha256, headers=headers) # Response parsing is identical stats = resp.json()["data"]["attributes"]["last_analysis_stats"] if stats["malicious"] > threshold: alert(sha256) ``` :::caution Base URL paths above are sourced from internal product documentation. Confirm exact paths against official RL documentation before deploying. ::: ## The API suite Two endpoints cover the file and URL reputation lookups that account for the majority of direct VT API usage: | API | Endpoint | Query input | |---|---|---| | File Report | `GET /api/v3/files/{hash}` | MD5, SHA-1, or SHA-256 | | URL Report | `GET /api/v3/urls/{urlid}` | SHA-1 URL identifier or base64-encoded URL (no padding) | Both use `x-apikey` header authentication. Base host: `https://data.reversinglabs.com`. ### File Report response fields ```json { "data": { "id": "", "attributes": { "sha256": "...", "sha1": "...", "md5": "...", "last_analysis_stats": { "malicious": 14, "undetected": 58 }, "last_analysis_results": { "BitDefender": { "engine_name": "BitDefender", "category": "malicious", "result": "Trojan.GenericKD.71234567" } }, "first_submission_date": 1706745600, "last_analysis_date": 1712345678 } } } ``` | Response field | Description | |---|---| | `sha256` / `sha1` / `md5` | All three hashes for the queried sample | | `last_analysis_stats.malicious` | Count of engines returning a malicious verdict | | `last_analysis_stats.undetected` | Count of engines with no detection | | `last_analysis_results[n].engine_name` | Name of the scanning engine | | `last_analysis_results[n].category` | `malicious` or `undetected` | | `last_analysis_results[n].result` | Threat name string, or `null` | | `first_submission_date` / `last_analysis_date` | Unix epoch seconds | ### URL Report response fields | Response field | Description | |---|---| | `url` | Human-readable URL | | `last_analysis_stats` | malicious / suspicious / harmless / undetected counts | | `last_analysis_results[n].engine_name` | Name of the reputation source | | `last_analysis_results[n].category` | `malicious`, `suspicious`, `harmless`, or `undetected` | | `last_analysis_results[n].threat_names` | List of threat name strings, or empty | | `first_submission_date` / `last_analysis_date` | Unix epoch seconds | ### What does not change across both patterns - Authentication header name (`x-apikey`) - HTTP method (`GET` for both endpoints) - Hash input types (MD5, SHA-1, SHA-256) - JSON response field names and nesting structure - Timestamp format (Unix epoch seconds) ## Bulk workflows The v3-compatible endpoints mirror VT v3's single-item GET design. Scripts that loop over a list of hashes calling the VT API sequentially work without modification, and VT v3 itself does not support batch file report lookups, so this is not a regression. For high-volume batch lookup, RL provides a separate bulk endpoint at `POST /api/xref/v2/bulk_query/{format}` on `data.reversinglabs.com`, which accepts a JSON body with a list of hashes. This endpoint uses a different request format and response schema from the v3-compatible layer and requires a separate integration path. ## Enterprise and security vendor use cases Beyond individual enrichment scripts, several other major use cases benefit from the same plug and play compatibility, in which the response schema, field names, and auth header are unchanged. ### Incident response and malware triage tooling IR teams frequently build and maintain internal hash-vetting tools: scripts or lightweight applications that accept a list of hashes extracted from a memory dump, disk image, or alert queue, query VT for each one, and return a verdict table sorted by malicious count. These tools are rarely documented and often owned by a single analyst. The compatibility layer means an IR team can redirect an existing triage tool to Spectra Intelligence without involving the analyst who originally wrote it, the tool's output logic, threshold checks, and report formatting all continue to work. ### Alert enrichment pipelines feeding a TIP or data lake Some enterprises build custom enrichment pipelines outside their SOAR platform: a Python service or Lambda function that consumes alert events from a queue, queries VT for each hash or URL, and writes enriched records back to a TIP, data lake, or ticketing system. These pipelines parse specific VT response fields, typically `last_analysis_stats.malicious`, `last_analysis_results` per-engine verdicts, and submission timestamps, into an internal schema. Redirecting the upstream query to RL changes the intelligence source without touching the field extraction logic or the downstream write operations. ### Security product vendors and MSSPs embedding reputation lookup Security ISVs and MSSPs frequently embed third-party file or URL reputation lookups directly into their own products. The customer interacts with the vendor's interface; the VT API call happens in the product backend, not in customer-controlled code. For vendors in this situation, VT's OEM pricing model has historically tied cost to how much reputation data is surfaced to end users: broader result display and customer awareness of the underlying provider increases license cost. The RL VT-compatible layer applies directly here. A vendor whose product initializes a `vt.Client` or issues `requests.get` calls against the VT v3 endpoint can redirect those calls to RL Spectra Intelligence by changing the client constructor or base URL constant in their codebase. The product's output logic, which reads `last_analysis_stats` and `last_analysis_results` to generate a verdict display, requires no modification. Data handling also changes: Spectra Intelligence does not share submitted samples with public repositories by default, which removes a common data handling concern when vendors analyze customer-provided files. ### Email gateway and file transfer enrichment Custom integrations at email gateways and secure file transfer systems often include a step that hashes inbound attachments and queries a reputation service for a quick triage verdict before routing or quarantining. These integrations are commonly implemented as Python scripts or lightweight services calling the VT file report endpoint, parsing `last_analysis_stats.malicious` against a configured threshold. The compatibility layer allows these integrations to be redirected to Spectra Intelligence without modifying the threshold logic, the quarantine routing, or the logging format. ### CI/CD pipeline artifact scanning Development and DevSecOps teams sometimes instrument build pipelines to hash build artifacts and query a reputation service before promoting a build or deploying to production. The check is typically a simple `requests.get` call against the VT file report endpoint, with a pass/fail based on `last_analysis_stats.malicious`. Redirecting this to Spectra Intelligence, a change to the base URL and API key in the pipeline's environment configuration, gives the same pass/fail behavior backed by RL's complex binary analysis engine, without modifying the pipeline logic itself. ## Scope boundary The VT Compatible API Suite covers file and URL reputation lookup. It does not replace: - Pre-built VT/GTI connector plugins for SOAR, SIEM, or EDR platforms; those are reconfigured inside the platform. - VT Intelligence search, retrohunt, YARA LiveHunt, or file feeds; no RL equivalent sits behind this compatibility layer. - RL's native Spectra Intelligence API, which provides a richer data model including MITRE ATT&CK mappings, behavioral classification, certificate chain data, and JSON-body bulk query support. Teams whose VT usage is primarily file and URL reputation lookup, the dominant pattern in custom scripts, IR tooling, enrichment pipelines, and embedded product features, can migrate that surface completely. Teams with heavy VT Intelligence usage should evaluate RL's native Spectra Intelligence APIs directly. ## Conclusion Custom code that calls the VT API depends on VT's JSON schema, not on VirusTotal as a platform. Because the RL VT Compatible API Suite preserves that schema, the same field names, the same nesting structure, the same `x-apikey` header, the same epoch-seconds timestamps, the intelligence source behind a lookup can be changed without touching the code that consumes the response. For `vt-py` users, that is one added constructor parameter. For `requests`-based scripts, it is two constant values. For security vendors with embedded VT calls in their product, it is a change to a client initialization in their own codebase. ## Keep learning - [Explore native Spectra Intelligence API documentation](https://docs.reversinglabs.com/SpectraIntelligence) - [Review vt-py SDK host parameter documentation](https://virustotal.github.io/vt-py/api/client.html) - [Compare ReversingLabs and VirusTotal capabilities](https://reversinglabs.com/reversinglabs-vs-virustotal) --- ## VirusTotal Compatible API Suite — Migration Guide Organizations that have built security automation around VirusTotal's APIs can migrate to ReversingLabs Spectra Intelligence without rewriting integration code. The **VT Compatible API Suite** accepts requests in the VirusTotal v3 format and returns responses in the same schema, powered by Spectra Intelligence. --- ## VirusTotal Compatible API Suite by ReversingLabs # VirusTotal Compatible API Suite **ReversingLabs Spectra Intelligence** provides comprehensive threat intelligence through file analysis, URL reputation, and threat classification services. Migrating away from an incumbent vendor can be complex and costly, especially when your security stack has been built around specific API integrations over years of development. To simplify this process, we've built the **VirusTotal Compatible API Suite** - APIs powered by ReversingLabs Spectra Intelligence but delivered in VT-compatible format. ## Migration challenges Organizations that have built security automation around VirusTotal's APIs face significant barriers to migration: - **Custom API code** - Years of integration work tied to VT's specific endpoints, request formats, and response schemas. - **Parsing logic dependencies** - Downstream systems that depend on VT's JSON key/value pairs, field names, and data structures. - **Operational risk** - Any migration introduces the possibility of broken workflows, missed detections, or gaps in coverage during the transition. The **VT Compatible API Suite** addresses these concerns by letting you redirect your existing API calls to ReversingLabs without rewriting any integration code. ## Why ReversingLabs Spectra Intelligence While the API format stays familiar, the intelligence behind it offers several advantages: - **Deeper file analysis** - Spectra Intelligence performs [static and dynamic analysis](/SpectraIntelligence/API/FileThreatIntel/) at scale, providing richer context for every sample, including file metadata, threat classification, and behavioral indicators. - **Broader coverage** - Spectra Intelligence combines intelligence from 40+ anti-malware engines with proprietary ReversingLabs analysis, delivering broader detection coverage than any single vendor. - **Enterprise-grade reliability** - Spectra Intelligence is purpose-built for high-volume enterprise environments with predictable performance and dedicated support. ## API suite overview The **VT Compatible API Suite** includes the following core APIs that cover the vast majority of VirusTotal integration use cases. ### File Report API **Endpoint:** `GET /api/v3/files/{hash}` Retrieve comprehensive file analysis reports using any supported hash identifier. The response format mirrors the VirusTotal v3 file report schema, so your existing parsing logic works without modification. | Feature | Details | |---|---| | **Hash input** | Query by MD5, SHA-1, or SHA-256 passed as a path parameter, just like VT v3. | | **Authentication** | API key via `x-apikey` header, using ReversingLabs-supplied credentials. | | **Analysis statistics** | Aggregated malicious/undetected counts in `last_analysis_stats`. | | **Per-engine results** | Individual scanner verdicts with engine name, category, and threat name in `last_analysis_results`. | | **File hashes** | SHA-256, SHA-1, and MD5 returned for every queried sample. | | **Timestamps** | `first_submission_date` and `last_analysis_date` in epoch-seconds format. | ### URL Report API **Endpoint:** `GET /api/v3/urls/{urlid}` Retrieve URL threat analysis reports using a SHA-1 URL identifier or base64-encoded URL. Responses follow the VirusTotal v3 URL report structure, delivering per-engine analysis results and aggregate statistics. | Feature | Details | |---|---| | **URL input** | Query by SHA-1 URL identifier or base64-encoded URL (without padding). | | **Authentication** | API key via `x-apikey` header, using ReversingLabs-supplied credentials. | | **Analysis statistics** | Malicious, suspicious, harmless, and undetected counts in `last_analysis_stats`. | | **Per-engine results** | Individual engine verdicts with category and threat names in `last_analysis_results`. | | **URL metadata** | Human-readable URL, unique identifier, and threat name information. | | **Timestamps** | `first_submission_date` and `last_analysis_date` in epoch-seconds format. | ## Migration process The **VT Compatible API Suite** acts as a transparent proxy layer, accepting requests in the VirusTotal v3 format and returning responses in the same schema, powered by Spectra Intelligence on the backend. To migrate, do the following: 1. **Redirect your endpoint** - Point your existing API calls from the VirusTotal v3 base URL to the ReversingLabs VT-compatible endpoint. 2. **Authenticate with your RL credentials** - Use the ReversingLabs-supplied API key in the `x-apikey` header. 3. **Receive VT-formatted responses** - Responses arrive in the same JSON structure your code already parses, with the same field names, data types, and nesting. Your downstream logic works without changes. ## Migration at a glance | | Traditional migration | VT Compatible API Suite | |---|---|---| | **Code changes** | Extensive rewrites | Base URL swap only | | **Migration timeline** | Weeks to months | Minutes to hours | | **Testing effort** | Full regression testing | Minimal validation | | **Intelligence quality** | Varies | Enterprise-grade from day one | ## Get started Your ReversingLabs account team can help at every step: 1. Schedule a technical walkthrough with your ReversingLabs solutions engineer. 2. Receive your VT-compatible API credentials and endpoint configuration. 3. Update your base URL and begin routing requests through the compatibility layer. 4. Validate responses against your existing parsing logic. 5. Go live with no operational disruption. **Info: Contact us** To schedule a demo or request access to the **VT Compatible API Suite**, contact your ReversingLabs account representative or visit [reversinglabs.com](https://www.reversinglabs.com). For general information about Spectra Intelligence APIs, including authentication, rate limits, and response codes, see the [General information](/SpectraIntelligence/) page. --- ## Network Threat Intelligence API — Spectra Intelligence The Network Threat Intelligence APIs provide comprehensive capabilities for investigating and analyzing network-based indicators of compromise (IOCs), including URLs, domains, and IP addresses. These APIs enable security teams to assess threats, retrieve reputation data, and correlate network indicators with malicious files. ## Common Use Cases ### Check and manage network reputation Quick reputation lookups for URLs, domains, and IP addresses to get an immediate assessment of whether a network location is associated with malicious activity. - **[Network reputation (TCA-0407)](tca-0407.md)** - Query reputation data for URLs, domains, and IP addresses in single or bulk requests. Returns ReversingLabs classification, third-party detections, and malware association indicators. - **[Network reputation (user override) (TCA-0408)](tca-0408.md)** - Override URL classifications within your organization. Useful for marking [false positives](/General/AnalysisAndClassification/FalsePositives) as known or flagging internal threats as malicious. ### Investigate a suspicious URL Use TCA-0404 Analyze URL to submit URLs for analysis and get detailed reports through TCA-0403 URL threat intelligence. TCA-0403 can also retrieve intelligence reports for any URL in our database. - **[Analyze URL (TCA-0404)](tca-0404.md)** - Submit URLs for analysis. Downloads and analyzes content, captures screenshots, and resolves infrastructure details. - **[URL threat intelligence (TCA-0403)](tca-0403.md)** - Retrieve comprehensive threat intelligence reports for URLs in single or bulk requests, including classification, analysis metadata (site categorization, threat type details, site availability, DOM, redirect paths..etc.), screenshots, downloaded files, and third-party reputation data. ### Investigate a domain or IP address Understand threat profiles, associated files, DNS records, and relationships with other network indicators. - **[Domain threat intelligence (TCA-0405)](tca-0405.md)** - Retrieve domain reports in single or bulk requests, including reputation data, downloaded file statistics, DNS records, SSL certificates, related URLs, subdomains, and domain resolutions. - **[IP threat intelligence (TCA-0406)](tca-0406.md)** - Retrieve IP address reports in single or bulk requests, including reputation data, downloaded file statistics, WHOIS information, GeoIP data, related URLs, and domain resolutions. ### Find malware samples associated with a network indicator Correlate network indicators with file samples. These APIs help identify which files contain references to specific URIs, enabling threat hunting and malware analysis workflows. - **[URI-to-hash search (TCA-0401)](tca-0401.md)** - Find file hashes that contain references to a specific URI (email, URL, IPv4 address, or domain) discovered during static analysis. - **[URI statistics (TCA-0402)](tca-0402.md)** - Get statistical counts of known, malicious, and suspicious files associated with a specific URI. ## All Networking APIs --- ## URI-to-Hash Search API (TCA-0401) — Spectra Intelligence The URI to Hash Search service provides a list of SHA1 hashes of files that, during static analysis, were found to contain the requested URI. The following URI types are supported: email, URL, IPv4 address, and domain. 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. There are two available response formats: **XML** and **JSON**. ## URI Query ### Request (GET) ``` GET /api/uri_index/v1/query/{uri_sha1}/[next_page_sha1]?[format=xml|json]&[classification=KNOWN|MALICIOUS|SUSPICIOUS|UNKNOWN] ``` This query returns a response containing SHA1 hashes associated (through static analysis) with the requested URI. Using the GET method requires the URI to be submitted as a SHA1 hash value of the URI string. - `uri_sha1` - The SHA1 hash value of the URI string - Required - `next_page_sha1` - An optional parameter used for pagination. Each response contains the *next_page_sha1* field needed for requesting the next page. To get the next page of results, provide the SHA1 hash returned in the next_page_sha1 response field as the next_page_sha1 parameter of the next request. If not supplied, the first page will be returned. - Optional - `format` - Response format. Accepts the following parameters: xml (default) and json - Optional - `classification` - If this parameter is provided in the request, the query will return a list of only those samples that match the requested classification. Possible values are: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN - Optional ### Request (POST) ``` POST /api/uri_index/v1/query?[format=xml|json] ``` This query returns a response containing SHA1 hashes associated (through static analysis) with the requested URI string. Unlike the GET method, the URI string in the POST request body can be in plain text format. The input format is specified using the **Content-Type** HTTP header field. It supports the following values: - text/xml - application/json The response format defaults to the input format. #### Request body ``` json { "rl" : { "query" : { "uri" : "uri_string", "next_page_sha1" : "SHA1_value" } } } ``` - `uri` - A plain text URI for which we request sample SHA1s. 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) - Required - `next_page_sha1` - An optional parameter used for pagination. Each response contains the *next_page_sha1* field needed for requesting the next page. To get the next page of results, provide the SHA1_value hash returned in the next_page_sha1 response field as the next_page_sha1 parameter of the next request. If not supplied, the first page will be returned. - Optional ### Response Response code 404 is returned when the URI isn't found in the ReversingLabs reputation database. ``` json { "rl": { "uri_index": { "query_uri": "string", "next_page_sha1": "string", "sha1_list": [ "string", "string", "string", "string", "string", "string" ] } } } ``` - A maximum of 1000 results per page will be returned - To get the next page of results, provide the SHA1 hash returned in the **next_page_sha1** response field as the **next_page_sha1** parameter in the next request ## Examples ### Example 1 Requesting SHA1 hashes associated with the **127.0.0.1** URI using **JSON** format for the request body. The response will also be in JSON format. ``` /api/uri_index/v1/query ``` #### Headers ``` Content-Type:application/json ``` Request body: ``` json { "rl": { "query": { "uri": "127.0.0.1" } } } ``` ### Example 2 Requesting the SHA1 hashes associated with the **127.0.0.1** URI using **JSON** format for the request body. The response will also be in **JSON** format. Pagination system is used, with **4ca39b9be025792197c2dd17d63956d4089560fe** used as a parameter to retrieve the next batch of results. ``` /api/uri_index/v1/query ``` #### Headers ``` Content-Type:application/json ``` #### Request body ``` json { "rl": { "query": { "uri": "127.0.0.1", "next_page_sha1": "4ca39b9be025792197c2dd17d63956d4089560fe" } } } ``` ### Example 3 Requesting SHA1 hashes associated with 127.0.0.1 using GET. The "127.0.0.1" URI string has to be converted to SHA1 - **4b84b15bff6ee5796152495a230e45e3d7e947d9**. Response formats vary by type. ``` /api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?format=json /api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?format=xml ``` ### Example 4 Requesting SHA1 hashes associated with 127.0.0.1 using GET. The "127.0.0.1" URI string has to be converted to SHA1 - **4b84b15bff6ee5796152495a230e45e3d7e947d9**. Following example filters and returns only results that are classified as **KNOWN**. ``` /api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?classification=KNOWN ``` Multiple arguments can also be combined. ``` /api/uri_index/v1/query/4b84b15bff6ee5796152495a230e45e3d7e947d9?classification=MALICIOUS&format=json ``` --- ## URI Statistics API (TCA-0402) — Spectra Intelligence The ReversingLabs URI Statistics API provides statistical information on how many known, malicious, and suspicious samples are associated with a particular 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. This service accepts only SHA1 values of URI strings. Requested URI strings cannot be in plain text. There are two available response formats: **XML** and **JSON**. ## URI Statistics Query This query returns information about the state of an URI. It provides an unhashed value and numbers for malicious, suspicious, and known files associated with it. ### Request ``` GET /api/uri/statistics/uri_state/sha1/{uri_sha1}?[format=xml|json] ``` - `uri_sha1` - The SHA1 hash value of the URI string - Required - `format` - Response format. Accepts the following parameters: xml (default) and json - Optional ### Response ```json { "rl": { "uri_state": { "url": "string", "sha1": "string", "uri_type": "string", "counters": { "known": 0, "malicious": 0, "suspicious": 0 } } } } ``` - `sha1` - SHA1 hash of the URI - `uri_type` - can be one of the following: email, URL, IPv4, domain - 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) - `counters` - suspicious - number of associations with suspicious samples, malicious - number of associations with malicious samples, known - number of associations with known samples ## Examples ### Request Examples Retrieving the URI state in different formats: ``` /api/uri/statistics/uri_state/sha1/234988566c9a0a9cf952cec82b143bf9c207ac16?format=json /api/uri/statistics/uri_state/sha1/baea954b95731c68ae6e45bd1e252eb4560cdc45?format=xml ``` ### Response Examples #### URL ``` json { "rl": { "uri_state": { "url": "http://google.com", "sha1": "234988566c9a0a9cf952cec82b143bf9c207ac16", "uri_type": "url", "counters": { "known": 77700, "malicious": 48296, "suspicious": 526 } } } } ``` #### IPv4 ```json { "rl": { "uri_state": { "ipv4": "127.0.0.1", "sha1": "4b84b15bff6ee5796152495a230e45e3d7e947d9", "uri_type": "ipv4", "counters": { "known": 48558, "malicious": 163953, "suspicious": 596 } } } } ``` --- ## URL Threat Intelligence API (TCA-0403) — Spectra Intelligence This service returns threat intelligence data for submitted URLs, including ReversingLabs URL classification, third-party reputation data, analysis metadata, and the reputation of files downloaded from the URL. URL classification is URL-specific and is based on a proprietary ReversingLabs algorithm that combines third-party reputation with the file reputation of all samples downloaded during any performed analysis. A URL stays classified as malicious for as long as any file that caused that classification remains malicious - regardless of whether the file is still present on the URL. This API exposes four endpoints: - **[URL report](#url-report) and [URL bulk report](#url-bulk-report)** — Return ReversingLabs URL classification, third-party reputation and categorization, analysis metadata, file counters by classification (malicious, suspicious, known, unknown), and the most common threats. Bulk requests support up to 100 URLs. If multiple analyses were performed on the submitted URL, the response will contain metadata for each analysis, and file counters will show the total number of samples downloaded across all analyses. - **[Downloaded files](#url-downloaded-files)** — Lists files downloaded from a URL across all, the latest, or a specific analysis, with optional extended metadata and classification filtering. - **[URL analysis notification](#url-analysis-notification)** — A feed of previously submitted URLs that were analyzed to completion and whose reports are ready, queryable up to 90 days into the past. **This API is rate-limited to 5 requests per second.** ## Privacy and Data Handling This API retrieves threat intelligence for URLs. It does not submit URLs for analysis. When querying this API, the queried URL may be shared with third-party reputation sources as part of the lookup process. To prevent this data sharing, use the `private` parameter in your request. When set to `true`, the queried URL and results are not shared with third-party sources and not included in public feeds. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls). --- ## URL 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. ### Request ``` POST /api/networking/url/v1/report/query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "url": "string", "response_format": "string", "private": false } } } ``` - `url` - The URL for which to retrieve the report. Provide the full URL of a website including the protocol (`https://www.example.org`). Only `http` and `https` protocols are supported. If the protocol is missing from the submitted URL, `http` will be automatically prepended to the URL. Note that URL normalization is performed during request submission, so duplicate and empty elements in the URL may be automatically removed or converted. - Required - `response_format` - Defines the response format. The following values are supported: `xml` (default) and `json`. - Optional - `private` - Boolean flag to process the query privately. When set to `true`, the submitted network location and query results are not shared with third-party sources and not included in public feeds. Default is `false`. - Optional ### Response If there were multiple analyses performed on the submitted URL, the counters will include files downloaded across all of them. The report will also list the most common threats downloaded from the URL. Regardless if the submitted URL was sent to analysis or not, the URL classification status and third party URL reputation information will always be returned. ```json { "rl": { "sha1": "string", "base64": "string", "analysis": {}, "third_party_reputations": {}, "last_seen": "string", "classification": "string", "reason": "string", "categories": [], "requested_url": "string" } } ``` - `sha1` - The SHA1 hash of the normalized submitted URL. - `base64` - The Base64 encoding of the normalized submitted URL. - `analysis` - Info on performed static analyses. - `dynamic_analysis` - Info on performed dynamic analyses. - `third_party_reputations` - Info from third parties on this URL. - `last_seen` - The last time when the requested URL received an indicator that updated its report. This can be the last time when we checked the URL reputation against third-party sources, the last time we obtained metadata for the requested URL from ReversingLabs static/dynamic file processing services (related files), or the last time the requested URL has been crawled or analyzed by the ReversingLabs Cloud Sandbox. - `classification` - URL classification based on the proprietary ReversingLabs algorithm that takes into account the 3rd party URL reputation and the latest file reputation of all files downloaded across all performed URL analyses. This means that a URL will be classified as malicious for as long as the sample that originally caused this classification is classified as malicious, regardless of whether the sample is present during a new scan. - `categories` - URL categorization according to the source, e.g. phishing. Not all sources provide categorization information. - `requested_url` - The submitted URL - `reason` - The reason why the URL was given a classification. This parameter is only shown if the classification is not `unknown`. If the classification reason was propagated from a URL redirection, it will be prefixed with `redirect_` (e.g `redirect_file_reputation`). Possible values are - `whitelist`, `blacklist` - The URL was found on a ReversingLabs curated whitelist/blacklist. - `file_reputation` - Classification based on the downloaded content. - `sandbox` - Classification based on dynamic analysis (ReversingLabs Cloud Sandbox). - `third_party_reputation`, `domain_third_party_reputation` - Classification based on third-party reputation sources. - `user_override` - Classification overridden by you, or a user belonging to your organization. - `analyst_override` - Classification overridden by a ReversingLabs analyst. - `threat_level` - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known URIs. For unknown URIs, this value is omitted. **Applies to malicious and suspicious samples only** - In real-world situations, threat level values are typically interpreted in the following way: - Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex) - Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations) - Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains). - `threat_name` - Standardized malware name indicating the type, platform, and family of the threat associated with the URL. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious URIs only** ---------------------------------------------------------------------- `rl.analysis` ```json { "first_analysis": "string", "analysis_history": [], "last_analysis": {}, "analysis_count": 0, "statistics": {} } ``` - `first_analysis` - Time when the URL was analyzed for the first time (UTC) - `analysis_history` - `last_analysis` - Metadata about the last analysis. - `analysis_count` - The total number of analyses performed on the submitted URL - `statistics` - File counters mapped to classification. They include files downloaded across all performed analyses. ---------------------------------------------------------------------- `rl.analysis.analysis_history[]` and `rl.analysis.last_analysis` ```json { "analysis_id": "string", "analysis_time": "string", "http_response_code": 0, "availability_status": "string", "domain": "string", "final_url": "string", "serving_ip_address": "string", "screenshot_url": "string", "dom_url": "string" } ``` - `final_url` - The URL that was analyzed after redirecting from the submitted URL. - `availability_status` - Indicates whether the analyzed URL was available or not (at the time of the analysis). Possible values are: `online`, `offline`. - `http_response_code` - The HTTP status code returned by the analyzed site. - `analysis_time` - Time when the report was generated. - `domain` - The domain that hosts the URL. - `serving_ip_address` - The resolved IP address of the analyzed URL. - `analysis_id` - The unique identifier of the analysis. - `redirection_count` - If the submitted URL redirects, this is the total count of redirections. - `redirection_chain` - The chain of redirections from the submitted URL to the final URL. The maximum number of listed redirections is 30. - `screenshot_url` - The URL of the screenshot taken during the analysis. The URL is publicly accessible for a duration of 1 hour. - `dom_url` - The URL of the DOM object that was analyzed. The URL is publicly accessible for a duration of 1 hour. ---------------------------------------------------------------------- `rl.analysis.statistics` ```json { "unknown": 0, "known": 0, "suspicious": 0, "malicious": 0, "total": 0 } ``` - `total` - The total number of files downloaded from the URL - `known` - The number of files classified as KNOWN - `suspicious` - The number of files classified as SUSPICIOUS - `malicious` - The number of files classified as MALICIOUS - `unknown` - The number of files without classification ---------------------------------------------------------------------- `rl.dynamic_analysis.analysis_history[]` and `rl.dynamic_analysis.last_analysis` ```json { "analysis_id": "string", "analysis_time": "string", "platform": "string", "classification": "string", "risk_score": 0, "threat_type": [ "string" ], "browser": "string", "geolocation": "string", "locale": "string" } ``` - `analysis_id` - The unique identifier of the analysis. - `analysis_time` - Time when the report was generated. - `platform` - States which platform was used to detonate the URL. - `classification` - Contains classification value that matches the requested URL sample. Supported values are: `MALICIOUS`, `SUSPICIOUS`, `CLEAN`, `UNKNOWN`. - `risk_score` - Value representing the trustworthiness or malicious severity of a sample. Risk score is expressed as a number from 0 to 10, with 0 indicating whitelisted samples from a reputable origin, and 10 indicating the most dangerous threats. - `threat_type` - Defines the type of a threat. This field is not shown if the classification is `UNKNOWN`. - `browser` - Browser-specific dynamic analysis detonation. The browser used for URL detonation is `chrome`. - `geolocation` - Geographic location associated with the URL's network activity, reflecting the configured country from which the network traffic was egressed during dynamic analysis. - `locale` - Locale setting reflecting the configured OS language, region, and keyboard layout used during dynamic analysis. ---------------------------------------------------------------------- `rl.third_party_reputations.sources[]` ```json { "source": "string", "provider": "string", "update_time": "string", "detection": "string" } ``` - `source` - Name of the third party source - `detection` - Detection for the submitted URL. The possible values are `malicious`/`clean`/`undetected`. If the URL is on a blacklist, it will be labeled as malicious. Whitelisted URLs will be considered clean, and if the source does not have any information about the URL, the value will be undetected. - `provider` - Optional field, shows the source provider. - `categories` - URL categorization according to the source, e.g. phishing. Not all sources provide categorization information. - `update_time` - Time when the information from the source was last updated - `detect_time` - Time when the URL was last detected or given a category by the source. **Important: Entries containing the provider field are sourced from third-party security services via our data provider. We do not verify or guarantee the accuracy or completeness of this information.** The names and trademarks of third-party providers are used for identification purposes only and do not imply endorsement. ---------------------------------------------------------------------- `rl.third_party_reputations.statistics` ```json { "total": 0, "malicious": 0, "suspicious": 0, "clean": 0, "undetected": 0 } ``` - `total` - The total number of consulted URL reputation sources - `malicious` - The number of sources that consider the URL malicious - `suspicious` - The number of sources that consider the URL suspicious - `clean` - The number of sources that consider the URL clean - `undetected` - The number of sources that do not have info about the URL #### Response format (no report) - If the analysis report does not exist, the API will return a **200 response** and the **third_party_reputations** section. The **analysis** section will be empty. ``` json { "rl": { "requested_url": "string", "classification": "string", "analysis": {}, "third_party_reputations": { "statistics": "string", "sources": [ "string", "string", "string" ] } } } ``` ### Examples #### Retrieve a report ``` /api/networking/url/v1/report/query/json ``` ``` json { "rl": { "query": { "url": "https://psychology-degree-programs-us.today/", "response_format": "json" } } } ``` #### Retrieve a report for a URL with third party detections only Retrieving a URL report in JSON format, using a JSON POST body. The submitted URL was not analyzed (submitted to the TCA-0404 service), but third party detections exist. ``` /api/networking/url/v1/report/query/json ``` ``` json { "rl": { "query": { "url": "http://icayus.com/wTpWgvg", "response_format": "json" } } } ``` ## URL bulk report This service returns the report for the submitted URLs. The report for each URL 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. The limit is 100 URLs per request. ### Request ``` POST /api/networking/url/v1/report/bulk_query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "urls": [ "string" ], "response_format": "string", "private": false } } } ``` - `urls` - The URLs for which to retrieve the report. Provide the full URL of a website including the protocol (`https://www.example.org`). Only `http` and `https` protocols are supported. If the protocol is missing from the submitted URL, `http` will be automatically prepended to the URL. Note that URL normalization is performed during request submission, so duplicate and empty elements in the URL may be automatically removed or converted. The limit is 100 URLs per request. - Required - `response_format` - Defines the response format. Supported values: `xml` or `json`. - Optional - `private` - Boolean flag to process the query privately. When set to `true`, the submitted network location and query results are not shared with third-party sources and not included in public feeds. Default is `false`. - Optional ### Response The response will contain a list of report entries for each submitted URL, including their classification status, reputation data, analysis metadata, and other details. ```json { "rl": { "entries": [ { "requested_url": "string", "classification": "string", "last_seen": "string", "analysis": {}, "third_party_reputations": {}, } { "sha1": "string", "base64": "string", "analysis": {}, "third_party_reputations": {}, "last_seen": "string", "first_seen": "string", "classification": "string", "reason": "string", "threat_level": 0, "requested_url": "string" } ] } } ``` ## URL downloaded files ### Request ``` POST /api/networking/url/v1/downloaded_files/query/{format} ``` - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "url": "string", "last_analysis": "string", "response_format": "string", "limit": 3, "extended": boolean, "classification": "string", "private": false } } } ``` - `url` - The URL for which to retrieve a list of files. Provide the full URL of a website including the protocol (`https://www.example.org`). Only `http` and `https` protocols are supported. If the protocol is missing from the submitted URL, `http` will be automatically prepended to the URL. Note that URL normalization is performed during request submission, so duplicate and empty elements in the URL may be automatically removed or converted. This parameter returns a list of all files downloaded from a URL in **all** analyses. `url` cannot be used in combination with `analysis_id`. - Optional - `analysis_id` - A string provided by the Analyze URL API response, or the URL Analysis Notification Feed. If provided in the request, this parameter returns a list of files downloaded from a URL during **the specific analysis matching the ID**. `analysis_id` cannot be used in combination with `url`. - Optional - `last_analysis` - Boolean; if set to true, the listed files will be exclusively the ones that were downloaded during the most recent analysis. Default value: `false`. `last_analysis` cannot be used in combination with `analysis_id`. - Optional - `response_format` - Defines the response format. The following values are supported: `xml` (default) and `json` - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional - `extended` - Allows choosing between `true` - extended, and `false` - non-extended data set (default) - Optional - `classification` - If this parameter is provided in the request, the response will contain only samples that match the requested classification. Supported values are: `KNOWN`, `SUSPICIOUS`, `MALICIOUS`, `UNKNOWN` - Optional - `private` - Boolean flag to process the query privately. When set to `true`, the submitted network location and query results are not shared with third-party sources and not included in public feeds. Default is `false`. - Optional ### Response The response will contain metadata for files downloaded from the submitted URL. Empty fields are not included in the response. ```json { "rl": { "requested_url": "string", "first_analysis": "string", "last_analysis": "string", "analysis_count": 0, "total_files_count": 0, "files": [], "next_page": "string" } } ``` - `requested_url` - The submitted URL - `first_analysis` - Time when the URL was analyzed for the first time (UTC) - `last_analysis` - Time when the URL was last analyzed (UTC) - `analysis_count` - The total number of times the URL was analyzed - `total_files_count` - The total number of files downloaded from the submitted URL (all crawls) - `files` - A list of files and their metadata. - if URL submitted - all files - if `analysis_id` - only for that analysis (crawl) - if URL submitted and `last_analysis=true` - only samples downloaded with the last analysis (crawl) - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of records ---------------------------------------------------------------------- `rl.files[]` ```json { "first_download": "string", "classification": "string", "sample_type": "string", "sha256": "string", "sample_size": 0, "sample_available": 0, "sha1": "string", "last_download": "string", "first_seen": "string", "threat_level": 0, "trust_factor": 0, "md5": "string", "last_seen": "string" } ``` - `first_download` - Time when the file was first downloaded (UTC) - `classification` - File classification. Can be one of the following: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN - `sample_type` - File type, as detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) - `sha256` - SHA256 of the file - `sample_size` - File size (in bytes) - `sample_available` - Indicates whether the sample is present in the ReversingLabs storage and available for download (true) or if it's not available (false). - `sha1` - The SHA1 hash of the file - `last_download` - Time when the file was last downloaded (UTC) - `first_seen` - Time when the sample was first seen in the ReversingLabs system (UTC) - `md5` - MD5 of the file - `trust_factor` - Trustworthiness indicator for goodware samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). **Applies to known samples only** - `threat_name` - Standardized malware name indicating the type, platform, and family of the threat associated with the URL. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious URIs only** - `threat_level` - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known URIs. For unknown URIs, this value is omitted. **Applies to malicious and suspicious samples only** - In real-world situations, threat level values are typically interpreted in the following way: - Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex) - Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations) - Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains). - `malware_type` - The *type* part of the full threat name detected for the sample (for example, Trojan, Adware, Rootkit...). Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious samples only** - `malware_family` - The *familyname* part of the full threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat...).. **Applies to malicious and suspicious samples only** - `platform` - The platform targeted by the malware - `subplatform` - The subplatform targeted by the malware - `last_seen` - The last time when the file received impactful changes that updated its threat intelligence report. (UTC) ### Examples #### Retrieve files downloaded from a URL with extended metadata Get extended metadata about MALICIOUS files downloaded from *http://185.242.104.78/wftp/* using a JSON request. Request the response in JSON, and limit it to 1 item. Request: ``` /api/networking/url/v1/downloaded_files/query/json ``` ``` json { "rl": { "query": { "url": "http://185.242.104.78/wftp/", "limit": 1, "extended": true, "classification": "MALICIOUS", "response_format": "json" } } } ``` Response: ``` json { "rl": { "requested_url": "http://185.242.104.78/wftp/", "first_analysis": "2020-04-06T15:38:20", "last_analysis": "2020-04-14T13:04:35", "analysis_count": 6, "total_files_count": 5, "files": [ { "sha1": "0d092b9cad4e5219313c589b9dd73b514af22bdf", "first_download": "2020-03-30T11:19:54", "last_download": "2020-03-31T11:22:32", "classification": "MALICIOUS", "md5": "80e101f716a4b97ea309e5f8d0ae654b", "sha256": "a92e3c5ee2574135d81299050998115d847fa9289559adf1eee8e860baa7063e", "sample_available": true, "first_seen": "2020-03-25T01:07:44", "last_seen": "2020-04-07T21:02:00", "sample_type": "Text/VBS", "sample_size": 19836, "trust_factor": 5, "threat_level": 5, "threat_name": "Script-VBS.Trojan.Valyria", "malware_family": "Valyria", "malware_type": "Trojan", "platform": "Script", "subplatform": "VBS" } ], "next_page": "15856537526475f6b4c1d2867907b170ee65eae5ae82340546" } } ``` ## URL analysis notification This service provides a continuous list of completed analyses up to 90 days into the past. The records enter the feed once the submitted URL is analyzed to completion and the report is ready. ### Request ``` GET /api/networking/url/v1/notifications/query/latest[/page/{page}]?[format=xml|json]&[limit=1-1000] ``` ``` GET /api/networking/url/v1/notifications/query/from/{time_format}/{start_time}/[/page/{page}]?[format=xml|json]&[limit=1-1000] ``` Path parameters: - `time_format` - Defines the time format. Possible values are: `utc`, `timestamp` - Required - `start_time` - Accepts values in the format set by `time_format`. If the format is set to `utc`, the value should be formatted as YYYY-MM-DDThh:mm:ss. If the format is set to `timestamp`, the value should be expressed as the number of seconds since 1970-01-01 00:00:00 - Required - `page` - An optional pagination parameter used for retrieving the next page of the results. The pagination value for the next page is provided in the previous request response - Optional Query parameters: - `format` - Defines the response format. Supported values are `xml` or `json`; the default is `xml`. - Optional - `limit` - The maximum number of reports to return in the response. Accepted values are numbers between 1 and 1000; if the parameter is not provided in the request, it defaults to 1000 - Optional ### Response The response will contain a list of completed URL analyses, starting from the requested time, or in the last 1 hour if the *latest* endpoint is used. The records will be sorted in ascending order by their stored time. The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, 1000 records will be returned by default. ```json { "rl": { "next_page": "string", "urls": [] } } ``` - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of records - `urls` - List of URLs ---------------------------------------------------------------------- `rl.urls[]` ```json { "url": "string", "availability_status": "string", "final_url": "string", "analysis_id": "string", "analysis_time": "string" } ``` - `url` - The submitted URL - `final_url` - The URL that was analyzed after redirecting from the submitted URL - `availability_status` - Indicates whether the submitted URL was available or not (at the time of the analysis). Possible values: `online`, `offline` - `analysis_time` - Time when the report was generated - `analysis_id` - The unique identifier of the analysis ### Examples #### Retrieve records from a specific timestamp Retrieving information starting from timestamp 1586869174, listing five feed records, in JSON format. Request: ``` /api/networking/url/v1/notifications/query/from/timestamp/1586869174?format=json&limit=5 ``` Response: ``` json { "rl": { "urls": [ { "url": "http://45.95.168.106/mips", "final_url": "http://45.95.168.106/mips", "availability_status": "offline", "analysis_time": "2020-07-14T08:57:44", "analysis_id": "15947161334231c0" }, { "url": "https://eicar.org/?page_id=3950", "final_url": "https://eicar.org/?page_id=3950", "availability_status": "online", "analysis_time": "2020-07-14T09:31:49", "analysis_id": "159471910992e314" }, { "url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "final_url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "availability_status": "offline", "analysis_time": "2020-07-14T10:43:05", "analysis_id": "1594722480864193" }, { "url": "http://45.95.168.106/mips", "final_url": "http://45.95.168.106/mips", "availability_status": "offline", "analysis_time": "2020-07-14T13:00:29", "analysis_id": "15947316295131c0" }, { "url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "final_url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "availability_status": "offline", "analysis_time": "2020-07-14T22:47:24", "analysis_id": "1594766844714193" } ], "next_page": "15874700660fc075d084e05839478b2f2e6056ec64b5f8ee48" } } ``` #### Retrieve a specific number of records Retrieving five records in JSON format, starting from UTC time 2020.06.08. 00:00:00 and providing the next page parameter `15916074711674f496007368cf5a54b5492ab59bdeaeea71c6`. Request: ``` /api/networking/url/v1/notifications/query/from/utc/2020-06-08T00:00:00/page/15916074711674f496007368cf5a54b5492ab59bdeaeea71c6?format=json&limit=5 ``` Response ``` json { "rl": { "urls": [ { "url": "http://45.95.168.106/mips", "final_url": "http://45.95.168.106/mips", "availability_status": "offline", "analysis_time": "2020-07-14T13:00:29", "analysis_id": "15947316295131c0" }, { "url": "http://107.174.206.110/bins", "final_url": "http://107.174.206.110/bins", "availability_status": "offline", "analysis_time": "2020-07-14T14:03:39", "analysis_id": "159473541917280d" }, { "url": "http://194.15.36.104/bins", "final_url": "http://194.15.36.104/bins", "availability_status": "offline", "analysis_time": "2020-07-14T14:18:45", "analysis_id": "159473632593312e" }, { "url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "final_url": "https://maximizemeasly.com/.well-known/pki-validation/BillingsCollections/odvr/", "availability_status": "offline", "analysis_time": "2020-07-14T14:46:54", "analysis_id": "1594738014894193" }, { "url": "https://ubadrium.com/", "final_url": "https://ubadrium.com/", "availability_status": "online", "analysis_time": "2020-07-14T16:05:04", "analysis_id": "159474270457d32c" } ], "next_page": "15916142651a3d50c943dc141d2713cc149f19449039e29e3e" } } ``` --- ## Analyze URL API (TCA-0404) — Spectra Intelligence This service provides comprehensive analysis of submitted URLs through advanced web intelligence gathering and threat detection capabilities. The analysis combines static file analysis, dynamic behavioral assessment, network infrastructure mapping, and visual documentation to deliver complete threat intelligence. The service supports three analysis workflows controlled by the optional `analysis_type` parameter: - **(parameter omitted)**: Downloads content from the submitted URL and from URLs found on that page. This is the most comprehensive analysis mode. - **`light`**: Downloads only the content from the submitted URL, skipping any linked content. - **`fileless`**: Skips downloading content entirely, focusing only on URL reputation and infrastructure analysis. ### Key Functionalities - Downloads and analyzes up to 50 samples per analysis (each up to 100 MB), with files processed through the ReversingLabs threat detection pipeline - Captures and analyzes the Document Object Model (DOM) to identify malicious JavaScript, hidden content, and dynamic page elements - Takes screenshots of analyzed pages for visual threat assessment and evidence collection - Resolves serving IP addresses, DNS records, and SSL/TLS certificate details for comprehensive infrastructure analysis - Gathers domain registration and ownership data to support attribution and threat actor profiling - Executes URLs in controlled sandbox environments to observe runtime behavior and detect evasive threats - Follows and documents complete redirection paths while analyzing each step in the chain - Files are downloaded only from the submitted URL, no recursion (crawl depth = 1) e.g. if a user submitted the following URL: `http://www.example.com/freshcontent`, only that URL will be crawled and `http://www.example.com/freshcontent/newest` will not ### Report Availability The report about the performed analysis and reputation information for the downloaded samples can be retrieved via the TCA-0403 URL Threat Intelligence service, along with a list of samples that were downloaded from the submitted URL. Reports become available before file analysis finishes. However, if you requested file downloads (default or `light` workflow), keep in mind that downloaded samples might take around 30 minutes from submission to have updated classification and metadata. When the processing is completed, the TCA-0403 URL Analysis Notification service will publish an alert and the analysis report will contain the latest data. Querying the TCA-0403 `/report` endpoint before the analysis is complete may return mixed data: the `last_analysis` object will be populated with new information, while the `statistics` object may still show old classification data. Within 10 minutes from submission, the `/downloaded_files` endpoint returns a list of downloaded samples, but their metadata and classifications will be populated with information obtained during previous URL analyses. ### Privacy and Data Handling All submitted URLs and downloaded files are treated as public data and accessible to all Spectra Intelligence users. For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls). ## Analyze URL Query This query requests an analysis of the submitted URL. Only one URL can be submitted per request. Submitting the same URL consecutively does not initiate new analyses until the first analysis has completed. ### Request ``` POST /api/networking/url/v1/analyze/query/{format} ``` Path parameters: - `format` - Defines the format of the request body (XML or JSON) - Required #### Request body ```json { "rl": { "query": { "url": "string", "response_format": "string", "analysis_type": "string" } } } ``` - `url` - Specifies the URL for which the analysis will be started. Provide the full URL of a website including the protocol (`https://www.example.org`). Only `http` and `https` protocols are supported. If the protocol is missing from the submitted URL, `http` will be automatically prepended to the URL. Note that URL normalization is performed during request submission, so duplicate and empty elements in the URL may be automatically removed or converted. - Required - `response_format` - An optional parameter that allows choosing the response format. Supported values are `xml` and `json`; the default is `xml`. - Optional - `analysis_type` - Controls content download. By default, the service downloads content from the submitted URL and from URLs found on that page. Use `light` to download only the content from the submitted URL. Use `fileless` to skip downloading content entirely. - Optional ### Response The response includes the submitted URL in a normalized format, information about the status of the analysis, and the `analysis_id` that can be further used to get a list of samples downloaded during that specific analysis. ``` json { "rl": { "requested_url": "string", "status": "string", "analysis_id": "string" } } ``` - `requested_url` - The submitted URL in normalized format. - `status` - Indicates the status of the analysis job for the requested URL. Returns **started** when the analysis job has been successfully initiated. No other status indicators are currently supported. - `analysis_id` - A 16 character string identifying the current analysis. ### Examples This example is for analyzing the URL *https://www.myabandonware.com* using JSON as the POST payload format, and requesting that the response is in JSON as well. For faster analysis, it is set to perform the analysis without downloading any content. #### Request `/api/networking/url/v1/analyze/query/json` ``` json { "rl": { "query": { "url": "https://www.myabandonware.com", "response_format": "json", "analysis_type": "fileless" } } } ``` #### Response ``` json { "rl": { "requested_url": "https://myabandonware.com/", "status": "started", "analysis_id": "159134594237612a" } } ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 403 | The server understood the request, but is refusing to fulfill it. A possible cause may be that the URL that was sent to analysis is already being analyzed. In this case, the API will also return an "Analysis in progress" message. | --- ## Domain Threat Intelligence API (TCA-0405) — Spectra Intelligence This service returns threat intelligence data for the submitted domain name. The reports contain domain reputation from various reputation sources, the maliciousness of files found on the submitted domain, and other metadata like last DNS records, related URLs, and related domains (subdomains, siblings). Information about the hosted files, last DNS records, related URLs, and domains comes from our internal databases and URLs submitted for analysis using the TCA-0404 Analyze URL service. ### Privacy and Data Handling Domains submitted for analysis using [TCA-0404 Analyze URL](/SpectraIntelligence/API/NetworkThreatIntel/tca-0404) are treated as public data and accessible to all Spectra Intelligence users. For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls). --- Users can send requests to the following endpoints: [**Domain report**](#domain-report) and [**Domain bulk report**](#domain-bulk-report) These endpoints return: - Third-party domain reputation and categorization - Counters of samples downloaded from the domain, mapped to their classification status (malicious, suspicious, known, unknown) - The most common threats (malware type, family) found on the domain - Last DNS records - Parent domain information [**Downloaded files endpoint**](#domain-downloaded-files) Provides a list of hashes and classifications for files downloaded from the submitted domain. The results can be filtered to return samples with specific classifications. If requested, the endpoint can return extended metadata for each file. Extended records contain: - Additional sample properties: SHA1 hash, MD5 hash, SHA256 hash, sample size, sample type, download availability of the sample, first and last seen dates, first and last download times, last download URL. - Sample reputation information: classification, threat level, trust factor, malware family name, malware type, threat name, targeted platform and subplatform. [**Related domains endpoint**](#domain-related-domains) A list of all subdomains that exist under the top parent domain of the submitted domain. For example, if a request is made with emails.azure.microsoft.com, a list of all subdomains under the top parent domain (microsoft.com) will be provided. [**Related URLs endpoint**](#domain-urls) Returns a list of URLs hosted on the submitted domain. [**Resolutions endpoint**](#domain-resolutions) Provides a list of a domain-to-IP mappings. **This API is rate limited to 5 requests per second.** ## Domain 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. ### Request ``` POST /api/networking/domain/report/v1/query/{format} ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Request body ``` json { "rl": { "query": { "domain": "string", "response_format": "string" } } } ``` - `domain` - The domain for which to retrieve the report. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional ### Response The returned report contains third party domain reputation and statistics, counters of downloaded samples mapped to their classification status (malicious, suspicious, known, unknown), the most common threats found on the domain, latest DNS records for the domain with the last change time, and last change time of any of the listed elements. Third party reputation data will always be present in the response, while other report sections might not. ```json { "rl": { "requested_domain": {}, "third_party_reputations": {}, "downloaded_files_statistics": {}, "parent_domain": "string", "last_dns_records": [], "top_threats": [], "last_dns_records_time": "string", "first_seen": "string", "last_seen": "string", "certificates": {}, "classification": "string", "reason": "string", "threat_level": 0, "threat_name": "string", "modified_time": {} } } ``` - `third_party_reputations` - Third party reputation data - `parent_domain` - TLD of the submitted domain - only returned for domains which are not TLD - `requested_domain` - The submitted domain - `top_threats` - Top 5 threats found on the domain - `last_dns_records_time` - last change time in DNS resolutions - `first_seen` - The first time when the requested domain was recorded in the ReversingLabs collection. This can be the first time when we checked the domain reputation against third-party sources, the first time we obtained metadata for the requested domain from ReversingLabs static/dynamic file processing services (related files), or the first time we analyzed a URL containing this domain. - `last_seen` - The last time when the requested domain received an indicator that updated its report. This can be the last time when we checked the domain reputation against third-party sources, the last time we obtained metadata for the requested domain from ReversingLabs static/dynamic file processing services (related files), or the last time we analyzed a URL containing this domain. - `certificates` - An object containing information about the SSL/TLS certificates associated with the requested domain, listed by port number (e.g., `443`). Each certificate entry includes metadata such as validity dates, version, signature algorithm, issuer, common name, serial number, thumbprints (MD5, SHA1, SHA256), and a list of certificate extensions with their criticality and values. - `classification` - ReversingLabs classification. Possible values are malicious, suspicious, known, or unknown. - `reason` - The reason why the domain was given a classification. This parameter is only shown if the classification is not `unknown`. Possible values are - `whitelist`, `blacklist` - The domain was found on a ReversingLabs curated whitelist/blacklist. - `domain_third_party_reputation` - Classification based on third-party reputation sources. - `user_override` - Classification overridden by you, or a user belonging to your organization. - `analyst_override` - Classification overridden by a ReversingLabs analyst. - `asn_blacklisted` - Classification based on the ASN being blacklisted. - `threat_level` - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known domains. For unknown domains, this value is omitted. **Applies to malicious and suspicious domains only** - `threat_name` - Standardized malware name indicating the type, platform, and family of the threat associated with the domain. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious domains only** - `modified_time` (deprecated) - Same as `last_seen` ### Credits Domain classification data uses information from third-party sources: © 2026 The Spamhaus Project SLU - [https://www.spamhaus.org/drop/terms/](https://www.spamhaus.org/drop/terms/) ---------------------------------------------------------------------- `rl.third_party_reputations.statistics` ```json { "malicious": 0, "suspicious": 0, "clean": 0, "undetected": 0, "total": 0 } ``` - `total` - The total number of consulted domain reputation sources - `malicious` - The number of sources that consider the domain malicious - `suspicious` - The number of sources that consider the domain suspicious - `clean` - The number of sources that consider the domain clean - `undetected` - The number of sources that do not have information about the domain ---------------------------------------------------------------------- `rl.third_party_reputations.sources[]` ```json { "source": "string", "provider": "string", "update_time": "string", "detection": "string", "detect_time": "string", "categories": [ "string" ] ``` - `source` - Name of the third party source - `provider` - Optional field, shows the source provider. - `detection` - Detection for the submitted domain. The possible values are **malicious/suspicious/clean/undetected**. If the source does not have any information about the domain, the value will be undetected. - `categories` - Domain categorization according to the source, e.g. phishing. Not all sources provide categorization information. - `update_time` - Time when the information from the source was last updated - `detect_time` - Time when the domain was last detected or given a category by the source. **Important: Entries containing the provider field are sourced from third-party security services via our data provider. We do not verify or guarantee the accuracy or completeness of this information.** The names and trademarks of third-party providers are used for identification purposes only and do not imply endorsement. ---------------------------------------------------------------------- `rl.downloaded_files_statistics` ```json { "unknown": 0, "known": 0, "suspicious": 0, "malicious": 0, "total": 0 } ``` - `total` - The total number of files downloaded from the domain - `known` - The number of files classified as KNOWN - `suspicious` - The number of files classified as SUSPICIOUS - `malicious` - The number of files classified as MALICIOUS - `unknown` - The number of files without classification ---------------------------------------------------------------------- `rl.certificates[]` ```json { "valid_from": "string", "valid_to": "string", "version": "string", "signature_algorithm": "string", "signature": "string", "serial_number": "string", "common_name": "string", "issuer": "string", "certificate_thumbprints": [ { "name": "string", "value": "string" } ], "extensions": [ { "is_critical": "string", "name": "string", "value": "string" } ] } ``` - `valid_from` - Start date of the certificate’s validity. - `valid_to` - Expiration date of the certificate. - `version` - X.509 version of the certificate. - `signature_algorithm` - Algorithm used to sign the certificate. - `signature` - The digital signature for the certificate. - `serial_number` - Serial number of the certificate. - `common_name` - Common Name (CN) for which the certificate is issued. - `issuer` - Name of the Certificate Authority that issued the certificate. - `certificate_thumbprints[]` - An array of thumbprints for the certificate in MD5, SHA1, and SHA256 formats. - `name`: Hashing algorithm used. - `value`: The thumbprint value. - `extensions[]` - X.509 certificate extensions. - `is_critical:` Indicates if the extension is marked critical. - `name`: Name of the extension. - `value`: Extension value content. ---------------------------------------------------------------------- `rl.top_threats[]` ```json { "threat_name": "string", "threat_level": 0, "files_count": 0 } ``` - `threat_name` - Name of the specific threat that was found - `threat_level` - Threat level based on threat_name - `files_count` - The number of files classified as that threat ---------------------------------------------------------------------- `rl.last_dns_records` ```json { "type": "string", "value": "string", "provider": "string" } ``` - `type` - Type of DNS resolution. - `value` - resolution value (IP) - `provider` - Source of resolution information ---------------------------------------------------------------------- ### Examples #### Retrieve a report (JSON) Retrieving a domain report in JSON format, using a JSON POST body ``` /api/networking/domain/report/v1/query/json ``` ``` json { "rl": { "query": { "domain": "www.stemalservice.it", "response_format": "json" } } } ``` #### Retrieve a report (JSON) for domain with no files Retrieving a domain report in JSON format, using a JSON POST body. The submitted domain has no files associated with it, but third party detections exist. ``` /api/networking/domain/report/v1/query/json ``` ``` json { "rl": { "query": { "domain": "mail.chat.whatsapp.sange.getsviip7.com", "response_format": "json" } } } ``` ## Domain bulk report This service returns threat intelligence data for the submitted domains. The report for each 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. The limit is 100 domains per request. ### Request ``` POST /api/networking/domain/report/v1/bulk_query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "domains": [ "string" ], "response_format": "string" } } } ``` - `domains` - The domains for which to retrieve the report. The limit is 100 domains per request. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional ### Response ```json { "rl": { "entries": [ { "requested_domain": {}, "third_party_reputations": {}, "downloaded_files_statistics": {}, "parent_domain": "string", "last_dns_records": [], "top_threats": [], "last_seen": "string", "certificates": {}, } ] } } ``` ## Domain downloaded files ### Request ``` POST /api/networking/domain/downloaded_files/v1/query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "domain": "string", "response_format": "string", "limit": 3, "extended": "string", "classification": "string" } } } ``` - `domain` - The domain for which to retrieve a list of files. - Required - `response_format` - Defines the POST body format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional - `extended` - Allows choosing between `true` - extended, and `false` - non-extended data set (default) - Optional - `classification` - If this parameter is provided in the request, the response will contain only samples that match the requested classification. Supported values are: `KNOWN`, `SUSPICIOUS`, `MALICIOUS`, `UNKNOWN` - Optional ### Response The response will contain metadata for files downloaded from the submitted domain. Empty fields are not included in the response. ```json { "rl": { "next_page": "string", "requested_domain": "string", "downloaded_files": [] } } ``` - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of records - `requested_domain` - The submitted domain - `downloaded_files` - A list of files and their metadata ---------------------------------------------------------------------- `rl.downloaded_files[]` ```json { "first_download": "string", "malware_type": "string", "classification": "string", "platform": "string", "subplatform": "string", "sample_type": "string", "sample_size": 0, "last_download_url": "string", "threat_name": "string", "sample_available": 0, "sha1": "string", "sha256": "string", "last_download": "string", "md5": "string", "first_seen": "string", "threat_level": 0, "trust_factor": 0, "malware_family": "string", "last_seen": "string" } ``` - `sha1` - The SHA1 hash of the file - `last_download_url` - The URL from which the file was last downloaded - `classification` - File classification. Can be one of the following: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN - `md5` - MD5 of the file - `sha256` - SHA256 of the file - `first_download` - Time when the file was first downloaded from the requested domain (UTC) - `last_download` - Time when the file was last downloaded from the requested domain (UTC) - `sample_available` - Indicates whether the sample is present in the ReversingLabs storage and available for download (true) or not (false). - `trust_factor` - Trustworthiness indicator for known samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). **Applies to known samples only** - `threat_name` - Complete malware threat name. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard): *platform-subplatform.type.familyname*. **Applies to malicious and suspicious samples only** - `threat_level` - Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). **Applies to malicious and suspicious samples only** - `malware_type` - The *type* part of the full threat name detected for the sample (for example, Trojan, Adware, Rootkit...). Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious samples only** - `malware_family` - The *familyname* part of the full threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat...).. **Applies to malicious and suspicious samples only** - `platform` - The platform targeted by the malware - `subplatform` - The subplatform targeted by the malware - `sample_type` - File type, as detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) - `sample_size` - File size (in bytes) - `first_seen` - Time when the sample was first seen in the ReversingLabs system (UTC) - `last_seen` - The last time when the file received impactful changes that updated its threat intelligence report. (UTC) ### Examples #### Retrieve files downloaded from a domain with extended metadata Get extended metadata about malicious files downloaded from *530908.selcdn.ru* using a JSON request. Request the response in JSON, and limit it to 1 item. Request: ``` /api/networking/domain/downloaded_files/v1/query/json ``` ``` json { "rl": { "query": { "domain": "530908.selcdn.ru", "limit": 1, "extended": true, "classification": "MALICIOUS", "response_format": "json" } } } ``` Response: ``` json { "rl": { "next_page": "7727ef8156fa0f9c013b7525c26bfc42c08fc8bc", "requested_domain": "530908.selcdn.ru", "downloaded_files": [ { "first_download": "2021-07-31T12:53:36", "threat_level": 5, "classification": "MALICIOUS", "threat_name": "Script-JS.Trojan.Cryxos", "subplatform": "JS", "last_seen": "2022-07-10T14:37:15", "sample_type": "Text/JavaScript", "last_download_url": "http://530908.selcdn.ru/0utllook-vvebs/kevn.htm", "sample_size": 111196, "sample_available": true, "sha1": "489712811cf611dfe4c8e8a6e3f7d57850021847", "platform": "Script", "last_download": "2021-07-31T12:53:36", "malware_type": "Trojan", "first_seen": "2021-07-31T05:24:58", "sha256": "ac582ad332d42964245da72ef5a240f54d96874d0bf044d6ce09ed8c0029a036", "trust_factor": 5, "malware_family": "Cryxos", "md5": "6e327edde38e71dc1196e743217010e9" } ] } } ``` ## Domain URLs This service provides a list of URLs associated with the requested domain. ### Request ``` POST /api/networking/domain/urls/v1/query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "domain": "string", "response_format": "string", "limit": 3 } } } ``` - `domain` - The domain for which to retrieve the URLs. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional ### Response The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default. ```json { "rl": { "next_page": "string", "requested_domain": "string", "urls": [] } } ``` - `requested_domain` - submitted domain - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions - `urls` - List of URLs ### Examples #### Retrieve URLs for a domain with paging Retrieving three records in JSON format, and providing the next page parameter `0030a7528573ce306ea2d0d9d66128b915bc95b1`. Request: ``` /api/networking/domain/urls/v1/query/json ``` ``` json { "rl": { "query": { "domain": "530908.selcdn.ru", "limit": 3, "response_format": "json", "page": "03c123eeca9351c35a7ac3f14832e58e20ccf35a" } } } ``` Response: ``` json { "rl": { "next_page": "05755cfc6fc64a755e3201f1c2b32af8f9e02752", "requested_domain": "530908.selcdn.ru", "urls": [ { "url": "http://530908.selcdn.ru/sharepoint-thunder-nasal-newsboy/index1.html/" }, { "url": "https://530908.selcdn.ru/0utlook-bookcook-blue-confused-territory/r.html?email=john.jones@jjrichards.com.au" }, { "url": "http://530908.selcdn.ru/general-vveb-online/gen.html" } ] } } ``` ## Domain resolutions ### Request ``` POST /api/networking/domain/resolutions/v1/query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "domain": "string", "response_format": "string", "limit": 3 } } } ``` - `domain` - The domain for which to retrieve the resolved IP addresses. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional ### Response The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default. ```json { "rl": { "requested_domain": "string", "resolutions": [], "next_page": "string" } } ``` - `requested_domain` - submitted domain - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions - `resolutions` - List of domain resolutions ---------------------------------------------------------------------- `rl.resolutions[]` ``` { "record_type": "string", "answer": "string", "last_resolution_time": "string", "provider": "string" } ``` - `record_type` - type of DNS record - `answer` - DNS query answer - `provider` - resolution source - `last_resolution_time` - last time the requested domain was resolved to this IP (UTC) ### Examples #### Retrieve resolutions for a domain with paging Retrieving five records in JSON format, and providing the next page parameter `1d083566ec3ce77ff4f5c033366de0ec2f1fe853`. Request: ``` /api/networking/domain/urls/v1/query/json ``` ``` json { "rl": { "query": { "domain": "google.com", "response_format": "json", "limit": 5, "page": "1d083566ec3ce77ff4f5c033366de0ec2f1fe853" } } } ``` Response: ``` json { "rl": { "resolutions": [ { "record_type": "A", "answer": "172.217.168.196", "last_resolution_time": "2020-09-28T15:00:02", "provider": "ReversingLabs" }, { "record_type": "A", "answer": "142.251.141.36", "last_resolution_time": "2024-03-01T01:02:19", "provider": "ReversingLabs" }, { "record_type": "A", "answer": "76.76.21.123", "last_resolution_time": "2023-12-08T17:32:05", "provider": "ReversingLabs" }, { "record_type": "A", "answer": "178.16.128.20", "last_resolution_time": "2024-01-16T20:55:25", "provider": "ReversingLabs" }, { "record_type": "A", "answer": "172.217.23.164", "last_resolution_time": "2021-01-21T10:42:40", "provider": "ReversingLabs" } ], "requested_domain": "google.com", "next_page": "1dfe7cf222f4f4369e74cfc6e90c640a357382f2" } } ``` ## Domain related domains This service provides a list of domains that have the same top parent domain as the requested domain. If the requested domain is a top parent domain, the API will return all subdomains. ### Request ``` POST /api/networking/domain/related_domains/v1/query/{format} ``` Path parameters: - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required Request body: ``` json { "rl": { "query": { "domain": "string", "response_format": "string", "limit": 3 } } } ``` - `domain` - The domain for which to retrieve the list of related domains. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional ### Response The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default. ```json { "rl": { "next_page": "string", "requested_domain": "string", "related_domains": [] } } ``` - `requested_domain` - submitted domain - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of domain resolutions - `related_domains` - List of related domains ---------------------------------------------------------------------- `rl.related_domains[]` ```json { "domain": "string" } ``` ---------------------------------------------------------------------- ### Examples #### Retrieve related domains for a domain with paging Retrieving five records in JSON format, and providing the next page parameter `07c9693a82ee38525a7d75727abfae1bf03d9e31`. Request: ``` /api/networking/domain/urls/v1/query/json ``` ``` json { "rl": { "query": { "domain": "google.com", "response_format": "json", "limit": 5, "page": "07c9693a82ee38525a7d75727abfae1bf03d9e31" } } } ``` Response: ``` json { "rl": { "next_page": "115b4399bbf7e431773694592c5b6cb5b2d6e749", "requested_domain": "google.com", "related_domains": [ { "domain": "mw1.google.com" }, { "domain": "r5---sn-5uaezne6.c.pack.google.com" }, { "domain": "script.google.com" }, { "domain": "442206.drive.google.com" }, { "domain": "lh3.google.com" } ] } } ``` --- ## IP Threat Intelligence API (TCA-0406) — Spectra Intelligence This service returns threat intelligence data for the submitted IP address. The reports contain IP address reputation from various reputation sources, the maliciousness of files found on the submitted IP address, and other metadata like related URLs and IP address resolutions. Information about the hosted files, related URLs, and IP address resolutions comes from our internal databases and URLs submitted for analysis using the TCA-0404 Analyze URL service. ### Privacy and Data Handling IPs submitted for analysis using [TCA-0404 Analyze URL](/SpectraIntelligence/API/NetworkThreatIntel/tca-0404) are treated as public data and accessible to all Spectra Intelligence users. For other queries (such as retrieving threat intelligence without submitting for analysis), information may be shared with third-party reputation sources as part of the lookup process. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls). --- Users can send requests to the following endpoints: [**IP report**](#ip-report) and [**IP bulk report**](#ip-bulk-report) These endpoints return: - Third-party IP address reputation and categorization. - Counters of samples downloaded from the IP address, mapped to their classification status (malicious, suspicious, known, unknown) - The most common threats (malware type, family) hosted on the submitted IP address - WHOIS registration and ownership data, if available and if `extended` is set to `true` - GeoIP data, if available and if `extended` is set to `true` [**Downloaded files endpoint**](#ip-downloaded-files) Provides a list of hashes and classifications for files found on the submitted IP address. The results can be filtered to return samples with specific classifications. If requested, the endpoint can return extended metadata for each file. Extended records contain: - Additional sample properties: SHA1 hash, MD5 hash, SHA256 hash, sample size, sample type, download availability of the sample, first and last seen dates, first and last download times, last download URL. - Sample reputation information: classification, threat level, trust factor, malware family name, malware type, threat name, targeted platform and subplatform. [**Related URLs endpoint**](#ip-urls) Returns a list of URLs hosted on the submitted IP address. [**Resolutions endpoint**](#ip-domain-resolutions) Provides a list of IP-to-domain mappings. **This API is rate limited to 5 requests per second.** ## IP 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. If available, WHOIS data about the submitted IP is also included in the response, as well as GeoIP data. ### Request ``` POST /api/networking/ip/report/v1/query/{format}?[extended=true|false] ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Query parameters - `extended` - Boolean; if set to true, the response will include WHOIS registration and ownership data for the IP address associated with the submitted URL, along with GeoIP data. - Default value: `false` #### Request body ``` json { "rl": { "query": { "ip": "192.168.1.1", "response_format": "json" } } } ``` - `ip` - The IP for which to retrieve the report. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `extended` - Boolean; if set to true, the response will include WHOIS registration and ownership data for the submitted IP address, along with GeoIP data - Default value: `false` ### Response The returned report contains third party reputation and statistics, counters of downloaded samples mapped to their classification status (malicious, suspicious, known, unknown), the top threats hosted on the submitted IP address, and last change time of any of the listed elements. Third party reputation data will always be present in the response, while other report sections might not. ```json { "rl": { "requested_ip": "string", "third_party_reputations": {}, "downloaded_files_statistics": {}, "top_threats": [], "last_seen": "string", "modified_time": "string" } } ``` ---------------------------------------------------------------------- `rl.third_party_reputations.statistics` ```json { "total": 0, "malicious": 0, "suspicious": 0, "clean": 0, "undetected": 0 } ``` - `total` - The total number of consulted IP reputation sources - `malicious` - The number of sources that consider the IP malicious - `suspicious` - The number of sources that consider the IP suspicious - `clean` - The number of sources that consider the IP clean - `undetected` - The number of sources that do not have information about the IP ---------------------------------------------------------------------- `rl.third_party_reputations.sources[]` ```json { "source": "string", "provider": "string", "update_time": "string", "detect_time": "string", "detection": "string", "category": "string" } ``` - `source` - Name of the third party source - `provider` - Optional field, shows the source provider. - `detection` - Detection for the submitted IP. The possible values are **malicious/suspicious/clean/undetected**. If the source does not have any information about the IP, the value will be undetected. - `categories` - IP categorization according to the source, e.g. phishing. Not all sources provide categorization information. - `update_time` - Time when the information from the source was last updated - `detect_time` - Time when the IP was last detected or given a category by the source. **Important: Entries containing the provider field are sourced from third-party security services via our data provider. We do not verify or guarantee the accuracy or completeness of this information.** The names and trademarks of third-party providers are used for identification purposes only and do not imply endorsement. ---------------------------------------------------------------------- `rl.downloaded_files_statistics` ```json { "known": 0, "unknown": 0, "suspicious": 0, "total": 0, "malicious": 0 } ``` - `total` - The total number of files downloaded from the IP - `known` - The number of files classified as KNOWN - `suspicious` - The number of files classified as SUSPICIOUS - `malicious` - The number of files classified as MALICIOUS - `unknown` - The number of files without classification ---------------------------------------------------------------------- `rl.top_threats` List of top 5 threats found at a given IP. Threats are ranked first by files_count and then by threat_level. ```json { "threat_name": "string", "threat_level": 0, "files_count": 0 } ``` - `threat_name` - Name of the specific threat that was found - `threat_level` - Threat level based on threat_name - `files_count` - The number of files classified as that threat ---------------------------------------------------------------------- `rl.third_party_reputations.whois` If requested and available, the response will include WHOIS data in the `rl.third_party_reputations.whois` array. These records contain registration and allocation details retrieved from regional WHOIS providers (such as RIPE or ARIN). Returned WHOIS records vary by source. The structure is not fixed, but typical fields may include: - `route` or `CIDR`: IP range. - `netname` or `NetName`: Name of the netblock. - `descr`: Description of the network entity. - `org`, `organisation`, or `Organization`: Owning organization. - `country`, `created`, `last-modified`, `source`, and others. **Note: Users should not assume a fixed schema. Always check field existence before processing.** **Example - WHOIS Format A (RIPE-style)** ```json { "rl": { "third_party_reputations":{ "whois": [ { "route": "153.128.64.0/18", "descr": "Some Company d.d", "origin": "AS37235", "mnt-by": "MIMECAST-MNT", "created": "2004-05-01T10:20:23Z", "last-modified": "2012-11-13T14:23:20Z", "source": "RIPE" }, { "inetnum": "153.128.64.0 - 153.128.127.255", "netname": "SC", "descr": "Some Company d.d.", "country": "HR", "org": "ORG-IA28-RIPE", "admin-c": "NP1462-RIPE", "tech-c": "II385-RIPE", "remarks": [ "This information has been partially mirrored by APNIC from", "RIPE. To obtain more specific information, please use the", "RIPE WHOIS Gateway." ], "last-modified": "2020-07-14T19:02:03Z", "source": "JPNIC" } ] } } } ``` **Example - WHOIS Format B (ARIN-style)** ```json { "rl": { "third_party_reputations":{ "whois": [ { "NetRange": "153.128.64.0 - 153.128.127.255", "CIDR": "153.128.64.0/18", "NetName": "FOOGLE", "NetHandle": "NET-153-128-64-0-1", "Parent": "NET1153 (NET-153-128-64-0-0)", "NetType": "Direct Allocation", "OriginAS": "AS15169", "Organization": "Foogle LLC (FOGL)", "RegDate": "2012-05-24", "Updated": "2012-05-24", "Ref": "https://rdap.arin.net/registry/ip/153.128.64.0" }, { "OrgName": "Foogle LLC", "OrgId": "FOGL", "Address": "1600 Foo Parkway", "City": "Mountain View", "StateProv": "CA", "PostalCode": "94043", "Country": "US", "RegDate": "2000-03-30", "Updated": "2019-10-31", "Comment": [ "Please note that the recommended way to file abuse complaints are located in the following links.", "To report abuse and illegal activity: https://www.foogle.com/contact/", "Regards,", "The Foogle Team" ], "Ref": "https://rdap.arin.net/registry/entity/FOGL" } ] } } } ``` ---------------------------------------------------------------------- `rl.geoip` If requested and available, the response will include GeoIP data in the `rl.geoip` object. This contains geographic location information for the submitted IP address. - `as` - Autonomous System Number for the IP address - `as_org` - Organization name associated with the Autonomous System - `network` - CIDR notation of the network block containing the IP - `location.city` - City where the IP is geographically located - `location.country.iso_code` - ISO 3166-1 alpha-2 country code - `location.latitude` - Geographic latitude coordinate - `location.longitude` - Geographic longitude coordinate **Example - GeoIP** ```json { "rl": { "geoip": { "as": "16625", "as_org": "Akamai Technologies, Inc.", "network": "92.123.36.0/22", "location": { "city": "Vienna", "country": { "iso_code": "AT" }, "latitude": 48.2082, "longitude": 16.3738 } } } } ``` ### Examples - report retrieval #### Retrieve a report (JSON) Retrieving an IP report in JSON format, using a JSON POST body ``` /api/networking/ip/report/v1/query/json ``` ``` json { "rl": { "query": { "ip": "216.239.34.36", "response_format": "json" } } } ``` #### Retrieve a report (JSON) for IP with no files Retrieving an IP report in JSON format, using a JSON POST body. The submitted IP has no files associated with it, but third party detections exist. ``` /api/networking/ip/report/v1/query/json ``` ``` json { "rl": { "query": { "ip": "149.28.54.212", "response_format": "json" } } } ``` ## IP bulk report This service returns threat intelligence data for the submitted IPs. The report for each contains IP reputation from various reputation sources, classification statistics for files downloaded from the IP, and the top threats hosted on the submitted IP. The limit is 100 IPs per request. ### Request ``` POST /api/networking/ip/report/v1/bulk_query/{format} ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Request body ``` json { "rl": { "query": { "ips": [ "string" ], "response_format": "string" } } } ``` - `ips` - The IPs for which to retrieve the report. The limit is 100 IPs per request. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional ### Response ```json { "rl": { "entries": [ { "requested_ip": "string", "third_party_reputations": {}, "downloaded_files_statistics": {}, "top_threats": [], "first_seen": "string", "last_seen": "string" } ] } } ``` ## IP downloaded files This service returns a list of files downloaded from the submitted IP address. ### Request ``` POST /api/networking/ip/downloaded_files/v1/query/{format} ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Request body ``` json { "rl": { "query": { "ip": "string", "response_format": "string", "limit": 3, "extended": "string", "classification": "string" } } } ``` - `ip` - The IP for which to retrieve a list of files. - Required - `response_format` - Defines the response format. The following values are supported: `xml` (default) and `json` - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional - `extended` - Allows choosing between `true` - extended, and `false` - non-extended data set (default) - Optional - `classification` - If this parameter is provided in the request, the response will contain only samples that match the requested classification. Supported values are: `KNOWN`, `SUSPICIOUS`, `MALICIOUS`, `UNKNOWN` - Optional ### Response The response will contain metadata for files downloaded from the submitted IP. Empty fields are not included in the response. ```json { "rl": { "requested_ip": "string", "next_page": "string", "downloaded_files": [] } } ``` - `requested_ip` - The submitted IP - `downloaded_files` - A list of files and their metadata - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of records ----------------------------------------------------------------------- `rl.downloaded_files[]` ```json { "first_download": "string", "threat_level": 0, "classification": "string", "last_seen": "string", "last_download_url": "string", "sample_size": 0, "sample_available": 0, "sha1": "string", "last_download": "string", "first_seen": "string", "sha256": "string", "trust_factor": 0, "md5": "string" } ``` - `sha1` - The SHA1 hash of the file - `last_download_url` - URL from which the file was last downloaded - `classification` - File classification. Can be one of the following: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN - `md5` - MD5 of the file - `sha256` - SHA256 of the file - `first_download` - Time when the file was first downloaded from the requested IP (UTC) - `last_download` - Time when the file was last downloaded from the requested IP (UTC) - `sample_available` - Indicates whether the sample is present in the ReversingLabs storage and available for download (true) or not (false). - `trust_factor` - Trustworthiness indicator for known samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). **Applies to known samples only** - `threat_name` - Complete malware threat name. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard): *platform-subplatform.type.familyname*. **Applies to malicious and suspicious samples only** - `threat_level` - Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). **Applies to malicious and suspicious samples only** - `malware_type` - The *type* part of the full threat name detected for the sample (for example, Trojan, Adware, Rootkit...). Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious samples only** - `malware_family` - The *familyname* part of the full threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat...). **Applies to malicious and suspicious samples only** - `platform` - The platform targeted by the malware - `subplatform` - The subplatform targeted by the malware - `sample_type` - File type, as detected by [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) - `sample_size` - File size (in bytes) - `first_seen` - Time when the sample was first seen in the ReversingLabs system (UTC) - `last_seen` - The last time when the file received impactful changes that updated its threat intelligence report. (UTC) ### Examples #### Retrieve files using pagination Get basic metadata about files downloaded from *37.34.248.24*, starting from page *54d1ec4a661e374661f04c2db29e1736dac62ff8*, using a **json** request. Limit the response to 2 items. Request: ``` /api/networking/ip/downloaded_files/v1/query/json ``` Response: ``` json { "rl": { "requested_ip": "37.34.248.24", "next_page": "5bbf9eb85c388624b367e46205dc62244544f33b", "downloaded_files": [ { "last_download_url": "http://rgyui.top/dl/build.exe", "sha1": "54d1ec4a661e374661f04c2db29e1736dac62ff8", "classification": "MALICIOUS" }, { "last_download_url": "http://acacaca.org/test3/get.php?first=true&pid=54CDD75ABCEFFD43CB02140E4B4CC293", "sha1": "596da184fb7a232c38144ebfd158af1e83224478", "classification": "KNOWN" } ] } } ``` #### Retrieve files downloaded from an IP address with extended metadata Get extended metadata about MALICIOUS files downloaded from *37.34.248.24* using a JSON request. Request the response in JSON, and limit it to 1 item. Request: ``` /api/networking/ip/downloaded_files/v1/query/json ``` ``` json { "rl": { "query": { "ip": "37.34.248.24", "limit": 1, "extended": true, "classification": "MALICIOUS", "response_format": "json" } } } ``` Response: ``` json { "rl": { "requested_ip": "37.34.248.24", "next_page": "54d1ec4a661e374661f04c2db29e1736dac62ff8", "downloaded_files": [ { "first_download": "2022-03-23T23:14:01", "threat_level": 5, "classification": "MALICIOUS", "threat_name": "Win32.Ransomware.StopCrypt", "last_seen": "2022-09-24T20:10:31", "sample_type": "PE/Exe", "last_download_url": "http://zerit.top/dl/build2.exe", "sample_size": 659968, "sample_available": true, "sha1": "1d61784e581389bfbb73fb6c3fdc9eb7af9af9b9", "platform": "Win32", "last_download": "2022-03-23T23:14:01", "malware_type": "Ransomware", "first_seen": "2022-03-21T19:42:44", "sha256": "082bf5ea5ae40e0328401f3e74b516e362ddc57c60ab194e1d2afd297ddf6e5e", "trust_factor": 5, "malware_family": "StopCrypt", "md5": "467f161440e8fac46258178e1b0784ca" } ] } } ``` ## IP URLs This service provides a list of URLs associated with the requested IP. ### Request ``` POST /api/networking/ip/urls/v1/query/{format} ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Request body ``` json { "rl": { "query": { "ip": "string", "response_format": "string", "limit": 3 } } } ``` - `ip` - The IP for which to retrieve the URLs. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional ### Response The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default. ```json { "rl": { "requested_ip": "string", "next_page": "string", "urls": [] } } ``` - `requested_ip` - submitted IP - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of analyzed URLs - `urls` - List of associated URLs ### Examples #### Retrieve URLs for specified IP with paging Retrieving three records in JSON format, and providing the next page parameter `0030a7528573ce306ea2d0d9d66128b915bc95b1`. Request: ``` /api/networking/ip/urls/v1/query/json ``` ``` json { "rl": { "query": { "ip": "104.19.138.57", "limit": 3, "response_format": "json", "page": "0030a7528573ce306ea2d0d9d66128b915bc95b1" } } } ``` Response: ``` json { "rl": { "next_page": "006ecec7f550cadfcbc0176ca2ace08ad1833d02", "requested_ip": "104.19.138.57", "urls": [ { "url": "https://google.com/url?cad=rja&esrc=s&rct=j&sa=t&source=web&uact=8&url=https://procrackerz.org/hitmanpro-crack-full-download/&usg=AOvVaw2qNutd2-aIy96HjHtql3Ww&ved=2ahUKEwiP4v79xZrxAhWotIsKHUMODTcQFjAAegQIBhAD" }, { "url": "https://google.com/maps/place/Vernier+Software+&+Technology/" }, { "url": "https://google.com/cse/cse.js?cx=014672437645974190520:sx5qa5dqcmm" } ] } } ``` ## IP domain resolutions This service provides a list of IP-to-domain mappings for the specified IP. ### Request ``` POST /api/networking/ip/resolutions/v1/query/{format} ``` #### Path parameters - `format` - Defines the POST body format. Supported values: `xml` and `json`. - Required #### Request body ``` json { "rl": { "query": { "ip": "string", "response_format": "string", "limit": 3 } } } ``` - `ip` - The IP for which to retrieve domain resolutions. - Required - `response_format` - Defines the response format. Supported values: `xml` and `json`. - Optional - `limit` - The number of files to return in the response. Default value: **1000** - Optional ### Response The endpoint will return a list of maximum **limit** records. If the **limit** value is not provided in the request, the maximum of 1000 records will be returned by default. ```json { "rl": { "requested_ip": "string", "next_page": "string", "resolutions": [] } } ``` - `requested_ip` - submitted IP - `next_page` - This value can be used with the `page` parameter in the next request to retrieve the next page of analyzed URLs - `resolutions` - List of associated resolutions ----------------------------------------------------------------------- `rl.resolutions` ```json { "last_resolution_time": "string", "host_name": "string", "provider": "string" } ``` - `host_name` - The domain resolves to requested IP - `last_resolution_time` - Most recent time IP has resolved to this domain - `provider` - Provider of this resolution ### Examples #### Retrieve domain resolutions for an IP with paging Retrieving five records in JSON format, and providing the next page parameter `07c9693a82ee38525a7d75727abfae1bf03d9e31`. Request: ``` /api/networking/ip/resolutions/v1/query/json ``` ``` json { "rl": { "query": { "ip": "37.34.248.24", "response_format": "json", "limit": 3, "page": "587196222d542cf07fbb337dc6c723810738214e" } } } ``` Response: ``` json { "rl": { "requested_ip": "37.34.248.24", "resolutions": [ { "provider": "ReversingLabs", "host_name": "zerit.top", "last_resolution_time": "2022-03-23T23:14:01" }, { "provider": "ReversingLabs", "host_name": "winnlinne.com", "last_resolution_time": "2022-10-07T00:29:41" }, { "provider": "ReversingLabs", "host_name": "abababa.org", "last_resolution_time": "2022-06-17T10:49:43" } ], "next_page": "6f4226f6457c9e24364d56dd3c047acbc1b25fc8" } } ``` --- ## Network Reputation API (TCA-0407) — Spectra Intelligence The Network Reputation service provides information regarding the reputation of a requested URL, domain, or IP address. The service provides ReversingLabs classification, along with an overview of detections from our partners. It also includes the category of the network location (for example phishing, gambling, adult content) and indicates whether we have encountered any malware samples associated with the submitted network location. The service supports both single and bulk queries. Bulk queries allow for a combination of URLs, domains, and IP addresses to be processed in the same request. ## General Info about Requests/Responses - All requests require the **post_format** parameter which supports two options: **xml** or **json**. - Default response format is **xml** - The number of URLs, domains or IP addresses in the request must not be greater than **100**. ### Privacy and Data Handling This API retrieves reputation information for URLs, domains, and IP addresses. It does not submit network locations for analysis. When querying this API, the queried network location may be shared with third-party reputation sources as part of the lookup process. To prevent this data sharing, use the `private` parameter in your request. When set to `true`, the queried network location and results are not shared with third-party sources and not included in public feeds. For comprehensive privacy considerations and best practices when using networking APIs, see [Privacy & Data Sharing](/General/SecurityAndAccessControl/Privacy#urls). ## Network Reputation Query This query returns reputation information about queried URLs, domains and IP addresses. ### Request ``` POST /api/networking/reputation/v1/query/{post_format} ``` Path parameters: - `post_format` - Required parameter that defines the POST payload format. Supported options are **xml** and **json**. #### Request body ``` json { "rl": { "query": { "network_locations": [ { "network_location": "string" }, { "network_location": "string", "type": "string" } ], "response_format": "string", "private": false } } } ``` - `network_locations` - A list of one or more network locations to be queried. - For every `network_location`, users can optionally set the `type` of the requested URI: `URL`, `IP` or `DOMAIN`. If the type isn't provided, the service will detect the URI type. - **Expected domain format:** fully qualified domain name using dots as separators, without any prefixes or suffixes. - **Expected URL format:** Submissions prefixed with a protocol name (`http://` and `https://`). - **Expected IP format:** IP address without any prefixes or suffixes (`1.2.3.4`). - Submissions that do not follow the expected formatting will be interpreted as follows: - A domain or IP with a slash (`domain.suffix/` or `1.2.3.4/`) will be treated as a URL. - Entries with multiple slashes at the end or prefixed by protocols (e.g., `https://1.2.3.4`, `1.2.3.4//` ) are also URLs. - Required - `response_format` - Defines the response format. Supported options are `xml` and `json`. The default is **xml**. - Optional - `private` - Boolean flag to process the query privately. When set to `true`, the submitted network location and query results are not shared with third-party sources and not included in public feeds. Default is `false`. - Optional ### Response The response contains reputation information for all valid requested network locations, along with the list of invalid network locations. ```json { "rl": { "entries": [] } } ``` ----------------------------------------------------------------------- `rl.entries[]` ```json { "type": "string", "requested_network_location": "string", "associated_malware": "bool", "last_seen": "string", "first_seen": "string", "third_party_reputations": {}, "classification": "string", "reason": "string", "threat_level": 0, "threat_name": "string", "categories": [] } ``` - `requested_network_location` - The requested URL, domain or IP address - `type` - The type of requested network location - `classification` - ReversingLabs classification. Possible values are malicious, suspicious, known, or unknown. - `categories` - List of categories that the URI in question belongs to (for example, phishing, news, retail, government, business_and_economy). List items are strings. The strings are arbitrary values obtained from third-party sources or from user overrides (using TCA-0408). - `first_seen` - Indicates the initial detection of the requested URL/domain/IP by a third-party source, the first instance of obtaining metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the first time the requested URL has been crawled or analyzed by the Spectra Sandbox. - `last_seen` - The last time when the requested URL/domain/IP received an indicator that updated its report. This can be the last time when we checked the URL/domain/IP reputation against third-party sources, the last time we obtained metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the last time the requested URL/domain/IP has been crawled or analyzed by the Spectra Sandbox. - `third_party_reputations` - Third party URL/domain/IP reputation counters showing the number of third party sources that detected the item as malicious/clean/undetected. - `associated_malware` - A boolean indicator showing if ReversingLabs downloaded malware from the submitted URL/domain/IP directly. The value does not rely on third-party results. - `reason` - The reason why the network location was given a classification. This parameter is only shown if the classification is not `unknown`. Possible values are - `whitelist`, `blacklist` - The network location was found on a ReversingLabs curated whitelist/blacklist. - `domain_third_party_reputation` - Classification based on third-party reputation sources. - `user_override` - Classification overridden by you, or a user belonging to your organization. - `analyst_override` - Classification overridden by a ReversingLabs analyst. - **Additional values for URLs:** - `file_reputation` - Classification based on the downloaded content. - `sandbox` - Classification based on dynamic analysis (ReversingLabs Cloud Sandbox). - `third_party_reputation` - Classification based on third-party reputation sources. - **Note:** If the classification reason was propagated from a URL redirection, it will be prefixed with `redirect_` (e.g `redirect_file_reputation`). - **Additional values for domains:** - `asn_blacklisted` - Classification based on the ASN being blacklisted. - `threat_level` - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known URIs. For unknown URIs, this value is omitted. **Applies to malicious and suspicious samples only** - In real-world situations, threat level values are typically interpreted in the following way: - Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex) - Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations) - Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains). - `threat_name` - Standardized malware name indicating the type, platform, and family of the threat associated with the URL. Conforms to the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard). **Applies to malicious and suspicious URIs only** ### Credits Domain classification data uses information from third-party sources: © 2026 The Spamhaus Project SLU - [https://www.spamhaus.org/drop/terms/](https://www.spamhaus.org/drop/terms/) ## Examples ### Example 1 A JSON URL query request and response. ``` /api/networking/reputation/v1/query/json ``` ``` json { "rl": { "query": { "network_locations": [ { "network_location": "http://icayus.com/wTpWgvg" } ], "response_format": "json" } } } ```
Response ``` json { "rl": { "entries": [ { "type": "url", "requested_network_location": "http://icayus.com/wTpWgvg", "associated_malware": false, "last_seen": "2024-04-16T07:12:50", "first_seen": "2024-03-11T19:15:10", "classification": "malicious", "reason": "third_party_reputation", "categories": [ "phishing", "spam", "suspicious", "scam_illegal_unethical", "uncategorized" ], "third_party_reputations": { "total": 19, "undetected": 17, "malicious": 2, "suspicious": 0, "clean": 0 } } ] } } ```
### Example 2 A JSON query including all supported types: URL, domain and IP address. Some are provided without the optional `type` field. ``` /api/networking/reputation/v1/query/json ``` ``` json { "rl": { "query": { "network_locations": [ { "network_location": "https://psychology-degree-programs-us.today/" }, { "network_location": "https://international-partnerships.ec.europa.eu/index_en", "type": "url" }, { "network_location": "www.stemalservice.it", "type": "domain" }, { "network_location": "216.239.34.36", "type": "ip" } ], "response_format": "json" } } } ```
Response ``` json { "rl": { "entries": [ { "type": "url", "requested_network_location": "https://psychology-degree-programs-us.today/", "associated_malware": false, "last_seen": "2024-04-16T07:19:54", "first_seen": "2024-01-24T19:17:44", "classification": "known", "reason": "file_reputation", "categories": [ "business_and_economy", "uncategorized" ], "third_party_reputations": { "total": 19, "undetected": 19, "malicious": 0, "suspicious": 0, "clean": 0 } }, { "type": "url", "requested_network_location": "https://international-partnerships.ec.europa.eu/index_en", "associated_malware": false, "last_seen": "2024-04-16T06:07:36", "first_seen": "2024-04-15T08:45:36", "classification": "known", "reason": "file_reputation", "categories": [ "government_legal", "government" ], "third_party_reputations": { "total": 19, "undetected": 19, "malicious": 0, "suspicious": 0, "clean": 0 } }, { "type": "domain", "requested_network_location": "www.stemalservice.it", "associated_malware": false, "last_seen": "2024-04-10T05:29:50", "first_seen": "2024-04-10T05:29:50", "third_party_reputations": { "total": 12, "undetected": 12, "malicious": 0, "suspicious": 0, "clean": 0 } }, { "type": "ip", "requested_network_location": "216.239.34.36", "associated_malware": false, "last_seen": "2024-04-15T10:42:56", "first_seen": "2024-02-16T22:41:05", "third_party_reputations": { "total": 11, "undetected": 11, "malicious": 0, "suspicious": 0, "clean": 0 } } ] } } ```
### Example 3 A JSON URL query, the result has a user classification override. ``` /api/networking/reputation/v1/query/json ``` ``` json { "rl": { "query": { "network_locations": [ { "network_location": "https://override-my-example.com" } ], "response_format": "json" } } } ```
Response ``` json { "rl": { "entries": [ { "type": "url", "requested_network_location": "https://override-my-example.com", "associated_malware": false, "last_seen": "2024-04-16T08:08:04", "first_seen": "2024-04-16T08:08:04", "classification": "malicious", "reason": "user_override", "categories": [ "Proxy Avoidance and Anonymizers" ], "third_party_reputations": { "total": 19, "undetected": 19, "malicious": 0, "suspicious": 0, "clean": 0 } } ] } } ```
## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 413 | The request contained more than the maximum allowed amount of network locations (100). | --- ## Network Reputation User Override API (TCA-0408) — Spectra Intelligence The Network Reputation User Override service enables URL and domain classification overrides and override removals. Any URL or domain can be overridden to malicious, suspicious, or known, and any classification override can be removed. Users can make up to a total of 100 overrides and override removals in a single request. Overrides are visible to all users within the same organization. The service also supports listing existing overrides. ## Network Location User Override Query This query sends network data to be overridden, and returns a list of network locations that were successfully overridden along with a list of invalid network locations and a list of network locations for which the override was successfully removed. All the parameters must be passed in the request body (either as JSON or XML). ### Request ``` POST /api/networking/user_override/v1/query/{post_format} ``` - `post_format` - allows choosing between XML and JSON format in the POST payload #### Request body ``` json { "rl": { "query": { "user_override": { "override_network_locations": [ { "network_location": "string", "type": "string", "TTL": "string", "classification": "string", "threat_level": "string", "categories": [ "string" ] } ], "remove_overrides": [ { "network_location": "string", "type": "string" } ] }, "response_format": "string" } } } ``` - `override_network_locations` - List of network locations that the user wants to override - Optional - `network_location` - Network location that the user wants to override. - Required - `type` - Type of URI that was listed in the `network_location` parameter. Supported types: `url`, `domain`. - Required - `TTL` - Specifies the duration (in seconds) for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration. - Optional - `classification` - Classification assigned to the network location in `network_location`. Allowed types correspond to the ReversingLabs classification scheme: `malicious`, `suspicious`, `known`, `unknown`. - Required - `threat_level` - Malware severity indicator for suspicious and malicious network locations, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the network location. For known network locations, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious network locations, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown network locations, setting the value is not allowed, and the value will default to `None`. - Optional - `categories` - List of categories that the URI in question belongs to. List items are strings. The strings are arbitrary values. - Optional - `remove_overrides` - List of network locations that the user wants to remove overrides from. Items in this list are objects. An object must contain two fields: `network_location` and `type`. These fields take in the same types of values as their equivalents in the `override_network_locations` parameter. - Optional - `response_format` - Allows choosing between XML and JSON format for the response. Default is `xml`. - Optional The request body of the query **must** contain the `override_network_locations` field or the `remove_overrides` field or **both**. ### Response ```json { "rl": { "user_override": { "created_overrides": [], "removed_overrides": [] } } } ``` `rl.user_override.created_overrides[]` and `rl.user_override.removed_overrides[]` ```json { "network_location": "string", "type": "string", "ttl": 0, "classification": "string", "categories": [ "string" ], "reason": "string", "threat_level": 0 } ``` - `created_overrides` - List of network locations for which overrides were created. - `network_location` - The overridden URI. - `type` - Type of URI that was listed in the `network_location` parameter. - `TTL` - Duration (in seconds) specified by the user for which an override is valid. It defines the lifespan of the override before it expires and needs to be reassessed or renewed. In case the TTL is not set, there will be no expiration. - `classification` - Classification that the user listed in the request. - `threat_level` - Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious URIs, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown URIs, setting the value is not allowed, and the value will default to `None`. - `categories` - List of categories that the requested URI belongs to. - `removed_overrides` - List of network locations from which overrides were removed, along with their type. - `invalid_network_locations` - List of invalid network locations. ## List User Network Location Overrides Query This query returns the list of overrides that the user has made. ### Request ``` GET /api/networking/user_override/v1/query/list_overrides?[format=xml|json]&next_network_location={next page SHA1}&type=[url|domain] ``` #### Query parameters - **next_network_location**: SHA1 hash of the next network location in the response. In case the response has reached the maximum number of entries for a single response (1000), paging is used. - **format**: response format (JSON/XML) - **type**: type of network location to filter by. Supported types: `url`, `domain`. Default value is `url`. ### Response format ```json { "rl": { "user_override": { "next_network_location": "string", "network_locations": [] } } } ``` ----------------------------------------------------------------------- `rl.user_override.network_locations[]` ```json { "network_location": "string", "type": "string", "classification": "string" } ``` - `network_location` - Network location (URI) that is overridden. - `type` - Type of network location. Supported types: `url`, `domain`. - `classification` - Classification assigned to the URI in `network_location`. Allowed types correspond to the ReversingLabs classification scheme: `malicious`, `suspicious`, `known`, `unknown`. - `expiration_time` - The specific time and date when the override will expire, calculated based on the TTL value provided. If the TTL is not set, the expiration_time will indicate no expiration. - `threat_level` - Malware severity indicator for suspicious and malicious URIs, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). In case the value is not set, default values will be assigned based on the classification of the URI. For known URIs, the allowed value is `0`. If the value is not set, the default value is `0`. For suspicious and malicious URIs, the allowed values are `1`, `2`, `3`, `4`, or `5`. If the value is not set, the default value is `5`. For unknown URIs, setting the value is not allowed, and the value will default to `None`. ----------------------------------------------------------------------- ## Examples ### Example 1 This request assigns an override to two network locations, and removes an existing override from a third network location. One of the new overrides is invalid. Request: ``` /api/networking/user_override/v1/query/json ``` ``` json { "rl": { "query": { "user_override": { "override_network_locations": [ { "network_location": "https://location-example.com", "type": "url", "classification": "malicious", "categories": [ "phishing" ] }, { "network_location": "http://test.com", "type": "url", "classification": "suspicious" } ], "remove_overrides": [ { "network_location": "https://example.com", "type": "url" } ] }, "response_format": "json" } } } ``` Response: ``` json { "rl": { "user_override": { "created_overrides": [ { "network_location": "https://location-example.com", "type": "url", "classification": "malicious", "categories": [ "phishing" ] } ], "removed_overrides": [ { "network_location": "https://example.com", "type": "url" } ], "invalid_network_locations": [ "http://test.com" ] } } } ``` ### Example 2 This request returns a list of overrides by the user. Request: ``` /api/networking/user_override/v1/query/list_overrides?format=json ``` Response: ``` json { "rl": { "user_override": { "network_locations": [ { "network_location": "https://location-example.com", "type": "url", "classification": "malicious" } ], "next_network_location": "9865c7ecda437034e1513cc43ae9a1f6f334bb7f" } } } ``` ### Example 3 This request returns a list of overrides by the user, in paginated form. Request: ``` /api/networking/user_override/v1/query/list_overrides?next_network_location=9865c7ecda437034e1513cc43ae9a1f6f334bb7f&format=json ``` Response: ``` json { "rl": { "user_override": { "network_locations": [ { "network_location": "https://location-example.com", "type": "url", "classification": "malicious" } ], "next_network_location": null } } } ``` ## Custom Response Status Codes This API implements custom response status codes. Find a complete list of possible HTTP response codes and their descriptions in the [General](../../index.md#response-status-codes) section of the documentation. | CODE | DESCRIPTION | | :--- | :---------- | | 413 | The request contained more than the maximum allowed amount of network locations (100). | --- ## Supply Chain Security APIs — Spectra Intelligence # Supply Chain Security APIs The Supply Chain Security APIs provide programmatic access to the Spectra Assure Community platform. These APIs allow you to search for software packages and retrieve detailed analysis reports. ## TCA-0701: Supply Chain Security API The [TCA-0701 Supply Chain Security API](./tca-0701.md) provides three main endpoints for interacting with the Spectra Assure Community platform: - **Search for Packages**: Search the catalogue by package URL (purl) or hash to find matching packages - **Show Package Details**: Retrieve metadata, version history, and analysis summaries for a specific package - **Show Version Report**: Get detailed analysis reports for a specific package version, including vulnerabilities, licenses, and quality metrics ## Common Use Cases - **Package Discovery**: Search the Spectra Assure Community catalogue by package URL (purl) or hash - **Package Analysis**: Retrieve detailed information about specific packages and their versions - **Risk Assessment**: Access quality metrics, vulnerability data, and threat classifications - **Compliance Monitoring**: Review license information and policy violations ## Available APIs --- ## Supply Chain Security API (TCA-0701) — Spectra Intelligence The Supply Chain Security API provides programmatic access to the Spectra Assure Community platform. Use this API to search for software packages and retrieve detailed analysis reports for packages and their versions. ## Search for Packages The Search for Packages API allows you to search the Spectra Assure Community catalogue for information on one or more software packages. You can search by providing either a purl (package URL) or a package hash (SHA1 or SHA256). The response contains a list of all software packages that match the search criteria, including package metadata, version information, quality assessments, and analysis results. ## Show Details About a Package The Show Package Details API allows you to retrieve detailed information about a software package specified in the request. By default, the response includes relevant package metadata and information about the latest published version of the software package. The response includes package identity, owner verification status, publication history, download statistics, quality assessments, risk indicators, incident reports, vulnerabilities, and available artifacts. ## Show Report for a Package Version The Show Package Version Report API allows you to retrieve detailed information about a software package version specified in the request. The response contains the Spectra Assure Community analysis report for the requested package version. The analysis report includes file details, analysis engine information, statistics on components and dependencies, license classifications, vulnerability details, quality metrics, policy violations, detection results, threat classifications, risk assessments, and behavioral indicators. --- ## CVE and In-the-Wild Exploits Feed — Spectra Intelligence The CVE and Exploit feeds provide information about files that exploit known vulnerabilities, collected in the wild from the Spectra Intelligence system. ## Common Use Cases ### Get CVE overview - **[CVEs exploited in the wild (TCF-0201)](tcf-0201.md)** - Daily overview of all CVE identifiers detected in the system. - **[Reports on CVEs exploited in the wild (TCF-0202)](tcf-0202.md)** - Detailed per-day reports with file hashes, threat names, and scan counts for each CVE. ### Get exploit samples - **[New exploit or CVE samples in the wild (hourly) (TCF-0203)](tcf-0203.md)** - Hourly feed of new files containing CVE or exploit identifications (first scans only). - **[New exploit or CVE samples in the wild (daily) (TCF-0204)](tcf-0204.md)** - Daily feed of new files containing CVE or exploit identifications (first scans only). ## All CVE and Exploit Feeds --- ## CVE Report Feed (TCF-0201) — Spectra Intelligence # CVEs exploited in the wild (TCF-0201) Daily CVE Exploit Feed returns all Common Vulnerabilities and Exposures (CVE) identifiers detected in the Spectra Intelligence system in a single day. These identifiers are related to **files that target vulnerabilities** (i.e. that contain exploits), **not files that are vulnerable**. These files have been collected in the wild and indicate exploitation of their respective vulnerability. We do not have information on the efficacy, targeting or prevalence of the exploit. This feed returns an **overview** of CVEs on any given day. The basis for this overview is *TCF-0202: Reports on CVEs Exploited in the Wild*, which also contains hashes and additional information related to these CVEs. An exploit is an application that uses a vulnerability or a flaw in another component (be it software or hardware) to impact the target's behavior in some way. In other words, it uses or communicates with its target in an unexpected or improperly handled way, usually resulting in a behavior change in the targeted program. Exploits can be remote or local, and the payload can range from allowing remote access or gaining elevated privileges, to downloading or dropping other malware. All known exploits are described in the Common Vulnerabilities and Exposures (CVE) system. The best way to deal with exploits is to prevent attacks by regularly updating software, but there is no efficient way to cope with the threats coming from the exploits that have not yet been patched, also known as zero-day exploits. The feed stores records for the last 365 days. ## Request This query returns an overview of all detected CVE identifiers (for the requested day). ``` GET /api/cve/v1/{date}[?format={json|xml}] ``` ### Request parameters `date` Required path parameter. It can be: - a specific date in the format `YYYY-MM-DD` - `latest` - `all_cves` If it is a specific date, the response includes results from 00:00 that day until 00:00 the next day. For example, `2023-04-20` will include results from *2023-04-20T00:00:00* to *2023-04-21T00:00:00*. Note that *how you specify the date range is different from how you do it in the "Reports on CVEs Exploited in the Wild" feed (TCF-0202)*, on which this feed is based (see TCF-0202 documentation for more details). The date **must** be in the last 365 days, excluding the current day. If the date is older than 365 days, the current day, or a day in the future, the service will respond with the status code **400 Bad Request**. If it is the string `latest`, the response is equivalent to passing yesterday's date. In other words, it includes the last complete 24-hour period between last midnight and the midnight before it. If it is the string `all_cves`, this is a special case where the response of the service is not based on a single day. Using this value will return all CVE identifiers found since the creation of this feed (2015-05-07). This request will take longer to complete. Depending on the network throughput and service availability, it may take over 30 minutes to complete. `format` Optional query parameter which defines the response format. It can be either `xml` or `json`. If this parameter is not provided, the response will be a plaintext response with CVE identifiers separated by a newline character. ## Response If the response format is JSON or XML, the response is a `rl.feed` object which contains: - `entries`: an array of CVE identifiers - `name`: feed name - `time_range`: - `to`: end time for the query - `from`: start time for the query ## Examples ### Example request ``` bash curl 'https://data.reversinglabs.com/api/cve/v1/2023-04-20?format=json' ``` ### Example response ``` json { "rl": { "feed": { "entries": [ "CVE-2006-3649", "CVE-2006-3590", "CVE-2006-3431", "CVE-2006-1359", "CVE-2006-1016", "CVE-2006-0022", "CVE-2006-0009", "CVE-2005-1790", "CVE-2004-1050", "CVE-2003-0347" ], "name": "Daily CVE Exploit", "time_range": { "to": "2023-04-21T00:00:00", "from": "2023-04-20T00:00:00" } } } } ``` --- ## CVE-to-Hash Feed (TCF-0202) — Spectra Intelligence # Reports on CVEs exploited in the wild (TCF-0202) This service provides detailed per-day reports on CVE identifiers associated with new malware in the Spectra Intelligence system. These identifiers are related to **files that target vulnerabilities** (i.e. that contain exploits), **not files that are vulnerable**. These files have been collected in the wild and indicate exploitation of their respective vulnerability. We do not have information on the efficacy, targeting or prevalence of the exploit. The report for each CVE identifier includes information about files tagged with that CVE, number of scans for each file, SHA1, MD5, and SHA256 hashes of each file, the threat name that the file received when it was scanned, and previous CVE identifiers for the file. If a sample has already been included in the feed sometime in the past, but has received a fresh antivirus scan, and - based on that scan - can be categorized as a CVE exploit, then that sample will be present in the results again. In other words, the same sample can be included in the results for different dates, provided that it has received a fresh scan on those dates. New scans are usually performed when a sample is uploaded from a new source, or if a rescan is requested by a customer. An exploit is an application that uses a vulnerability or a flaw in another component (be it software or hardware) to impact the target's behavior in some way. In other words, it uses or communicates with its target in an unexpected or improperly handled way, usually resulting in a behavior change in the targeted program. Exploits can be remote or local, and the payload can range from allowing remote access or gaining elevated privileges, to downloading or dropping other malware. All known exploits are described in the Common Vulnerabilities and Exposures (CVE) system. The best way to deal with exploits is to prevent attacks by regularly updating software, but there is no efficient way to cope with the threats coming from the exploits that have not yet been patched, also known as zero-day exploits. The feed stores records for the last 365 days. ## Daily CVE Report 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. If the requested day is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/report/cve/daily/v1/query/{time_format}/{time_value}[?format=xml|json] ``` #### Path parameters - `time_format` - 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); date (YYYY-MM-DD). - Required - `time_value` - Accepts values formatted according to the format set in the time_format parameter. It must not be the current date. If it is set to the current date, the service responds with the HTTPS status code 400. Values that are not provided as a full day will be rounded to midnight of the same day (for example, if the format is timestamp, querying 1430983979 is the same as querying 1430956800). - The date range behavior is different from the behavior of TCF-0201. If you query a date, you will get the results starting with midnight before that date, and ending with 00:00 on that date. For example, 2023-04-20 will include results from 2023-04-19T00:00:00 to 2023-04-20T00:00:00. In other words, the date specifies the end of a 24 hour period. - Required ##### Query parameters - `format` - Defines the response format. Accepts the following options: xml (default), or json - Optional ## Latest CVE Report The endpoint below returns the results from the latest full 24-hour period (midnight to midnight) for which we have data: ### Request ``` GET /api/report/cve/daily/v1/query/latest[?format=xml|json] ``` ### Response An empty **entries** field means there were no new CVE samples in the requested day rl \> cve_daily_report - `cve_id` - Mandatory field. This value represents a group of samples with the same exploit classification. - `total_count` - Mandatory field. This is the total count of samples in the **cve_id** exploit classification category. - `single_scan` - A group of samples that are scanned for the first time. If a sample is scanned multiple times on the day it was first seen, it will count as a single scan item. This field will be present only if not empty. - `multiple_scan` - A group of samples that were scanned multiple times. This field will be present only if not empty. Single_scan and multiple_scan share the same schema: rl \> cve_daily_report \> single_scan/multiple_scan - `count` - Mandatory field. An integer value that corresponds to the number of samples in the `samples` field. - `samples` - Mandatory field. A list of samples related to an exploit. rl \> cve_daily_report \> single_scan/multiple_scan \> samples - `sha1, sha256, md5` - Mandatory field. Hash values of the sample. - `threat_names` - Mandatory field. Shows a list of unique threat names the sample received when it was scanned. If the sample was scanned multiple times in a day, it can have multiple threat names. However, the large majority of samples have only one entry in this list. The last received threat name is in the last place. - `previous_cve_ids` - Optional field. A list of unique previous classifications for this sample, different from the current `cve_id` (for example, two scans that show two different results and classifications). ## Examples **Retrieving new exploits from 2015-05-07 00:00:00 till 2015-05-08 00:00:00** ``` /api/report/cve/daily/v1/query/timestamp/1430956800 /api/report/cve/daily/v1/query/date/2015-05-07 ``` In this case, the hour value in the timestamp format will be floor rounded to midnight of the requested day (same as querying 1430956800): ``` /api/report/cve/daily/v1/query/timestamp/1430983979 ``` --- ## CVE Changelog Feed (TCF-0203) — Spectra Intelligence # New exploit or CVE samples in the wild (hourly) (TCF-0203) 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. These identifiers are related to **files that target vulnerabilities** (i.e. that contain exploits), **not files that are vulnerable**. These files have been collected in the wild and indicate exploitation of their respective vulnerability. We do not have information on the efficacy, targeting or prevalence of the exploit. Information about the file download availability is included. Unlike *TCF-0201: CVEs Exploited in the Wild* and *TCF-0202: Reports on CVEs Exploited in the Wild*, this feed contains **first scans only**. If a sample has been scanned, it will be included in the results for that specific hour. If it was then rescanned, **it will not be included again**. An exploit is an application that uses a vulnerability or a flaw in another component (be it software or hardware) to impact the target's behavior in some way. In other words, it uses or communicates with its target in an unexpected or improperly handled way, usually resulting in a behavior change in the targeted program. Exploits can be remote or local, and the payload can range from allowing remote access or gaining elevated privileges, to downloading or dropping other malware. All known exploits are described in the Common Vulnerabilities and Exposures (CVE) system. The best way to deal with exploits is to prevent attacks by regularly updating software, but there is no efficient way to cope with the threats coming from the exploits that have not yet been patched, also known as zero-day exploits. The feed stores records for the last 365 days. ## Hourly Malware Detection Exploit Feed This query returns a recordset containing a list of malware samples that contain CVE or Exploit identifications and that were detected within the requested hour. The one-hour period is calculated upwards from the user's input. The input is rounded down to the nearest full hour. For example, the time value of 11:22 will be rounded down to 11:00 and the query will return the results for the period between 11:00 and 12:00. To search for detections between 13:00 and 14:00, it is enough to input any value between those two hours as the time value (13:19, 13:33, 13:54…). To search for detections between 14:52 and 15:52, two queries would need to be sent (one for detections between 14:00 and 15:00, and another for 15:00 to 16:00). If the requested hour / timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/detection/exploit/hourly/v2/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=true|false][&active_cve=true|false] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format`. Values that are not provided as a full hour will be rounded down to the closest full hour. For example: **time_value 1415714400** for **time_format timestamp** is the same as querying 1398517200; **time_value 2014-11-11T18:33:22** for **time_format utc** is the same as 2014-11-11T18:00:00 - Required - `sample_available` - When **true**, the result contains only the hashes of samples that are available for download (through Spectra Intelligence SamPle EXchange service) - Optional - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `active_cve` - When **true** (default), returns only exploits with active CVE identifiers. When **false**, returns only exploit [candidates](https://cve.mitre.org/about/faqs.html#cve_list_retire_term_cve). - Optional ## Latest Exploit Malware Detection Feed The endpoint below returns the results from the latest hour for which we have data: ### Request ``` GET /api/feed/malware/detection/exploit/hourly/v2/query/latest[?format=xml|json|tsv][&sample_available=true|false][&active_cve=true|false] ``` ### Response HTTP response code `404 Not Found` means that there were no new exploit malware detections in the given hour in Spectra Intelligence. rl \> feed \> entries - `scanner_count` - Number of scanners used in the last scan - `first_seen_on` - Indicates the date and time when the sample was first uploaded to the system, or when it has received a scan result for the first time - `cve_id` - Contains the Common Vulnerabilities and Exposures (CVE) identifier. Only available for samples with active CVE status, not for [candidates](https://cve.mitre.org/about/faqs.html#cve_list_retire_term_cve). - `scanner_percent` - Percent of scanners that detected malware in the last scan - `md5` - MD5 hash of the sample - `sha1` - SHA1 hash of the sample - `record_on` - Date when the entry was added to the feed - `scanner_match` - Number of scanners that detected malware in the last scan - `last_seen_on` - Indicates the date and time when the sample was last uploaded to the system, or the date and time of the last scan result it has received - `sample_type` - A description of the file - `active_cve` - Whether or not the sample holds the active CVE identification - `sha256` - SHA256 hash of the sample ## Examples **Retrieving new exploit malware detections between 2014-11-20 13:00:00 and 2014-11-20 13:59:59** ``` /api/feed/malware/detection/exploit/hourly/v2/query/timestamp/1416488400 /api/feed/malware/detection/exploit/hourly/v2/query/utc/2014-11-20T13:00:00 ``` In this case, the hour value in the timestamp format will be floor rounded to midnight of the requested day (same as querying 1416488400): ``` /api/feed/malware/detection/exploit/hourly/v2/query/timestamp/1416487800 ``` **Retrieving new exploit malware detections between 2014-11-20 13:00:00 and 2014-11-20 13:59:59 with active CVE identifiers only** ``` /api/feed/malware/detection/exploit/hourly/v2/query/timestamp/1416488400?active_cve=true ``` **Retrieving new exploit malware detections between 2014-07-24 12:00:01 and 2014-07-24 13:00:00 in JSON and XML format with the sample_available option** ``` /api/feed/malware/detection/exploit/hourly/v2/query/timestamp/1406204891?format=json&sample_available=true /api/feed/malware/detection/exploit/hourly/v2/query/timestamp/1406203200?format=xml&sample_available=true ``` **Retrieving the latest exploit malware detections in JSON and XML format** ``` /api/feed/malware/detection/exploit/hourly/v2/query/latest?format=json /api/feed/malware/detection/exploit/hourly/v2/query/latest?format=xml ``` **Retrieving the latest exploit malware detections in XML and JSON with the active_cve option** ``` /api/feed/malware/detection/exploit/hourly/v2/query/latest?format=json&active_cve=true /api/feed/malware/detection/exploit/hourly/v2/query/**latest?format=xml&active_cve=true** ``` --- ## CVE Exploit Feed (TCF-0204) — Spectra Intelligence # New exploit or CVE samples in the wild (daily) (TCF-0204) This service provides per-day information about new file hashes in the Spectra Intelligence system that contain CVE or Exploit identifications. These identifiers are related to **files that target vulnerabilities** (i.e. that contain exploits), **not files that are vulnerable**. These files have been collected in the wild and indicate exploitation of their respective vulnerability. We do not have information on the efficacy, targeting or prevalence of the exploit. Unlike *TCF-0201: CVEs Exploited in the Wild* and *TCF-0202: Reports on CVEs Exploited in the Wild*, this feed contains **first scans only**. If a sample has been scanned, it will be included in the results for that specific day. If it was then rescanned on another day, **it will not be included in the results for that day**. An exploit is an application that uses a vulnerability or a flaw in another component (be it software or hardware) to impact the target's behavior in some way. In other words, it uses or communicates with its target in an unexpected or improperly handled way, usually resulting in a behavior change in the targeted program. Exploits can be remote or local, and the payload can range from allowing remote access or gaining elevated privileges, to downloading or dropping other malware. All known exploits are described in the Common Vulnerabilities and Exposures (CVE) system. The best way to deal with exploits is to prevent attacks by regularly updating software, but there is no efficient way to cope with the threats coming from the exploits that have not yet been patched, also known as zero-day exploits. The feed stores records for the last 365 days. ## Daily Malware Exploit Feed This query returns a document containing the list of malware hashes (SHA1, SHA256) with CVE and Exploit identifications and their file type description for the requested day. If the requested day / timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/exploit/daily/v1/query/{time_format}/{time_value}[?format=json|xml|htsv][&sample_available=true|false] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format, **date** in the YYYY-MM-DD format. - Required - `time_value` - Accepts values in the format set by `time_format`. Values that are not rounded to a full day will be rounded down to the midnight of the requested date. For example, if the time format is `timestamp`, querying the value **1412036355** is the same as querying **1412035200**. If the time format is `utc`, querying the value **2014-09-30T10:32:12** is the same as querying **2014-09-30T00:00:00**. - Required - `sample_available` - When **true**, the result contains only the hashes of samples that are available for download (through Spectra Intelligence). - Optional - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **htsv** (Headless Tab Separated Values, delimiter character \t 0x09). - Optional ## Latest Malware Exploit Feed Use the "latest" endpoint to retrieve results from the latest day for which we have data: ### Request ``` GET /api/feed/malware/exploit/daily/v1/query/latest[?format=json|xml|htsv][&sample_available=true|false] ``` ### Response HTTP response code `404 Not Found` means there were no new malware exploits in Spectra Intelligence for the requested day. The first line of the response contains the day indicator in Unix timestamp format. Each malware sample record is listed on a separate line, with columns corresponding to SHA1, SHA256 and sample type description. The column separator is tab (**t, 0x0A**), and the line separator is line feed (**n, 0x0A**). ``` json {"rl": {"feed": "entries": [ {"sha256": "7b051ab689a9a29450dc0e752be5829b250f07ccef5ff7655751be0522fba503", "sha1": "a66db9f2b63a2b17ad8a29754bd7eea5c4427a6b", "sample_type": "Description of the file"}, "..." ] } } ``` ## Examples These examples request different response formats and use different time formats. **Fetching new malware detections between 2014-09-29 00:00:01 and 2014-09-30 00:00:00** ``` /api/feed/malware/exploit/daily/v1/query/timestamp/1412035200 /api/feed/malware/exploit/daily/v1/query/utc/2014-09-30T00:00:00 /api/feed/malware/exploit/daily/v1/query/date/2014-09-30 ``` In this case, the hour will be floor rounded to the midnight of the requested day (same as querying 1412035200): ``` /api/feed/malware/exploit/daily/v1/query/timestamp/1412036555 ``` In this case, the hour will be floor rounded to the midnight of the requested day (same as querying 2014-14-30T00:00:00): ``` /api/feed/malware/exploit/daily/v1/query/utc/2014-09-30T12:13:14 ``` **Fetching new malware detections from 2014-09-29 00:00:01 till 2014-09-30 00:00:00 for which samples are available for download** ``` /api/feed/malware/exploit/daily/v1/query/timestamp/1412035200?sample_available=true /api/feed/malware/exploit/daily/v1/query/date/2014-09-18?sample_available=true ``` **Fetching the list of the latest detections in JSON and XML format** ``` /api/feed/malware/exploit/daily/v1/query/latest?format=json /api/feed/malware/exploit/daily/v1/query/**latest?format=xml** ``` --- ## Certificate Indicators Feed — Spectra Intelligence The Certificate Indicator feeds provide continuous streams of code signing certificates and their associated samples, helping detect impersonation attempts and compromised certificates. ## Common Use Cases ### Track certificates signing malware - **[Certificate feed (TCF-0601)](tcf-0601.md)** - Continuous list of certificates with signed samples, filterable by classification. Includes certificate chain of trust and validation status. ## All Certificate Indicator Feeds --- ## Certificate Indicators Feed (TCF-0601) — Spectra Intelligence # Certificate feed (TCF-0601) The service provides a continuous list of certificates alongside the information about associated samples signed with the certificate(s). The feed output can be filtered by sample classification status - for example, it can return certificates that signed only malware samples (with samples being included). This is an easy way for a user to get valid and self-signed certificates that are being used in impersonation attempts. Basic records include sample SHA1 hash, certificate thumbprints, and the time the record was inserted into the feed. Extended records contain: - additional sample properties: SHA1 hash, MD5 hash, SHA256 hash, sample size, sample type, download availability of the sample, first and last seen dates (UTC), as well as the hashes of files containing the sample; - sample reputation information: classification, threat level, trust factor, malware family name, malware type, threat name, targeted platform and subplatform; - certificate properties: certificate status, date until the certificate was whitelisted, date since certificate is blacklisted, reason for whitelisting/blacklisting, first seen date, certificate threat level and trust factor; - certificate validation; - the certificate chain of trust. The response can be filtered by sample classification status. The feed stores records for the last 365 days. ## Certificate Feed ### Get feed data starting from the requested time The query returns certificate information and information about signed samples that was stored since the requested date and time. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. #### Request ``` GET /api/feed/certificate/v1/query/from/{time_format}/{start_time}[/page/{page}]?[format=xml|json]&[classification=MALICIOUS|SUSPICIOUS|KNOWN|UNKNOWN]&[limit=1-100]&[extended=true|false] ``` - `time_format` - Time format in which the date and time should be requested. It is possible to choose between `utc` and `timestamp` - Required - `start_time` - Time value that should be requested. If the chosen time format is `timestamp`, the time value should be an integer representing time. In case of UTC, the time value should be in the **%Y-%m-%dT%H:%M:%S** format - Required - `page` - An optional pagination parameter for retrieving the next page of the results. The pagination value for the next page is provided in the previous request response - Optional - `format` - An optional parameter that allows choosing the response format. Supported values are `xml` and `json`; the default is `xml` - Optional - `limit` - The maximum number of records to return in the certificate feed. It is possible to choose a number between 1 and 100; if the parameter is not provided in the request, defaults to 100 - Optional - `extended` - Allows choosing between extended ( `true`) and non-extended data set ( `false`); if the parameter is not provided in the request, defaults to `false` (non-extended) - Optional - `classification` - If this parameter is provided in the request, the query will return a list of only those records that match the requested sample's classification. It is possible to combine and request multiple classifications at once. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN - Optional #### Response The query will return records that were stored in the feed starting from the requested time. The records will be sorted in ascending order by their stored time. The API will return a list of maximum `limit` records. If the `limit` value is not provided in the request, 100 records will be returned by default. Response fields that will be returned depend on the selected data set. If the `extended` option is not set to `true`, the response will only include a list of records, each containing a sample SHA1 hash, certificate thumbprints, and the time the record was inserted into the feed. ##### Response fields **next_page** - hash value for the next page that can be used with the `page` parameter in the next request to retrieve more records **request** - `limit` - number of requested records - `extended` - requested data set - `response_format` - output format - `page` - page indicator (returned only if the `page` parameter is in the request) - `classification` - sample classification (returned only if the `classification` parameter is in the request) **certificate_feed** - `signatures` - Signature information is presented as a signature chain of trust. It includes information about counter-signatures and, recursively, issuer certificates until root certificate is reached. Individual certificate information includes the following fields: **common_name, valid_from, valid_to, signature_algorithm, signature, extensions, certificate_thumbprints, serial_number, version, issuer** - `sha1` - Sample SHA1 hash - `sha256` - Sample SHA256 hash - `md5` - Sample MD5 hash - `pe_sha1` (optional) - SHA1 authentihash of the PE file used in the authenticode signing process - `pe_sha256` (optional) - SHA256 authentihash of the PE file used in the authenticode signing process - `container_sha1` - SHA1 hash of the sample container - `first_seen` (optional) - Time when the sample was first seen in the ReversingLabs system (UTC) - `last_seen` (optional) - Time when the sample was last seen in the ReversingLabs system (UTC) - `sample_type` - Sample type - `sample_size` - Sample size in bytes - `sample_available` - Indicates whether the sample is available for download - `classification` - Classification of the sample - `platform` (optional) - Indicates the platform targeted by the malware - `subplatform` (optional) - Indicates the subplatform targeted by the malware - `threat_name` (optional) - Detected threat name for malicious and suspicious samples - `malware_type` (optional) - Malware type for malicious and suspicious samples - `malware_family` (optional) - Malware family for malicious and suspicious samples - `threat_level` (optional) - Threat level of the sample (returned only for samples classified as MALICIOUS and SUSPICIOUS) - `trust_factor` (optional) - Trust factor of the sample (returned only for samples classified as KNOWN) - `validation` - List of validation descriptions for a certificate associated with a sample at the time the sample was detected - `certificate_thumbprints` - MD5, SHA1, SHA256 thumbprints of the certificate used to sign the sample(s). MD5, SHA1 are available from October 2019. - `certificate_status` - Indicates whether the certificate is whitelisted/blacklisted/undefined - `whitelisted_to` (optional) - Property that applies only to certificates that were first whitelisted and then blacklisted. Indicates the date until which the certificate was considered whitelisted. The value returned here should correspond to the `blacklisted_from` field - `blacklisted_from` (optional) - Indicates the last valid signing time of a certificate that is now blacklisted - `reason` (optional) - Indicates the reason for whitelisting/blacklisting the certificate - `certificate_threat_level` (optional) - A property of blacklisted certificates expressed as a number in range \[0-5\] - `certificate_trust_factor` (optional) - A property of whitelisted certificates expressed as a number in range \[0-5\] - `certificate_first_seen` - Time when the certificate was first seen in the ReversingLabs system (UTC) ### Get the latest feed data The query returns the latest certificate information and the information about signed samples. #### Request ``` GET /api/feed/certificate/v1/query/latest[/page/{page}]?[format=xml|json]&[classification=MALICIOUS|SUSPICIOUS|KNOWN|UNKNOWN]&[limit=1-1000]&[extended=true|false] ``` - `page` - An optional pagination parameter for retrieving the next page of the results. The pagination value for the next page is provided in the previous request response - Optional - `format` - An optional parameter that allows choosing the response format. Supported values are `xml` and `json` format for the response; `xml` is default - Optional - `limit` - The maximum number of records to return in the certificate feed. It is possible to choose a number between 1 and 1000; if the parameter is not provided in the request, defaults to 1000 - Optional - `extended` - Allows choosing between extended ( `true`) and non-extended data set ( `false`); if the parameter is not provided in the request, defaults to `false` (non-extended) - Optional - `classification` - If this parameter is provided in the request, the query will return a list of only those records that match the requested sample's classification. It is possible to combine and request multiple classifications at once. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN - Optional #### Response The query returns records that were stored in the feed starting from 10 seconds before the request, ordered descending by stored time. The API will return a list of maximum `limit` records. If the `limit` value is not provided in the request, 1000 records will be returned by default. Response fields are the same as for the [Get feed data starting from the requested time query](#get-feed-data-starting-from-the-requested-time). ## Examples ### Example 1 Retrieving information starting from UTC time 27.09.2019. 00:00:00, listing three feed records, in JSON format. **Request** ``` GET /api/feed/certificate/v1/query/from/utc/2019-09-27T00:00:00?format=json&limit=3 ``` **Response**
Response ``` json { "rl": { "certificate_feed": [ { "certificate_thumbprints": [ { "name": "MD5", "value": "0907bfee555ef20b67fcb1c92bd48d52" }, { "name": "SHA1", "value": "aad10e16489a9f6bee789dfc171958b1db036a1c" }, { "name": "SHA256", "value": "48525B3B128B48FE54D437508F4EEE2CA89E1288621A7569CE48BB08AAC210FE" } ], "sha1": "5f5bb550099561881c5aca6fdd079418e31d2bb7", "inserted_on": "2019-09-27 00:00:15" }, { "certificate_thumbprints": [ { "name": "MD5", "value": "c678645d41a50cf837e645e6889a02f9" }, { "name": "SHA1", "value": "1a6ac0549a4a44264deb6ff003391da2f285b19f" }, { "name": "SHA256", "value": "BA215596C19AEC4E1D25D32D284474D6F824228B74621738F6EE2CE603C9EF2F" } ], "sha1": "69d185adde13eef094692862d41ff6d81c338f5d", "inserted_on": "2019-09-27 00:00:15" }, { "certificate_thumbprints": [ { "name": "MD5", "value": "1d0f25354806f80e67cc765acecbec29" }, { "name": "SHA1", "value": "61ebbc6cbf12d6afb3bc32f675428215043b7f6d" }, { "name": "SHA256", "value": "FC0028CF0C52E3399D1D1890FB6581F6AC44595619CA358428ECF968A95A3D99" } ], "sha1": "9b293548d6426a195f56cafba7de68202c548837", "inserted_on": "2019-09-27 00:00:15" } ], "next_page": "15695424159d492e84cb4eae1934793fcf2c77e53a61c13389", "request": { "limit": 3, "response_format": "json" } } } ```
### Example 2 Retrieving information starting from UTC time 27.09.2019. 00:00:00 with next page SHA1 15695424159d492e84cb4eae1934793fcf2c77e53a61c13389 listing three feed records, in JSON format. **Request** ``` GET /api/feed/certificate/v1/query/from/utc/2019-09-27T00:00:00/page/15695424159d492e84cb4eae1934793fcf2c77e53a61c13389?format=json&limit=3 ``` **Response**
Response ``` json { "rl": { "certificate_feed": [ { "certificate_thumbprints": [ { "name": "MD5", "value": "988eb04c9b0bbef5ed76054cc91b6a59" }, { "name": "SHA1", "value": "c82273a065ec470fb1ebde846a91e6ffb29e9c12" }, { "name": "SHA256", "value": "FFE713A0436DE7A5A6096F4B545DFC2339F2A0752E959C73EA078807405F53D6" } ], "sha1": "9d492e84cb4eae1934793fcf2c77e53a61c13389", "inserted_on": "2019-09-27 00:00:15" }, { "certificate_thumbprints": [ { "name": "MD5", "value": "4298e7e94db45ba5845048beea7b46b5" }, { "name": "SHA1", "value": "5f0ea4b93e4a403cf923937f0faa88ab6b3dffce" }, { "name": "SHA256", "value": "ADCB6EBA078AFC94FBBFC9E3627581C72FFB0AB8995AD47F18ACC04D65326192" } ], "sha1": "2ff2e55562e675bb5871e95dc0e136a3fccc0557", "inserted_on": "2019-09-27 00:00:18" }, { "certificate_thumbprints": [ { "name": "MD5", "value": "62fecb587eb46113c2afbbaadd422575" }, { "name": "SHA1", "value": "e9129f8eddc58d377003a3a11cb2688440330179" }, { "name": "SHA256", "value": "6F8E2A0358D3C3663C0DF69F5E5858906CE68CBFBAC6F01E2BF463BC350F7614" } ], "sha1": "318d5aedf2fab9127170e2da6d3d4fc4b8f91d6c", "inserted_on": "2019-09-27 00:00:18" } ], "next_page": "15695424185ad2fdd090d922caf6c3869675b62ce0e2c47e28", "request": { "limit": 3, "page": "15695424159d492e84cb4eae1934793fcf2c77e53a61c13389", "response_format": "json" } } } ```
### Example 3 Retrieving information starting from timestamp 1569542400, listing just one feed record, in JSON format, with an extended data set. **Request** ``` GET /api/feed/certificate/v1/query/from/timestamp/1674734311?format=json&limit=1&extended=true ``` **Response**
Response ``` json { "rl": { "certificate_feed": [ { "container_sha1": "797ddbf06404d87afd3b5280d8901b02308ead20", "signatures": { "counter_signatures": [ { "counter_signatures": null, "certificate": { "valid_from": "2022-09-21T00:00:00Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2033-11-21T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" }, { "is_critical": "True", "name": "X509v3 Extended Key Usage", "value": "Time Stamping" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 2.23.140.1.4.2\nPolicy: 2.16.840.1.114412.7.1\n" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:BA:16:D9:6D:4D:85:2F:73:29:76:9A:2F:75:8C:6A:20:8F:9E:C8:6F\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "62:8A:DE:D0:61:FC:8F:31:14:ED:97:0B:CD:3D:2A:94:14:DF:52:9C" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertTrustedG4RSA4096SHA256TimeStampingCA.crl\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertTrustedG4RSA4096SHA256TimeStampingCA.crt\n" } ], "signature": "55AA2A1AF346F378573730FC75E34FD68523F1FCF995399B25E6F7728A98C377D464FC15FB36C249512C7888635509463900FC69D4CA9B29FBA33FC0C9009B131DB09889DC78F2CD7C85CD539DAF62E26166A3142A45874A98422B50FC1BB59E083009FAE42DD7098979F909E688CE7D1BB86AA29BC1536009E8A3B89DD7AD1F1CB8EC9841F0F60E80FBE4FFDF9D10A7EB00BA5F4A8F1A3A52B4EABF0949153536599A0F54D2B21B7F7E5E09AD76548A746DCAD205672B76EBFF98B226953819884414E50A59A26BE7223E4421D23F1CC09BED7C48B2D8920C914F3C6694AF5D0253EB9EE29EE4D31F8601649C00C2E95A74750D3DE17988BF1C0197C9192380D7365A5F9616B1630CC646403BCE5D35D4593E439A18AEC3C9CBC3FB9B135F6AB5C7E0F305C359DF27622BDE41C953B9FF341067F62632987BFE5C42948194829DAC0A8BC64B154AD3989045603380E023DEF803A4F64547E5CEB8034247E841367177ADFDA2E897744E2EDA1E1D8C5AC81E9AD5C2F0C622A84F9BBDD81C9A51C42F9AF65FA72797BA962E8557C060E778567F6AEFC2959A4B1102C8829CC91A057CBA71B54E7A996CF4E89ED45A98C89FBF8DBB185C43F5D02AE8E262EE7804DBBDD1FB5B0AA8707EF0978478E308035D472C63A825389701D23F3ADAE5E5F6E69BDC7E2CCCFF174C4D00A2D8D6010EB88BEEE6E07255892C271961F677018C", "common_name": "DigiCert Timestamp 2022 - 2", "serial_number": "0C4D69724B94FA3C2A4A3D2907803D5A", "certificate_thumbprints": [ { "name": "MD5", "value": "c1b349871880f9359e1e241630313de9" }, { "name": "SHA1", "value": "f387224d8633829235a994bcbd8f96e9fe1c7c73" }, { "name": "SHA256", "value": "C7F4E1BE32288920ABE2263ABE1AC4FC4FE6781C2D64D04C807557A023B5B6FA" } ], "issuer": { "valid_from": "2022-03-23T00:00:00Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2037-03-22T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE, pathlen:0" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "BA:16:D9:6D:4D:85:2F:73:29:76:9A:2F:75:8C:6A:20:8F:9E:C8:6F" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F\n" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Time Stamping" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertTrustedRootG4.crt\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertTrustedRootG4.crl\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 2.23.140.1.4.2\nPolicy: 2.16.840.1.114412.7.1\n" } ], "signature": "7D598EC093B66F98A94422017E66D6D82142E1B0182E104D13CF3053CEBF18FBC7505DE24B29FB708A0DAA2969FC69C1CF1D07E93E60C8D80BE55C5BD76D87FA842025343167CDB612966FC4504C621D0C0882A816BDA956CF15738D012225CE95693F4777FB727414D7FFAB4F8A2C7AAB85CD435FED60B6AA4F91669E2C9EE08AACE5FD8CBC6426876C92BD9D7CD0700A7CEFA8BC754FBA5AF7A910B25DE9FF285489F0D58A717665DACCF072A323FAC0278244AE99271BAB241E26C1B7DE2AEBF69EB1799981A35686AB0A45C9DFC48DA0E798FBFBA69D72AFC4C7C1C16A71D9C6138009C4B69FCD878724BB4FA349B9776691F1729CE94B0252A7377E9353AC3B1D08490F94CD397ADDFF256399272C3D3F6BA7F166C341CD4FB6409B212140D0B71324CDDC1D783AE49EADE5347192D7266BE43873ABA6014FBD3F3B78AD4CADFBC4957BED0A5F33398741787A38E99CE1DD23FD1D28D3C7F9E8F1985FFB2BD87EF2469D752C1E272C26DB6F157B1E198B36B893D4E6F2179959CA70F037BF9800DF20164F27FB606716A166BADD55C03A2986B098A02BED9541B73AD5159831B462090F0ABD81D913FEBFA4D1F357D9BC04FA82DE32DF0489F000CD5DC2F9D0237F000BE4760226D9F0657642A6298709472BE67F1AA4850FFC9896F655542B1F80FAC0F20E2BE5D6FBA92F44154AE7130E1DDB37381AA12BF6EDD67CFC", "common_name": "DigiCert Trusted G4 RSA4096 SHA256 TimeStamping CA", "serial_number": "073637B724547CD847ACFD28662A5E5B", "certificate_thumbprints": [ { "name": "MD5", "value": "9e3e4fa44117441dba73c28e983fc05f" }, { "name": "SHA1", "value": "b6c8af834d4e53b673c76872aa8c950c7c54df5f" }, { "name": "SHA256", "value": "281734D4592D1291D27190709CB510B07E22C405D5E0D6119B70E73589F98ACF" } ], "issuer": { "valid_from": "2013-08-01T12:00:00Z", "signature_algorithm": "sha384WithRSAEncryption", "valid_to": "2038-01-15T12:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F" } ], "signature": "BB61D97DA96CBE17C4911BC3A1A2008DE364680F56CF77AE70F9FD9A4A99B9C9785C0C0C5FE4E61429560B36495D4463E0AD9C9618661B230D3D79E96D6BD654F8D23CC14340AE1D50F552FC903BBB9899696BC7C1A7A868A427DC9DF927AE3085B9F6674D3A3E8F5939225344EBC85D03CAED507A7D62210A80C87366D1A005605FE8A5B4A7AFA8F76D359C7C5A8AD6A23899F3788BF44DD2200BDE04EE8C9B4781720DC01432EF30592EAEE071F256E46A976F92506D968D687A9AB236147A06F224B9091150D708B1B8897A8423614229E5A3CDA22041D7D19C64D9EA26A18B14D74C19B25041713D3F4D7023860C4ADC81D2CC3294840D0809971C4FC0EE6B207430D2E03934108521150108E85532DE7149D92817504DE6BE4DD175ACD0CAFB41B843A5AAD3C305444F2C369BE2FAE245B823536C066F67557F46B54C3F6E285A7926D2A4A86297D21EE2ED4A8BBC1BFD474A0DDF67667EB25B41D03BE4F43BF40463E9EFC2540051A08A2AC9CE78CCD5EA870418B3CEAF4988AFF39299B6B3E6610FD28500E7501AE41B959D19A1B99CB19BB1001EEFD00F4F426CC90ABCEE43FA3A71A5C84D26A535FD895DBC85621D32D2A02B54ED9A57C1DBFA10CF19B78B4A1B8F01B6279553E8B6896D5BBC68D423E88B51A256F9F0A680A0D61EB3BC0F0F537529AAEA1377E4DE8C8121AD07104711AD873D07D175BCCFF3667E", "common_name": "DigiCert Trusted Root G4", "serial_number": "059B1B579E8E2132E23907BDA777755C", "certificate_thumbprints": [ { "name": "MD5", "value": "78f2fcaa601f2fb4ebc937ba532e7549" }, { "name": "SHA1", "value": "ddfb16cd4931c973a2037d3fc83a4d7d775d05e4" }, { "name": "SHA256", "value": "552F7BDCF1A7AF9E6CE672017F4F12ABF77240C78E761AC203D1D9D20AC89988" } ], "issuer": { "valid_from": "2022-08-01T00:00:00Z", "signature_algorithm": "sha384WithRSAEncryption", "valid_to": "2031-11-09T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F\n" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertAssuredIDRootCA.crt\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertAssuredIDRootCA.crl\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: X509v3 Any Policy\n" } ], "signature": "70A0BF435C55E7385FA0A3741B3DB616D7F7BF5707BD9AACA1872CEC855EA91ABB22F8871A695422EDA488776DBD1A14F4134A7A2F2DB738EFF4FF80B9F8A1F7F272DE24BC5203C84ED02ADEFA2D56CFF9F4F7AC307A9A8BB25ED4CFD143449B4321EB9672A148B499CB9D4FA7060313772744D4E77FE859A8F0BF2F0BA6E9F2343CECF703C787A8D24C401935466A6954B0B8A1568EECA4D53DE8B1DCFD1CD8F4775A5C548C6FEFA1503DFC760968849F6FCADB208D35601C0203CB20B0AC58A00E4063C59822C1B259F5556BCF27AB6C76CE6F232DF47E716A236B22FF12B8542D277ED83AD9F0B68796FD5BD15CAC18C34D9F73B701A99F57AA5E28E2B994", "common_name": "DigiCert Trusted Root G4", "serial_number": "0E9B188EF9D02DE7EFDB50E20840185A", "certificate_thumbprints": [ { "name": "MD5", "value": "8ddd0bc6d9d770eb6b2b671a862855cc" }, { "name": "SHA1", "value": "a99d5b79e9f1cda59cdab6373169d5353f5874c6" }, { "name": "SHA256", "value": "33846B545A49C9BE4903C60E01713C1BD4E4EF31EA65CD95D69E62794F30B941" } ], "issuer": "DigiCert Assured ID Root CA" } } } } } ] "certificate": { "valid_from": "2022-04-29T00:00:00Z", "signature_algorithm": "sha256WithRSAEncryption", "valid_to": "2024-05-01T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:68:37:E0:EB:B6:3B:F8:5F:11:86:FB:FE:61:7B:08:88:65:F4:4E:42\n" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "58:E5:82:F0:BE:FD:83:68:8C:A4:4A:5E:AA:80:78:F7:FE:80:36:1B" }, { "is_critical": "False", "name": "X509v3 Subject Alternative Name", "value": "othername:" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertTrustedG4CodeSigningRSA4096SHA3842021CA1.crl\n\nFull Name:\n URI:http://crl4.digicert.com/DigiCertTrustedG4CodeSigningRSA4096SHA3842021CA1.crl\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 2.23.140.1.3\n CPS: http://www.digicert.com/CPS\n" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertTrustedG4CodeSigningRSA4096SHA3842021CA1.crt\n" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:FALSE" } ], "signature": "1DB129B746C0E2F211D37F527B6B81B1553ABB96493CFCF6C9F68F7B1CC4F0C8E0E2FAFDC3AF766BCA16B5C64FF9325CCD8C2D0B1F55B7CD60C234D4F935CCBBEFFFADBB0999BE73C2A1F18419C7499C18199F0378DE5A04EBA61FAE9F00F0C64C7377E573CC4FCCD38B8CA1CB7ECC35F7971CFEA51E71E474E8E2EF8BBAD13CB3E69A079D04B5FFED4123BCA21ADD0723F9255052F01CBCCF065ADEA3EB8D572D32674EF270BB846421BA1B899D310131556C2E532E6B3862E80BC333F410FC127E109D98044E21AC63D5CBE7D8E7B02E89875892E09FBFD496592ED387DAFD41CCD9BB7E49125222D0024B1D10A584CFF59D03C806F08A2843CFD57CC9B8DDAC0DE1FA069EF38C7DDA4A98E3D56A9689F0DF2B1505AF8475F86A6A4D8393506AEAF105C8A01DC6518ED8BABB86D27B0828C788E61B097D78E9199FDA93F97B65641A57396444175A38103CA5B7EB4ECEF0CE52D1575D4C6DC45E62BE0AD28B759933D5475A356CB9903EB67454224CDDBE2A1CAA255E97B77DC00517DF49D13AE7D8368E030A420E3E9CB43BDDE9E9DCC4D2BAC6F27F8F27DDA37ABB48C7982F5B768C8A849A1F5F08DE000463F63D2A36210AF5B6706801FBBF49A385E3CA4C8369353482596926A3B6FFCC1487E821AC2684571C72ED9DF7A0FA713DF3D45FF9257722B500A4C6936FC2E5D9116CEB4116AD6DC268316888E6286EE92D3B", "common_name": "Adobe Inc.", "serial_number": "0C2896110788B129825FB1D1F6BAACA3", "certificate_thumbprints": [ { "name": "MD5", "value": "318362c1c531fb204e985e5b8fa561ef" }, { "name": "SHA1", "value": "b428bb409b67d9a4f701735cf06536c0c8c0f8f6" }, { "name": "SHA256", "value": "8CA6CFA8D13913048FEA73CAF4BAC4485C0005AAB2B87F461B6B5ED32F9A9270" } ], "issuer": { "valid_from": "2021-04-29T00:00:00Z", "signature_algorithm": "sha384WithRSAEncryption", "valid_to": "2036-04-28T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE, pathlen:0" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "68:37:E0:EB:B6:3B:F8:5F:11:86:FB:FE:61:7B:08:88:65:F4:4E:42" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F\n" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Code Signing" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertTrustedRootG4.crt\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertTrustedRootG4.crl\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 2.23.140.1.3\nPolicy: 2.23.140.1.4.1\n" } ], "signature": "3A23443D8D0876EE8FBC3A99D356E0021AA5F84834F32CB6E67466F79472B100CAAF6C302713129E90449F4BFD9EA37C26D537BC3A5D486D95D53F49F427BB16814550FD9CBDB685E0767E3771CB22F75AAA90CFF5936AE3EB20D1D55079889A8A8AC1B6BDA148187EDCD8801A111918CD61998156F6C9E376E7C4E41B5F43F83E94FF76393D9ED499CF4ADD28EB5F26A1955848D51AFED7273FFD90D17686DD1CB0605CF30DA8EEE089A1BD39E1384EDA6EBB369DFBE521535AC3CAE96AF1A23EDB43B833C84F38149299F5DDCE546DD95D02141F40337C03E295B2C221757352CB46D8C4341CA2A54B8DCD6F76372C853F1ACE26E918BE9007B0437F9588208270F0CCCAEFFD29355C1F893855F7378A8B09A1CB0BE9311AFF2E195C3971E1BE9CA70A06D62667B792E64E5FDE7AAC49CF2EA47492ADDB3CA49C861FE3C1561B2B23FF8FB5EA887B706BE6A0BAFD3A3F45A6C4E81691528B41C048844B964DAB4440E38DF01528CEEDF11856072A2F10C40C08643C338FAE288C3CCB8F880B0DBF3BF4CE1E7B8EEFB5EBCBB7F07713E6E7283FAC12AEA52F226C41F9825C1566CC6C0ECAC586C3F626330C074BA0D307026A6A4030484B34A85120BBAD1B8508E2590D6DCA05502BEA4A1C9EA5FDA0A71F0674E7F2D65290FDAF854821F9573BB49C03ED8645F4B4616EBF68E2266086EAC8AFA9FE941DE7631B3A8656784E", "common_name": "DigiCert Trusted G4 Code Signing RSA4096 SHA384 2021 CA1", "serial_number": "08AD40B260D29C4C9F5ECDA9BD93AED9", "certificate_thumbprints": [ { "name": "MD5", "value": "d91299e84355cd8d5a86795a0118b6e9" }, { "name": "SHA1", "value": "7b0f360b775f76c94a12ca48445aa2d2a875701c" }, { "name": "SHA256", "value": "46011EDE1C147EB2BC731A539B7C047B7EE93E48B9D3C3BA710CE132BBDFAC6B" } ], "issuer": { "valid_from": "2013-08-01T12:00:00Z", "signature_algorithm": "sha384WithRSAEncryption", "valid_to": "2038-01-15T12:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F" } ], "signature": "BB61D97DA96CBE17C4911BC3A1A2008DE364680F56CF77AE70F9FD9A4A99B9C9785C0C0C5FE4E61429560B36495D4463E0AD9C9618661B230D3D79E96D6BD654F8D23CC14340AE1D50F552FC903BBB9899696BC7C1A7A868A427DC9DF927AE3085B9F6674D3A3E8F5939225344EBC85D03CAED507A7D62210A80C87366D1A005605FE8A5B4A7AFA8F76D359C7C5A8AD6A23899F3788BF44DD2200BDE04EE8C9B4781720DC01432EF30592EAEE071F256E46A976F92506D968D687A9AB236147A06F224B9091150D708B1B8897A8423614229E5A3CDA22041D7D19C64D9EA26A18B14D74C19B25041713D3F4D7023860C4ADC81D2CC3294840D0809971C4FC0EE6B207430D2E03934108521150108E85532DE7149D92817504DE6BE4DD175ACD0CAFB41B843A5AAD3C305444F2C369BE2FAE245B823536C066F67557F46B54C3F6E285A7926D2A4A86297D21EE2ED4A8BBC1BFD474A0DDF67667EB25B41D03BE4F43BF40463E9EFC2540051A08A2AC9CE78CCD5EA870418B3CEAF4988AFF39299B6B3E6610FD28500E7501AE41B959D19A1B99CB19BB1001EEFD00F4F426CC90ABCEE43FA3A71A5C84D26A535FD895DBC85621D32D2A02B54ED9A57C1DBFA10CF19B78B4A1B8F01B6279553E8B6896D5BBC68D423E88B51A256F9F0A680A0D61EB3BC0F0F537529AAEA1377E4DE8C8121AD07104711AD873D07D175BCCFF3667E", "common_name": "DigiCert Trusted Root G4", "serial_number": "059B1B579E8E2132E23907BDA777755C", "certificate_thumbprints": [ { "name": "MD5", "value": "78f2fcaa601f2fb4ebc937ba532e7549" }, { "name": "SHA1", "value": "ddfb16cd4931c973a2037d3fc83a4d7d775d05e4" }, { "name": "SHA256", "value": "552F7BDCF1A7AF9E6CE672017F4F12ABF77240C78E761AC203D1D9D20AC89988" } ], "issuer": { "valid_from": "2022-06-09T00:00:00Z", "signature_algorithm": "sha384WithRSAEncryption", "valid_to": "2031-11-09T23:59:59Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "EC:D7:E3:82:D2:71:5D:64:4C:DF:2E:67:3F:E7:BA:98:AE:1C:0F:4F" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F\n" }, { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "False", "name": "X509v3 Extended Key Usage", "value": "Time Stamping" }, { "is_critical": "False", "name": "Authority Information Access", "value": "OCSP - URI:http://ocsp.digicert.com\nCA Issuers - URI:http://cacerts.digicert.com/DigiCertAssuredIDRootCA.crt\n" }, { "is_critical": "False", "name": "X509v3 CRL Distribution Points", "value": "\nFull Name:\n URI:http://crl3.digicert.com/DigiCertAssuredIDRootCA.crl\n" }, { "is_critical": "False", "name": "X509v3 Certificate Policies", "value": "Policy: 2.23.140.1.4.2\nPolicy: 2.16.840.1.114412.7.1\n" } ], "signature": "9A1602A501EF81FB0DB458B278ADA82319D97337DA609E51D7CBF82F40B9A31F7C404E333E903CE789017585E8627B1D56E071BADE5EC637BC795C62004DF8497A514D0632F3C5D2002A2720EA892E1539E02C3EF8757C2C824161350F23D0ED3595D288952943CBE0A658107C538E9F45C9203714C0ED19BA7E7739D25496C7A611DF3433F67552424B1C9D8D96D5956C471214245F2641FA1A46BDDEB0E5914703AC1808CBCBDB66897F2B9C65BFBE374EBE2DF39D4AC3CCCC475EC89595ADD1CBBB2A0620F93F72EA36EB4572927A297B14033CFB4DD648717A10118A0874CD6C1B045CD28A950376515053D62EF74A46C3AE102C714CB087B62737446044", "common_name": "DigiCert Trusted Root G4", "serial_number": "01240AFB1E380B8A16F14B719DF4D3C0", "certificate_thumbprints": [ { "name": "MD5", "value": "3291a2f1ac361c6bd3135018680eef08" }, { "name": "SHA1", "value": "18c57901aa5ec47719c39400e1239a7ef12e9270" }, { "name": "SHA256", "value": "4C913D04FB495DC36119552D6068F7B9891EFE40344E9E5C1E9132F65BAEFF7F" } ], "issuer": { "valid_from": "2006-11-10T00:00:00Z", "signature_algorithm": "sha1WithRSAEncryption", "valid_to": "2031-11-10T00:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F\n" } ], "signature": "A20EBCDFE2EDF0E372737A6494BFF77266D832E4427562AE87EBF2D5D9DE56B39FCCCE1428B90D97605C124C58E4D33D834945589735691AA847EA56C679AB12D8678184DF7F093C94E6B8262C20BD3DB32889F75FFF22E297841FE965EF87E0DFC16749B35DEBB2092AEB26ED78BE7D3F2BF3B726356D5F8901B6495B9F01059BAB3D25C1CCB67FC2F16F86C6FA6468EB812D94EB42B7FA8C1EDD62F1BE5067B76CBDF3F11F6B0C3607167F377CA95B6D7AF112466083D72704BE4BCE97BEC3672A6811DF80E70C3366BF130D146EF37F1F63101EFA8D1B256D6C8FA5B76101B1D2A326A110719DADE2C3F9C39951B72B0708CE2EE650B2A7FA0A452FA2F0F2", "common_name": "DigiCert Assured ID Root CA", "serial_number": "0CE7E0E517D846FE8FE560FC1BF03039", "certificate_thumbprints": [ { "name": "MD5", "value": "87ce0b7b2a0e4900e158719b37a89372" }, { "name": "SHA1", "value": "0563b8630d62d75abbc8ab1e4bdfb5a899b24d43" }, { "name": "SHA256", "value": "3E9099B5015E8F486C00BCEA9D111EE721FABA355A89BCF1DF69561E3DC6325C" } ], "issuer": { "valid_from": "2006-11-10T00:00:00Z", "signature_algorithm": "sha1WithRSAEncryption", "valid_to": "2031-11-10T00:00:00Z", "version": "2", "extensions": [ { "is_critical": "True", "name": "X509v3 Key Usage", "value": "Digital Signature, Certificate Sign, CRL Sign" }, { "is_critical": "True", "name": "X509v3 Basic Constraints", "value": "CA:TRUE" }, { "is_critical": "False", "name": "X509v3 Subject Key Identifier", "value": "45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F" }, { "is_critical": "False", "name": "X509v3 Authority Key Identifier", "value": "keyid:45:EB:A2:AF:F4:92:CB:82:31:2D:51:8B:A7:A7:21:9D:F3:6D:C8:0F\n" } ], "signature": "A20EBCDFE2EDF0E372737A6494BFF77266D832E4427562AE87EBF2D5D9DE56B39FCCCE1428B90D97605C124C58E4D33D834945589735691AA847EA56C679AB12D8678184DF7F093C94E6B8262C20BD3DB32889F75FFF22E297841FE965EF87E0DFC16749B35DEBB2092AEB26ED78BE7D3F2BF3B726356D5F8901B6495B9F01059BAB3D25C1CCB67FC2F16F86C6FA6468EB812D94EB42B7FA8C1EDD62F1BE5067B76CBDF3F11F6B0C3607167F377CA95B6D7AF112466083D72704BE4BCE97BEC3672A6811DF80E70C3366BF130D146EF37F1F63101EFA8D1B256D6C8FA5B76101B1D2A326A110719DADE2C3F9C39951B72B0708CE2EE650B2A7FA0A452FA2F0F2", "common_name": "DigiCert Assured ID Root CA", "serial_number": "0CE7E0E517D846FE8FE560FC1BF03039", "certificate_thumbprints": [ { "name": "MD5", "value": "87ce0b7b2a0e4900e158719b37a89372" }, { "name": "SHA1", "value": "0563b8630d62d75abbc8ab1e4bdfb5a899b24d43" }, { "name": "SHA256", "value": "3E9099B5015E8F486C00BCEA9D111EE721FABA355A89BCF1DF69561E3DC6325C" } ], "issuer": "DigiCert Assured ID Root CA" } } } } } } }, "classification": "KNOWN", "certificate_status": "undefined", "sample_available": "False", "first_seen": "2023-01-26 11:38:10", "threat_level": "0", "trust_factor": "5", "sample_type": "PE/Exe/UPX", "inserted_on": "2023-01-26 11:58:32", "sha256": "a3cca01bc2b3dd37ead4879d60a5dde3fb70f41daa45bde3aef9a68ee60ded74", "pe_sha256": "18854c7bcef20608507dc85a8bdce9fba6c29c6dcca4da1533925a7849fb0a9d", "certificate_first_seen": "2022-06-22 08:00:40", "certificate_thumbprints": [ { "name": "MD5", "value": "318362c1c531fb204e985e5b8fa561ef" }, { "name": "SHA1", "value": "b428bb409b67d9a4f701735cf06536c0c8c0f8f6" }, { "name": "SHA256", "value": "8CA6CFA8D13913048FEA73CAF4BAC4485C0005AAB2B87F461B6B5ED32F9A9270" } ], "md5": "aafff0742bb0b7bbc54163b512347554", "sha1": "797ddbf06404d87afd3b5280d8901b02308ead20", "pe_sha1": "ad4dcd1fbc10a6f8b192c1c958dcc44926fb1e9f", "sample_size": "2860856", "last_seen": "2023-01-26 11:58:27" } ], "next_page": "167473431280124d78601aa15e3ab5bf324ea41f84c8cab689", "request": { "limit": 1, "response_format": "json" } } ```
--- ## File Indicators Feed — Spectra Intelligence The Malicious File Indicator feeds provide continuous streams of newly detected malware samples, AV scan results, and classification changes from the Spectra Intelligence system. ## Common Use Cases ### Get newly detected malware - **[Malware detection feed (TCF-0101)](tcf-0101.md)** - Continuous list of samples with at least one AV detection. - **[Malware detection feed (platform-filtered) (TCF-0102-0106)](tcf-0102-0106.md)** - Malware detections filtered by platform (Windows, Android, macOS, etc.). ### Track all scanned files - **[New files (first scan) (TCF-0107)](tcf-0107.md)** - Files scanned for the first time in the system. - **[New files (first and rescan) (TCF-0108)](tcf-0108.md)** - All files scanned or rescanned. ### Monitor classification changes - **[Files with detection changes (TCF-0109)](tcf-0109-V3.md)** - Files showing detection changes between AV scans. - **[Malware presence change events feed (TCF-0111)](tcf-0111.md)** - New malicious samples, false positives, and threat name changes. ## All Malicious File Indicator Feeds --- ## Malicious Files Feed (TCF-0101) — Spectra Intelligence # Malware detection feed (TCF-0101) This service provides a continuous list of new samples with at least one antivirus scanner detection present in the Spectra Intelligence system. Samples that appear in this feed will not necessarily be classified as malicious by ReversingLabs, since antivirus scanner detections are only one of the components taken into consideration for the final classification verdict. Each record in the feed, besides hashes of the detected sample, includes some additional information about the samples, such as their file type and targeted platform. The following criteria define the types of samples that can enter this feed: - a public sample was scanned for the first time and a threat was detected (by at least one AV scanner) - a public sample was rescanned and a threat was detected during rescan (by at least one AV scanner) - a private sample became public and a threat was detected during rescan (by at least one AV scanner) The feed stores records for the last 365 days. ## Continuous Malware Detection Feed Query This query returns malware detections from the requested timestamp. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/detection/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=false|true][&limit=N] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. This field does not update, it shows sample availability at the time of entering the feed. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as the information about the sample's file type and targeted platform. An empty response is returned if no records for the requested timestamp are available. - `time_range` - The from/to time range of results - `entries` - A list of records, each returned as a separate item, containing SHA1, MD5, SHA256, sample_type, sample_size and targeted platform - `last_timestamp` - The timestamp of the last result. Increase by 1 in the next query to retrieve the next batch of results. The format will be the same as the requested time format. rl \> malware_detection_feed ### Response Examples ``` json {"rl": { "malware_detection_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "sample_type" : "sample_type_value", "sample_size" : "sample_size_value", "platform" : "platform_value" }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## PULL Query This query returns a list of malware detections since a particular point in time. The starting point for this query is defined using the [START query](#start-query). If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the limit parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled. ### Request ``` GET /api/feed/malware/detection/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true] ``` - `format` - Specifies the response format. The following values are supported: **xml** - default; **json**; **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response The response format is the same as in the [Continuous Malware Detection Feed Query](#continuous-malware-detection-feed-query). ## START Query This query sets the starting timestamp for the previously described *PULL* query. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/malware/detection/v1/query/start/[time_format]/[time_value] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required ### Response A successful query returns an **HTTP 200 OK** message with an empty response body. ## Examples ### Format query field **Fetching all new detections from 2017-03-26 10:33:20** ``` /api/feed/malware/detection/v1/query/timestamp/1490517200 /api/feed/malware/detection/v1/query/utc/2017-03-26T10:33:20 ``` **Fetching all new detections from 2017-03-26 10:33:20 with samples available in the storage** ``` /api/feed/malware/detection/v1/query/timestamp/1490517200?sample_available=true /api/feed/malware/detection/v1/query/timestamp/1490517200?sample_available=true&format=json ``` **Fetching all new samples from 2017-03-26 10:33:20 in JSON and XML formats** ``` /api/feed/malware/detection/v1/query/timestamp/1490517200?format=json /api/feed/malware/detection/v1/query/timestamp/1490517200?format=xml ``` **Setting the initial timestamp to 2017-03-26 10:33:20** ``` /feed/malware/detection/v1/query/start/timestamp/1490517200 ``` **Pulling records from the latest state** ``` /feed/malware/detection/v1/query/pull ``` ### Empty response example An empty response is returned if no records for the requested timestamp are available. To return the next batch of records, use the `last_timestamp` value incremented by 1. **JSON** ``` json { "rl": { "malware_detection_feed": { "entries": [], "last_timestamp": 1449745851, "time_range": { "from": "2017-03-26T10:33:20", "to": "2017-03-26T10:34:20" } } } } ``` --- ## File Indicators Feed (TCF-0102-0106) — Spectra Intelligence # Malware detection feed (platform-filtered) (TCF-0102-0106) This service provides information about new malware samples with detections in the Spectra Intelligence system. The samples are filtered by platform. The following criteria defines the types of samples that can enter this feed: - samples that have been scanned for the first time - samples that changed their classification to malicious after a rescan (available through an optional parameter, excluded by default) - samples that became available for download (their status changed from private to public) Samples will enter the feed only if their platform is detected as one of the supported platforms: The feed stores records for the last 365 days. ## Malware Detection Platform Feed Query This query returns a list of malware samples optionally filtered by platform since the requested timestamp. The feed will return at most 1000 records, or a little bit over 1000 if there are multiple records with the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/detection/platform/v1/query/{time_format}/{time_value}?platform={platform_name}&[platform={platform_name}...]&[format=xml|json|tsv][&rescans_included=false|true][&sample_available=false|true][&limit=N] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required - `platform` - The parameter accepts one or more values from the list of supported platform names. This parameter is optional and can be used to filter the samples by their detected platform value. Supported values are: Android, Boot, ByteCode, Document, DOS, Firmware, FreeBSD, iOS, Linux, MacOS, OS2, Palm, Script, Symbian, Unix, Unknown, Win32, Win64 - Optional - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `rescans_included` - If this parameter is set to `true`, the response will be expanded to include any samples that changed their classification to malicious after a rescan. - Optional - `sample_available` - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - `limit` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned. - Optional ### Response For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as information about the sample's file type. The `record_on` field is a timestamp that indicates when the sample has entered the feed, based on the feed criteria configured at that time. Every item also has the targeted platform for the sample. An empty response is returned if no records for the requested timestamp are available. - `time_range` - The from/to time range of results - `entries` - A list of records, each returned as a separate item, containing SHA1, MD5, SHA256, sample_type, record_on and targeted platform - `last_timestamp` - The timestamp of the last result. Increase by 1 in the next query to retrieve the next batch of results. The format will be the same as the requested time format. rl \> malware_detection_platform_feed ### Response Examples ``` json {"rl": { "malware_detection_platform_feed: { "entries": [ { "md5" : "md5_value", "platform" : "platform_value", "record_on" : "YYYY-MM-DDTHH:MM:SS", "sample_type" : "sample_type_value", "sha1" : "sha1_value", "sha256" : "sha256_value", }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, } } } ``` ## PULL Query This query returns the list of malware samples optionally filtered by platform since a particular point in time. The starting point for this query is defined using the `start_query`. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the **limit** parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. This ensures 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 request is fulfilled. ### Request ``` GET /api/feed/malware/detection/platform/v1/query/pull?platform={platform_name}&[platform={platform_name}...]&[format=xml|json|tsv][&sample_available=false|true][&rescans_included=false|true][&limit=N] ``` - `platform` - The parameter accepts one or more values from the list of supported platform names. This optional parameter can be used to filter samples by their detected platform value. Supported values are: Android, Boot, ByteCode, Document, DOS, Firmware, FreeBSD, iOS, Linux, MacOS, OS2, Palm, Script, Symbian, Unix, Unknown, Win32, Win64 - Optional - `format` - Specifies the response format. The following values are supported: **xml** - default; **json**; **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or not (false). Supported values are **false** (default) and **true**. - Optional - `rescans_included` - If this parameter is set to `true`, the response will be expanded to include any samples that changed their classification to malicious after a rescan. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response The response format is the same as in the `feed_query`. ## START Query This query sets the starting timestamp for the previously described `pull_query`. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/malware/detection/platform/v1/query/start/[time_format]/[time_value] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required ### Response A successful query returns an `HTTP 200 OK` message with an empty response body. ## Examples **Retrieving all new malware samples from 2020-05-01 10:33:20 with platform Android and iOS:** ``` /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Android&platform=iOS /api/feed/malware/detection/platform/v1/query/utc/2020-05-01T10:33:20?platform=Android&platform=iOS ``` **Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20 that are available for download:** ``` /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?sample_available=true&platform=Win32 /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?sample_available=true&platform=Win32&format=json ``` **Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20, and any malware samples that changed their classification to malicious following a rescan:** ``` /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?rescans_included=true&platform=Win32 ``` **Retrieving all new malware samples for the platform Win32 from 2020-05-01 10:33:20 in JSON and XML format:** ``` /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Win32&format=json /api/feed/malware/detection/platform/v1/query/timestamp/1588329200?platform=Win32&format=xml ``` **Setting the initial timestamp for the PULL query to 2020-05-01 10:33:20:** ``` /api/feed/malware/detection/platform/v1/query/start/timestamp/1588329200 ``` **Pulling records since the latest state:** ``` /api/feed/malware/detection/platform/v1/query/pull ``` ### Empty response example An empty response is returned if no records for the requested timestamp are available. To return the next batch of records, use the `last_timestamp` value incremented by 1. **JSON** ``` json { "rl": { "malware_detection_platform_feed": { "entries": [], "last_timestamp": 1588329200, "time_range": { "from": "2020-05-01T10:33:20", "to": "2020-05-01T10:34:20" } } } } ``` --- ## New Files Feed (First Scan) (TCF-0107) — Spectra Intelligence # New files (first scan) (TCF-0107) This service provides a continuous list of hashes for samples collected from various sources and scanned with the multi-AV scanning system for the first time in the Spectra Intelligence system. The feed stores records for the last 365 days. ## Continuous First Scan Feed This query returns hashes for samples collected from various sources and scanned with the multi-AV scanning system for the first time since the requested timestamp. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/first_scan/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=false|true][&limit=N] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the sample, as well as the information about the sample's file type. An empty response is returned if no records for the requested timestamp are available. - `time_range` - The from/to time range of results - `entries` - A list of records, each returned as a separate item, containing SHA1, MD5, SHA256, and sample_type - `last_timestamp` - The timestamp of the last result. Increase by 1 in the next query to retrieve the next batch of results. The format will be the same as the requested time format. rl \> malware_first_scan_feed ### Response Examples ``` json {"rl": { "malware_first_scan_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "sample_type" : "sample_type_value" }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## PULL Query For a given point in time, this query returns a list of hashes for samples collected from various sources that are scanned with the multi-AV scanning system for the first time. The starting point for this query is defined using the `start_query`. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the **limit** parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 request is fulfilled. ### Request ``` GET /api/feed/malware/first_scan/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true] ``` - `format` - Specifies the response format. The following values are supported: **xml** - default; **json**; **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response The response format is the same as in the `feed_query`. ## START Query This query sets the starting timestamp for the previously described `pull_query`. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/malware/first_scan/v1/query/start/[time_format]/[time_value] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required ### Response A successful query returns an `HTTP 200 OK` message with an empty response body. ## Examples **Retrieving all first-scanned samples from 2017-03-26 10:33:20:** ``` /api/feed/malware/first_scan/v1/query/timestamp/1490517200 /api/feed/malware/first_scan/v1/query/utc/2017-03-26T10:33:20 ``` **Retrieving all first-scanned samples from 2017-03-26 10:33:20 that are present in the storage:** ``` /api/feed/malware/first_scan/v1/query/timestamp/1490517200?sample_available=true /api/feed/malware/first_scan/v1/query/timestamp/1490517200?sample_available=true&format=json ``` **Retrieving all first-scanned samples from 2017-03-26 10:33:20 in JSON and XML format:** ``` /api/feed/malware/first_scan/v1/query/timestamp/1490517200?format=json /api/feed/malware/first_scan/v1/query/timestamp/1490517200?format=xml ``` **Setting the initial timestamp for the PULL query to 2017-03-26 10:33:20:** ``` /api/feed/malware/first_scan/v1/query/start/timestamp/1490517200 ``` **Pulling records since the latest state:** ``` /api/feed/malware/first_scan/v1/query/pull ``` ### Empty response example An empty response is returned if no records for the requested timestamp are available. To return the next batch of records, use the `last_timestamp` value incremented by 1. **JSON** ``` json { "rl": { "malware_first_scan_feed": { "entries": [], "last_timestamp": 1449745851, "time_range": { "from": "2017-03-26T10:33:20", "to": "2017-03-26T10:34:20" } } } } ``` --- ## New Files Feed (First and Rescan) (TCF-0108) — Spectra Intelligence # New files (first and rescan) (TCF-0108) 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 multi-AV scanner system. The feed stores records for the last 365 days. ## Continuous Malware Scan Feed Query This query returns a list of samples that have been scanned for the first time or rescanned since the requested time. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/scan/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=false|true][&limit=N] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required - `format` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as the information about the sample's file type. An empty response is returned if no records for the requested timestamp are available. - `time_range` - The from/to time range of results - `entries` - A list of records, each returned as a separate item, containing SHA1, MD5, SHA256, sample_type and the record_on field, indicating the date and time when the sample record was updated in the feed. The `single` field value indicates if the sample was scanned for the first time (`True`), or if it was rescanned (`False`). - `last_timestamp` - The timestamp of the last result. Increase by 1 in the next query to retrieve the next batch of results. The format will be the same as the requested time format. ``` json {"rl": { "malware_scan_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "record_on": "YYYY-MM-DDTHH:MM:SS", "sample_type": "file_type_description", "single": true|false}, }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## PULL Query This query returns a list of first-time scanned or rescanned samples from a particular point in time. The starting point for this query is defined using the `start_query`. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the `limit` parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled. ### Request ``` GET /api/feed/malware/scan/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true] ``` - `format` - Specifies the response format. The following values are supported: **xml** - default; **json**; **tsv** (Tab Separated Values, delimiter character t 0x09) - Optional - `sample_available` - Indicates whether the samples are present in the ReversingLabs storage and are available for download (true) or if they are not available (false). Supported values are **false** (default) and **true**. - Optional - `limit` - Number of records to return in the response. The maximum and default 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. - Optional ### Response The response format is the same as in the `feed_query`. ## START Query This query sets the starting timestamp for the previously described `pull_query`. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/malware/scan/v1/query/start/[time_format]/[time_value] ``` - `time_format` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - `time_value` - Accepts values in the format set by `time_format` - Required ### Response A successful query returns an `HTTP 200 OK` message with an empty response body. ## Examples ### Format query field **Fetching all new samples from 2017-03-26 10:33:20** ``` /api/feed/malware/scan/v1/query/timestamp/1490517200 /api/feed/malware/scan/v1/query/utc/2017-03-26T10:33:20 ``` **Fetching all new samples from 2017-03-26 10:33:20 that are present in storage** ``` /api/feed/malware/scan/v1/query/timestamp/1490517200?sample_available=true /api/feed/malware/scan/v1/query/timestamp/1490517200?sample_available=true&format=json ``` **Fetching all new samples from 2017-03-26 10:33:20 in JSON and XML format** ``` /api/feed/malware/scan/v1/query/timestamp/1490517200?format=json /api/feed/malware/scan/v1/query/timestamp/1490517200?format=xml ``` --- ## Daily File Indicators Feed (TCF-0109) — Spectra Intelligence # Files with detection changes (TCF-0109) This service provides a continuous list of records about samples in the Spectra Intelligence system that have been scanned for the first time, or that show detection changes in their multi-AV reports. The feed stores records for the last 365 days. ## Continuous Malware Scan Change Feed Query This query returns a list of sample hashes that have been scanned for the first time, or those that show detection changes between the two last multi-AV scanning system reports. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/malware/scan/change/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=true|false][&limit=N] ``` - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - ``time_value`` - Accepts values in the format set by time_format - Required - ``format`` - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09). - Optional - ``sample_available`` - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - ``limit`` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned. - Optional ### Response For the requested timestamp, the response contains a list of records. Every item in the list includes SHA1, MD5, and SHA256 hashes associated with the malware sample, as well as the information about the sample file type. If there are detection changes between the sample's last two multi-AV scanning system reports, every item will also contain a list of scanners for which changes have been recorded. Samples scanned for the first time will not contain this list of scanner changes. An empty response is returned if no records for the requested timestamp are available. ``` json {"rl": { "malware_scan_change_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "sample_type" : "sample_type_value", "record_on" : "YYYY-MM-DDTHH:MM:SS", "changed_result_scanners" : [ "scanner1_name", "scanner2_name", ... ] }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## PULL Query For a given point in time, this query returns a list of sample hashes which have been scanned for the first time, or which show detection changes between their two last multi-AV scanning system reports. The starting point for this query is defined using the `start-query`. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. When using the pull query continuously, it is useful to implement a pause between API requests to allow more results to accumulate in the feed, increasing the number of results returned per API request and reducing the total number of API calls needed. However, when catching up from a distant past timestamp, minimizing the pause between requests will speed up the process. Once the timestamp from the latest API response matches the current time, both methods (with and without pause) yield a similar number of records per unit of time. If you want to keep fetching the latest available records as they appear in the feed, you can use a short pause (e.g., 1 second) between requests. And if you need to catch up on a large backlog of data from the past, it is better to make continuous API calls without pausing. Unless the **limit** parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 request is fulfilled. ### Request ``` GET /api/feed/malware/scan/change/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true] ``` - ``format`` - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character t 0x09). - Optional - ``sample_available`` - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - ``limit`` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned. - Optional ### Response The response format is the same as in the `feed-query`. ## START Query This query sets the starting timestamp for the previously described `pull-query`. It is used to reprocess an already pulled time span, obtain data from an older period that was not previously retrieved, or skip ahead to a more recent timestamp when older data is no longer relevant. Resetting the start time in these cases helps manage the data retrieval process effectively. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/malware/scan/change/v1/query/start/[time_format]/[time_value] ``` - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - ``time_value`` - Accepts values in the format set by time_format - Required ### Response A successful query returns an **HTTP 200 OK** message with an empty response body. ## Examples **Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00:** ``` api/feed/malware/scan/change/v1/query/timestamp/1570197600 api/feed/malware/scan/change/v1/query/utc/2019-10-04T14:00:00 ``` **Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00 that are available for download:** ``` /api/feed/malware/scan/change/v1/query/timestamp/1570197600?sample_available=true /api/feed/malware/scan/change/v1/query/timestamp/1570197600?sample_available=true&format=json ``` **Retrieving all first-scanned samples or samples with changed scan results from 2019-10-04 14:00:00 in JSON and XML format:** ``` /api/feed/malware/scan/change/v1/query/timestamp/1570197600?format=json /api/feed/malware/scan/change/v1/query/timestamp/1570197600?format=xml ``` --- ## Malware Presence Change Events Feed (TCF-0111) — Spectra Intelligence # Malware presence change events feed (TCF-0111) The Malware Presence Change Events Feed provides a continuous list of new malicious samples, false positives (FPs) and malicious samples for which the ReversingLabs threat name changed. Event types included in the feed: - **New malicious** - event type representing files for which the classification changed to MALICIOUS (including false negatives - FNs) - **False positive (FP)** - event type representing files for which the classification changed from MALICIOUS or SUSPICIOUS to KNOWN - **Threat name changes** - event type representing malicious files for which the threat name changed By including *event_type* information in the response, the service enables users to filter records by event and easily get newly discovered samples that ReversingLabs classified as malicious, or information about false positive samples - malicious or suspicious samples for which the classification changed into *KNOWN* after rescanning. The service also provides information about threat name changes for malicious samples. The `threat_name` field is returned in the response for "New malicious" and "Threat name changes" event types. Threat names follow the [ReversingLabs malware naming standard](/General/AnalysisAndClassification/MalwareNamingStandard) (*platform-subplatform.malware_type.malware_family*). The following are examples of threat names formatted according to the standard: Win32.Ransomware.Teslacrypt Android.Trojan.Smsbot Script-JS.Downloader.Nemucod By comparing the `threat_name` fields in the response for the "Threat name changes" event type, users can track malware type changes, malware family changes, as well as changes in the affected platform. Similarly, based on the `threat_name` field information in the response for "New malicious" event type, users can compile a list of new malicious samples by specific platform, malware type, or malware family. The feed stores records for the last 365 days. ### ReversingLabs Malware Naming Standard ## PULL with timestamp This query returns samples with a newly calculated or changed malware presence classification and threat name, starting from the timestamp provided in the request. The feed will return at most 1000 records, or a little bit over 1000 if there are multiple records with the same timestamp. To retrieve the next batch of records, the timestamp from the response field `last_timestamp` should be increased by 1 and used in the subsequent query as the value of the `time_value` parameter. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/mwp_change_events/v1/query/{time_format}/{time_value}[?format=xml|json][&sample_available=false|true][&limit=N] ``` ### Request parameters - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - ``time_value`` - Accepts values in the format set by time_format - Required - ``format`` - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** - Optional - ``sample_available`` - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - ``limit`` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned. - Optional ### Response The response contains a list of records matching the requested timestamp. Every record in the list includes the following information: - SHA1, MD5, and SHA256 hashes associated with the sample, - event type, - sample classification, - threat name, - sample size, - sample type, - the timestamp of the update. An empty response is returned if no records for the requested timestamp are available. Response fields are described in the following table. Example responses can be found further in the document. Fields that do not appear in the response are considered empty. There will be no fields with empty or null values in the response. - `SHA1` - SHA1 of the sample - `SHA256` - SHA256 of the sample - `MD5` - MD5 of the sample - `event_type` - The type of event that triggered the record in the feed. Possible values: NEW_MALICIOUS; FP; THREAT_NAME_CHANGE - `classification` - Current Malware Presence status designation. The status designation is calculated by a proprietary ReversingLabs algorithm that adapts and improves as new information about the file and the threat is discovered. The algorithm takes the following into account: [Spectra Intelligence](https://www.reversinglabs.com/products/spectra-intelligence) antivirus scan results, threat and trust factors, parent/child relationships, certificates, and other metadata-specific information. - `threat_name` - Sample's detected threat name (*platform-subplatform.malware_type.malware_family*) - `sample_size` - Sample size (in bytes) - `sample_type` - Sample type - `record_on` - Timestamp of the update, indicating the date and time when the sample record was updated in the feed. ### Response Examples ``` json {"rl": { "mwp_change_events_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1": "21841b32c6165b27dddbd4d6eb3a672defe54271", "sha256": "2f6ed...55346", "md5": "3133c2231fcee5d6b0b4c988a5201da1", "event_type": "FP", "classification":"KNOWN", "sample_size":"636416", "sample_type":"PE/Exe", "record_on":"1470221633000" }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", -- the format is the same as the requested time format } } } ``` ``` json {"rl": { "mwp_change_events_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1": "21841b32c6165b27dddbd4d6eb3a672defe54271", "sha256": "2f6ed...55346", "md5": "3133c2231fcee5d6b0b4c988a5201da1", "event_type": "THREAT_NAME_CHANGE", "classification":"MALICIOUS", "threat_name":"Win32.Trojan.Nsis" "sample_size":"636416", "sample_type":"PE/Exe", "record_on":"1470221633000" }, {...}, … ], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", -- the format is the same as the requested time format } } } ``` ## PULL without timestamp For this query type, ReversingLabs is tracking the user's last query state, so the user doesn’t have to provide a timestamp in the request to retrieve the next batch of records. ### *PULL* Query This query returns a list of classification and threat name changes since a particular point in time. The starting point for this query is defined using the [START query](#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. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the limit parameter is specified, the feed returns up to 1000 records and any surplus records sharing 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. ### Request parameters - ``format`` - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json** - Optional - ``sample_available`` - If this parameter is set to `true` in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to `false`, the query will return all samples, regardless of their download availability status. The default is `false`, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - ``limit`` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all the records with the same timestamp are returned. - Optional ### Response format The response format is the same as in the PULL with timestamp. ## START Query This query sets the starting timestamp for the previously described *PULL* query. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/mwp_change_events/v1/query/start/[time_format]/[time_value] ``` ### Request parameters - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - ``time_value`` - Accepts values in the format set by time_format - Required ### Response A successful query returns an `HTTP 200 OK` message with an empty response body. ## Examples ### Format query field **Retrieving all new detections from 2019-05-09T07:25:10** \[GET\] ``` /api/feed/mwp_change_events/v1/query/timestamp/1557386701 /api/feed/mwp_change_events/v1/query/utc/2019-05-09T07:25:10 ``` **Retrieving all new detections from 2019-05-09T07:25:10 with samples available in the storage** \[GET\] ``` /api/feed/mwp_change_events/v1/query/timestamp/1557386701?sample_available=true /api/feed/mwp_change_events/v1/query/timestamp/1557386701?sample_available=true&format=json ``` **Retrieving all new samples from 2019-05-09T07:25:10 in JSON and XML formats** \[GET\] ``` /api/feed/mwp_change_events/v1/query/timestamp/1557386701?format=json /api/feed/mwp_change_events/v1/query/timestamp/1557386701?format=xml ``` **Setting the initial timestamp to 2017-03-26 10:33:20** \[PUT\] ``` /api/feed/mwp_change_events/v1/query/start/timestamp/1557386701 ``` **Pulling records from the latest timestamp** \[GET\] ``` /api/feed/mwp_change_events/v1/query/pull ``` --- ## Industry Sector Indicators Feed — Spectra Intelligence The Targeted and Industry-Specific Indicator feeds provide early-warning streams of malware samples filtered by industry category, including APT, Financial, Retail, Ransomware, CVE Exploits, and Malware Configuration. ## Common Use Cases ### Get industry-specific malware - **[Targeted and industry-specific file indicators (TCF-0401-0406)](tcf-0401-0406.md)** - Continuous feeds of malware samples filtered by category: - **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 These APIs provide statistics and search capabilities for the industry-specific feeds above: - **[Vertical feeds statistics (TCA-0307-0311, 0317)](/docs/SpectraIntelligence/API/MalwareHunting/tca-0307-0311_0317.md)** - Get weekly statistics on malware families by industry category. - **[Vertical feeds search (TCA-0312-0316, 0318)](/docs/SpectraIntelligence/API/MalwareHunting/tca-0312-0316_0318.md)** - Search for new malware hashes by family name within industry-specific feeds. ## All Targeted and Industry-Specific Feeds --- ## Industry Sector Indicators Feed (TCF-0401-0406) — Spectra Intelligence # Targeted and industry-specific file indicators (TCF-0401-0406) ReversingLabs Targeted and Industry-Specific File Indicator Feeds are early-warning feeds that provide information about new malware samples detected in the 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. - `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 ### Category Definitions Malware sample categories are defined by and consist of a set of malware families. **Financial** The Financial malware feed refers to the most common malware threats targeting the Financial Services industry. It currently tracks in excess of 70 malware families that are periodically updated. **Retail** The Retail malware feed refers to the most common malware threats targeting Retail organizations. **Ransomware** The Ransomware malware feed refers to the most common malware threats targeting almost all computer users. The most common method is by encrypting user files and demanding payment for the decryption key. **APT** The APT (Advanced Persistent Threat) malware feed refers to the most common malware threats which are government-sponsored or are precisely tailored for specific actions and/or targets. **Exploit** The Exploit feed refers to the most common malware threats which target and exploit known vulnerabilities, indexed by CVE number. An exploit is an application that uses a vulnerability or a flaw in another component (be it software or hardware) to impact the target's behavior in some way. In other words, it uses or communicates with its target in an unexpected or improperly handled way, usually resulting in a behavior change in the targeted program. Exploits can be remote or local, and the payload can range from allowing remote access or gaining elevated privileges, to downloading or dropping other malware. All known exploits are described in the Common Vulnerabilities and Exposures (CVE) system. The best way to deal with exploits is to prevent attacks by regularly updating software, but there is no efficient way to cope with the threats coming from the exploits that have not yet been patched, also known as zero-day exploits. **Malware Configuration** The Malware Configuration feed provides different kinds of malware samples, such as Keyloggers, RAT(s) or Ransomware that contain embedded configuration data. This data may include a list of servers that a given sample may contact; the ID of the malware campaign; passwords; malware installation location; mutexes; file names and more. Network information extracted from malware samples is unfiltered and presented as it was found. ## Malware Detection Family Feed Query ### Fetch detections since specified time This query returns a recordset of malware detections in the specified time range for a particular category. The categories correspond to ReversingLabs Targeted and Industry-Specific File Indicator Feeds, which are described in the [Category Definitions section](#category-definitions). Detections are included in the response based on the time when they were added to a particular feed. The time value provided in the query defines the starting point of the time range. If a detection has been added to one of the feeds in that time range, it is included in the response. #### Request ``` GET /api/feed/malware/detection/family/v2/query/{category}/{time_format}/{time_value}/?[format=xml|json] ``` The time range is defined as the period between the time specified by the `time_value` parameter and the time when the request is made. The earliest time value that the user can specify is 365 days before the current time. The latest time value is 60 seconds before the current time. Specifying a time value outside of these limits will return the status code **400 Bad Request**. The response can contain up to 1000 results. If the number of samples with the last timestamp included in the response goes above this limit, the results will be cut off. To get the next page of results, provide the `to` field value from the previous request as the `timestamp` value of the next request. This will cause some result duplication (specifically, records whose **record_on** value matches the **to** timestamp will reappear on the second page), but it will also return any remaining records with the matching timestamp that didn't fit on the first page. All time values are in UTC, independent of the input format. - `category` - Allows selecting a category to filter the results by a specific industry. Supported values: **apt, configuration, exploit, financial, ransomware, retail**. If the user doesn't have access to the requested category, or if the category doesn't exist, the query will return a `403 Forbidden` response - Required - `time_format` - Time format in which the date and time should be requested. It is possible to choose between `utc` and `timestamp` - Required - `time_value` - Accepts values in the format set by `time_format`. If the format is set to `utc`, the value should be expressed in the format **YYYY-MM-DDThh:mm:ss**. If the format is set to `timestamp`, the value should be expressed as the number of seconds since 1970-01-01 00:00:00. - Required - `count` - Allows specifying how many of the latest hashes in the selected category should be returned in the response. Accepts an integer in the range between 1 and 1000 ( 1 \<= `count` \<= 1000 ). The default value of the parameter is 100. Setting the `count` value too low may result in `from` and `to` timestamps being the same, which will cause a response loop. - Optional - `format` - An optional parameter that defines the response format. Supported values are `xml` and `json`. The default is `xml` and it is returned if this parameter is not provided in the request. - Optional ### Fetch the latest detections This query returns a recordset containing the latest Malware Family Feed detections for a particular category. #### Request ``` GET /api/feed/malware/detection/family/v2/query/{category}/latest?[format=xml|json]&[count=(1-1000)] ``` Submitting a GET request without any optional request arguments will return the latest 100 detections in the requested category. The `count` request parameter supports all integers between 1 and 1000, with 1 and 1000 included. Submitting the `count` parameter with anything other than integers in the supported range will result in a "400 Bad Request" response. The feed will return 100 records if the `count` parameter is not provided. Otherwise it will return the requested amount of records, starting from the most recent record in the data store. The most recent returned value can be 60 seconds before the current time. - `category` - Allows selecting a category to filter the results by a specific industry. Supported values: **apt, configuration, exploit, financial, ransomware, retail**. If the user doesn't have access to the requested category, or if the category doesn't exist, the query will return a `403 Forbidden` response - Required - `format` - An optional parameter that defines the response format. Supported values are `xml` and `json`. The default is `xml` and it is returned if this parameter is not provided in the request. - Optional - `count` - Allows specifying how many of the latest hashes in the selected category should be returned in the response. Accepts an integer in the range between 1 and 1000 ( 1 \<= `count` \<= 1000 ). The default value of the parameter is 100. - Optional ### Response Fields that do not appear in the response are considered empty. - `sha1` - Sample SHA1 hash - `record_on` - Time when the hash was added to a particular category - `sha256` - Sample SHA256 hash, if that information exists - `md5` - Sample MD5 hash, if that information exists - `container_hash` - SHA1 hash of the sample container; if the sample is not extracted from a container, then this value is identical to the `sha1` field - `priority` - Integer value (1-5) describing the importance of the entry for a particular industry (category). The value of 1 indicates the lowest priority, and 5 the highest. Lower values mean that the particular malware family is connected to some actor or other malware families related to the industry; not directly affecting the industry, but relevant to it - `family_name` - Malware family name - `first_seen_on` - Indicates when the hash was seen for the first time in the system (UTC) - `last_seen_on` - Indicates when the hash was last seen in the system (UTC) - `sample_available` - Boolean value indicating whether the sample is physically available for download. Note that even if this value is returned as true, it does not always mean the file is shareable (available for public download). To verify download availability, customers are advised to use the Sample Download API to attempt a file download. If the Sample Download API returns a 403 error, that indicates that the sample is not available for download, or is private - `sample_size` - Integer value that indicates the sample size in bytes - `sample_type` - String value describing the sample type (e.g., "Binary/Archive" ) - `tags` - A dictionary that contains `tag_types` as keys and `tag_list` as the value for each `tag_type` that is found in the configuration for a given detection - `bot_configs` - Key value list describing the configuration data embedded within the sample. Find more details in the **bot_configs** table - `cvssv2` - Key value list describing the vulnerability metadata found in samples from the Exploit category. Find more details in the **cvssv2** table **bot_configs** - `botFamily` - Malware family name - `botVersion` - Malware version - `botServer` - Command-and-control servers found in the malware configuration - `botRunMutex` - Mutex object names - `botIdentifier` - Unique malware sample or campaign identifier - `botInstallationPath` - The path into which the malware will attempt to install itself on infected systems - `botStartupKey` - Registry key(s) used at startup - `botStartupActiveX` - ActiveX startup string registry value - `botFileName` - Filename used by the malware on the infected system - `botPassword` - Password(s) used to establish a connection between the sample and the server **cvssv2** - `base_score` - String that can be converted to decimal in the range between 0.0 and 10.0 (precision is single decimal digit) - `integrity_impact` - Impact on integrity expressed as an enum value. Can be one of: "None", "Low", "High" - `availability_impact` - Impact on availability expressed as an enum value. Can be one of: "None", "Low", "High" - `attack_complexity` - Attack complexity expressed as an enum value. Can be one of the following: "Low", "Medium", "High" - `attack_vector` - enum value that can be one or more of the following: "Local", "Physical", "Network", "Adjacent network" - `confidentiality_impact` - Impact on confidentiality expressed as an enum value. Can be one of: "None", "Low", "High" ```xml Malware Detection Family Feed timestamp timestamp CATEGORY hash_hex_value hash_hex_value hash_hex_value container_sha1_value priority_value timestamp True|False family_name timestamp timestamp integer sample_type configurations, base_score impact impact complexity attack_vector impact tag1 tag2 ... ... ... … ... ``` ```json {"rl": {"feed": { "name": "Malware Detection Family", "time_range": { "from": "timestamp", "to": "timestamp" }, "category": CATEGORY, "entries": [{ "sha1": "hash_value", "record_on": "timestamp", "sha256": "hash_value", "md5": "hash_value", "container_hash": "container_hash_value", "priority": "priority_value", "sample_available": boolean, "family_name": "family_name", "first_seen_on": "timestamp", "last_seen_on": "timestamp", "sample_size": integer, "sample_type": "sample_type", "bot_configs":{ configurations }, "cvssv2": { "base_score": "base_score", "integrity_impact": "impact", "availability_impact": "impact", "attack_complexity": "complexity", "attack_vector": "attack_vector", "confidentiality_impact": "impact" }, "tags": { "tag_type1": ["tag1","tag2"], "tag_type2": [...], ... } }, ... ]} } } ``` #### Example JSON response with additional fields for CVE exploits ``` json {"rl": {"feed": { "name": "Malware Detection Family Feed", "time_range": { "from": "timestamp", "to": "timestamp" }, "category": "EXPLOIT", "entries": [{ "family_name": "CVE-2008-2992", "first_seen_on": 1471608000, "sha1": "9f83f1c87d16e73b6fb6cf65093b9ad4b5ca1382", "record_on": 1489592176, "cvssv2":{ "base_score": "9.3", "attack_complexity": "Medium", "attack_vector": "Network", "availability_impact": "High", "integrity_impact": "High", "confidentiality_impact": "High" }, "tags": { "affect": [ "Adobe Acrobat and Reader 8.1.2" ] }, }, ] } } } ``` #### Example JSON response with additional configuration settings fields ``` json {"rl": {"feed": { "name": "Malware Detection Family Feed", "time_range": { "from": "timestamp", "to": "timestamp" }, "category": "CONFIGURATION", "entries": [{ "family_name": "DarkComet", "sha1": "1316f23cd80a15a589f493b9155f537b4e8fab28", "record_on": 1506588587, "sample_type": "PE/Exe/DarkComet", "bot_configs":{ "botFamily": "DarkComet", "botIdentifier": "Vitima", "botInstallationPath": "MSDCSC\\\\msdcsc.exe", "botRunMutex": "DC_MUTEX-81883ZC", "botServer0": "romerinotraderpt.no-ip.org:1604", "botStartupKey": "MicroUpdate", "botVersion": "5.2 - 5.3" } }] }, } } ``` ### How to return more results from the feed The following two examples fetch the first and second page of results for the **retail** category using the `timestamp` parameter. The first request will search for entries newer than the provided timestamp (1477008000) and return 2 entries per page (in practical use, this number should be higher, 2 was only used as an example). #### Request ``` GET /api/feed/malware/detection/family/v2/query/retail/timestamp/1477008000?format=json&count=2 ``` **First page response in JSON** ```json { "rl": { "feed": { "category": "RETAIL", "entries": [ { "family_name": "ChewBacca", "sha1": "5e9dd2f849831355faea86bef2f75918d6b8a025", "record_on": 1477010349, "first_seen_on": 1477009751, "last_seen_on": 1477009800, "priority": 5, "sample_available": true, "container_hash": "5e9dd2f849831355faea86bef2f75918d6b8a025", "sha256": "2019fc174249565f5349fe203b622ac7d979008e8fc8e452ff3889fd9cb37b4e", "md5": "065bb3b1341ec2ff0157155bd25f17fb" }, { "family_name": "ChewBacca", "sha1": "0f2f22b7efa5ec9ee2b9c4882f7a5f002219117e", "record_on": 1477012336, "first_seen_on": 1476301532, "last_seen_on": 1476907260, "priority": 5, "sample_available": true, "container_hash": "0f2f22b7efa5ec9ee2b9c4882f7a5f002219117e", "sha256": "48f636a51ad542d7c189855812943e4260d6f474382d947d9699c7e5c0e620a5", "md5": "78a66809f89f67c48161c0acb6874997" } ], "name": "Malware Detection Family Feed", "time_range": { "to": 1477012336, "from": 1477008000 } } } } ``` To get the next page of results, provide the `to` value from the previous request as the `timestamp` value of the next request. This will cause some result duplication (specifically, records whose **record_on** value matches the **to** timestamp will reappear on the second page), but it will also return any remaining records with the matching timestamp that didn't fit on the first page. Setting the `count` value too low may result in `from` and `to` timestamps being the same, which will cause a response loop. #### Request ``` GET /api/feed/malware/detection/family/v2/query/retail/timestamp/1477012335?format=json&count=2 ``` **Second page response in JSON** ```json { "rl": { "feed": { "category": "RETAIL", "entries": [ { "family_name": "ChewBacca", "sha1": "0f2f22b7efa5ec9ee2b9c4882f7a5f002219117e", "record_on": 1477012336, "first_seen_on": 1476301532, "last_seen_on": 1476907260, "priority": 5, "sample_available": true, "container_hash": "0f2f22b7efa5ec9ee2b9c4882f7a5f002219117e", "sha256": "48f636a51ad542d7c189855812943e4260d6f474382d947d9699c7e5c0e620a5", "md5": "78a66809f89f67c48161c0acb6874997" }, { "family_name": "ChewBacca", "sha1": "8d5406d1af09d783f60585f57abd123b04c5bf47", "record_on": 1477014315, "first_seen_on": 1476302394, "last_seen_on": 1476908100, "priority": 5, "sample_available": true, "container_hash": "8d5406d1af09d783f60585f57abd123b04c5bf47", "sha256": "ed13c6f95925fb5cd37d6a954744d3250eb33c42367f31be92c32f41e20f24cc", "md5": "63670a3b40cea38138bb97e75441c611" } ], "name": "Malware Detection Family Feed", "time_range": { "to": 1477014315, "from": 1477012335 } } } } ``` ## Examples These examples request the first 100 detections starting from 2016-10-30 00:00:00 GMT for the Financial category. Responses are returned in XML as the default response format, since the optional `format` parameter is not specified in the request. The first example uses **timestamp** as the time format in the request, and the second uses **UTC**. ``` /api/feed/malware/detection/family/v2/query/financial/timestamp/1477785600 /api/feed/malware/detection/family/v2/query/**financial/utc**/2016-10-30T00:00:00 ``` --- ## Network Indicators Feed — Spectra Intelligence The Network Indicator feeds provide continuous streams of malicious URLs detected in the Spectra Intelligence system. ## Common Use Cases ### Get malicious URLs - **[Network IOCs feed (TCF-0301)](tcf-0301.md)** - Continuous list of malicious URLs with associated file hashes and threat names. ## All Network Indicator Feeds --- ## Network Indicators Feed (TCF-0301) — Spectra Intelligence # Network IOCs feed (TCF-0301) This service provides a continuous feed of malicious URLs identified by Spectra Intelligence. When a URL is observed delivering malicious files, the feed also includes relevant metadata for the downloaded file, such as the SHA1 hash, SHA256, and the ReversingLabs threat name. The feed stores records for the last 365 days. The feed returns a maximum of 1000 records per request, and provides the latest queried timestamp up to which the records are included. In your next request, increment that timestamp by 1 to fetch the next batch of records. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ## Continuous Feed Query ### Request ``` GET /api/feed/malware_uri/v1/query/{time_format}/{time_value}[?format=xml|json|tsv] ``` - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** (number of seconds since 1970-01-01 00:00:00), **utc** (UTC date in the *YYYY-MM-DDThh:mm:ss* format). This will also determine which format will be used in the `last_timestamp` field of the response. - Required - ``time_value`` - Accepts values in the format set by `time_format` - Required - ``format`` - Specifies the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**, **tsv** (Tab Separated Values, delimiter character `\t 0x09`) - Optional To retrieve at most 1000 latest records, use the following query: ``` GET /api/feed/malware_uri/v1/query/latest[?format=xml|json|tsv] ``` ### Response Records returned from third party sources contain only the `uri`, `threat_level` and `uri_type` fields. ``` json { "rl": { "malware_uri_feed": { "entries": [ { "record_on": "string", "uri": "string", "samples": [ { "threat_name": "string", "sha1": "string", "sha256": "string" } ], "uri_type": "string" } ], "last_timestamp": "string", "time_range": { "to": "string", "from": "string" } } } } ``` ----------------------------------------------------------------------- `rl.malware_uri_feed.entries[]` - `record_on` - When the record was included in the feed. Format: utc (YYYY-MM-DDThh:mm:ss). - `samples` - List of samples with optional threat names. Contains the following: - `sha1`: SHA1 hash of the sample, for example 9300addf4d28d3c1419d0080fbb415bb50e8a19c - `sha256`: SHA256 hash of the sample, for example 9f0da89c727b6efb3d2a3f845254bf89c626980a70a5817918d9c43ae65858c0 - `threat_name`: optional threat name, for example Win32.Trojan.Dinwod - `uri` A URL that we downloaded a malicious file from, or a third party reputation provider found it malicious. - `threat_level` - Malware severity indicator expressed as an integer between 0 and 5. Values from `1` to `5` indicate threats from lowest to highest severity, `0` is reserved for known URIs. For unknown URIs, this value is omitted. - In real-world situations, threat level values are typically interpreted in the following way: - Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex) - Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations) - Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains). - `uri_type` - This field is included for the purpose of backward compatibility. Always equal to url. ### Examples **Fetching all new URIs with changes from 2023-01-01 00:00:00** ``` /api/feed/malware_uri/v1/query/utc/2023-01-01T00:00:00 ``` **Fetching all new URIs with changes from 2023-01-01 00:00:00 using the timestamp format; response in JSON, XML, and TSV format** ``` /api/feed/malware_uri/v1/query/timestamp/1672527600?format=json /api/feed/malware_uri/v1/query/timestamp/1672527600?format=xml /api/feed/malware_uri/v1/query/timestamp/1672527600?format=tsv ``` **Fetching the first available changes** ``` /api/feed/malware_uri/v1/query/timestamp/0 ``` **Fetching all latest changes in XML, JSON, and TSV format** ``` /api/feed/malware_uri/v1/query/latest?format=json /api/feed/malware_uri/v1/query/latest?format=xml /api/feed/malware_uri/v1/query/latest?format=tsv ``` ## PULL Query For a given point in time, this query returns a list of malicious URIs that have been detected in the Spectra Intelligence system. The starting point for this query is defined using the `start` query. If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. When using the pull query continuously, it is useful to implement a pause between API requests to allow more results to accumulate in the feed, increasing the number of results returned per API request and reducing the total number of API calls needed. However, when catching up from a distant past timestamp, minimizing the pause between requests will speed up the process. Once the timestamp from the latest API response matches the current time, both methods (with and without pause) yield a similar number of records per unit of time. If you want to keep fetching the latest available records as they appear in the feed, you can use a short pause (e.g., 1 second) between requests. And if you need to catch up on a large backlog of data from the past, it is better to make continuous API calls without pausing. Unless the **limit** parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 request is fulfilled. ### Request ``` GET /api/feed/cf/malware_uri/v1/query/pull[?format=xml|json][&limit=N] ``` - ``format`` - Parameter defining the format in which the resulting data will be returned. Supported values are: **xml** (default), **json**. - Optional - ``limit`` - The number of records to return in the response. The maximum and default value is 1000. Note that the response may include more records than requested to ensure that all records with the same timestamp are returned. - Optional ### Response The response format is the same as in the `feed-query`. ### Examples **Fetching all new URI changes since last pull in XML and JSON format** ``` /api/feed/cf/malware_uri/v1/query/pull?format=json /api/feed/cf/malware_uri/v1/query/pull?format=xml ``` **Fetching a smaller batch of results per request** ``` /api/feed/cf/malware_uri/v1/query/pull?limit=100 /api/feed/cf/malware_uri/v1/query/pull?format=json&limit=100 ``` ## START Query This query sets the starting timestamp for the previously described `pull-query`. It is used to reprocess an already pulled time span, obtain data from an older period that was not previously retrieved, or skip ahead to a more recent timestamp when older data is no longer relevant. Resetting the start time in these cases helps manage the data retrieval process effectively. The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/cf/malware_uri/v1/query/start/[time_format]/[time_value] ``` - ``time_format`` - Format in which the time value will be specified. Supported values are: **timestamp** - number of seconds since 1970-01-01 00:00:00; **utc** - UTC date in the *YYYY-MM-DDThh:mm:ss* format - Required - ``time_value`` - Accepts values in the format set by time_format - Required ### Examples **Set the start time using UTC format** ``` /api/feed/cf/malware_uri/v1/query/start/utc/2023-01-01T00:00:00 ``` **Set the start time using the timestamp format** ``` /api/feed/cf/malware_uri/v1/query/start/timestamp/1672527600 ``` ### Response A successful query returns an **HTTP 200 OK** message with an empty response body. --- ## Supply Chain Security Feed — Spectra Intelligence The Supply Chain Security feeds provide threat intelligence for malicious Open Source Software (OSS) packages and reclassifications. ## Common Use Cases ### Monitor malicious OSS packages - **[Supply Chain IoC (TCF-0701)](tcf-0701.md)** - Continuous feed of malicious OSS packages and false positive reclassifications, with historical data since 2011. ## All Supply Chain Security Feeds --- ## Supply Chain Security Feed (TCF-0701) — Spectra Intelligence ReversingLabs Supply Chain Indicators of Compromise (IoC) Feed service delivers access to large volumes of structured threat intelligence data for malicious Open Source Software (OSS) packages and subsequent reclassifications. It delivers all historical data and maintains a continuous stream. The service includes the following primary event types: - **New Malicious Samples** (`NEW_MALICIOUS`): represents confirmed malicious OSS packages or files. - **False Positives** (`FP`): marks previously flagged samples that have been reclassified as non-malicious. - **New Threats** (`NEW_THREAT_NAME`): represents malware packages reclassified with a new threat name after additional analysis. The service supports time-based querying (e.g., retrieving data after a specified timestamp) and maintains user-specific cursors for reliable incremental consumption. The feed stores events since 2011-03-29. ## General Info about Requests/Responses - Default response format is XML. Supported formats are JSON and XML. ## Supply Chain Indicators of Compromise Pull The Supply Chain Indicators of Compromise (IoC) service delivers access to large volumes of structured threat intelligence data for malicious Open Source Software (OSS) packages and subsequent reclassifications. ### Request ``` GET /api/feed/supply_chain/ioc/v1/query/pull ``` #### Query parameters - `format` - The format of the response. Supported values: `json`, `xml` (default). - Optional - `limit` - Number of records to return in the response. The maximum and default value is `1000`. 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. - Optional ### Response The response is a JSON object containing the query parameters and the entries that match the requested query. - `last_timestamp`: Timestamp of the last entry in the feed - Type: string - `time_range.to`: End time of the query range - Type: string - `time_range.from`: Start time of the query range - Type: string - `entries[]`: Array of supply chain IoC entries - Type: array - `event_type`: Type of event. Supported values: `NEW_MALICIOUS`, `FP`, `NEW_THREAT_NAME` - Type: string - `md5`: MD5 hash of the package - Type: string - `sha1`: SHA1 hash of the package - Type: string - `sha256`: SHA256 hash of the package - Type: string - `sha512`: SHA512 hash of the package - Type: string - `filename`: Name of the package file - Type: string - `sample_size`: Size of the package in bytes - Type: string - `source_url`: URL where the package was downloaded from - Type: string - `identity.purl`: Package URL identifier - Type: string - `identity.community`: Package community (e.g., npm, pypi) - Type: string - `identity.namespace`: Package namespace - Type: string - `identity.package`: Package name - Type: string - `identity.product`: Product name - Type: string - `identity.version`: Package version - Type: string - `identity.artifact`: Artifact identifier - Type: string - `identity.homepage`: Package homepage URL - Type: string - `identity.repository`: Package repository URL - Type: string - `identity.published`: Package publication timestamp - Type: string - `sample_list[]`: List of malicious samples found in the package - Type: array - `sample_list[].status`: Sample status. Supported values: `MALICIOUS`, `KNOWN`, `SUSPICIOUS`, `UNKNOWN` - Type: string - `sample_list[].threat_name`: Name of the detected threat - Type: string - `sample_list[].threat_level`: Threat level (1-5) - Type: string - `sample_list[].md5`: MD5 hash of the sample - Type: string - `sample_list[].sha1`: SHA1 hash of the sample - Type: string - `sample_list[].sha256`: SHA256 hash of the sample - Type: string
Response example ``` json { "rl": { "supply_chain_ioc_feed": { "last_timestamp": "string", "time_range": { "to": "string", "from": "string" }, "entries": [ { "event_type": "NEW_MALICIOUS", "md5": "99d1bdaaa2e4a198521bc12df599ead0", "sha1": "aad8d679f15a721ed79454d553e3473f9f0536f1", "sha256": "e37d30c42c9739dfe153a324885937cbb98ed31760d1ba34d5542b309b2a67b0", "sha512": "11d11650fdc393da32c9c4733016d51d85b718b6eae4a3d61cb2a95d23700f917abb4b35c75da698fe0a233a924b3a6782ff3ff291377f8f7fa86046f1582a0a", "filename": "ua-parser-js-0.7.29.tgz", "sample_size": "57690", "source_url": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.29.tgz", "identity": { "purl": "pkg:npm/ua-parser-js@0.7.29", "community": "npm", "package": "ua-parser-js", "version": "0.7.29", "homepage": "https://uaparser.dev", "repository": "https://github.com/faisalman/ua-parser-js", "published": "2025-10-10T03:51:52+0000" }, "sample_list": [ { "status": "MALICIOUS", "threat_name": "Archive-GZIP.Downloader.SupplyChain", "threat_level": "3", "md5": "99d1bdaaa2e4a198521bc12df599ead0", "sha1": "aad8d679f15a721ed79454d553e3473f9f0536f1", "sha256": "e37d30c42c9739dfe153a324885937cbb98ed31760d1ba34d5542b309b2a67b0" }, { "status": "MALICIOUS", "threat_name": "Script-BAT.Downloader.SupplyChain", "threat_level": "3", "md5": "d98a3013336b755b739d285a58528cbe", "sha1": "01a2c9815acd76dc827b0325b97b793af3632c18", "sha256": "f4c800066e56dd32d20299c451fe6a2b60a3563f7f1915f8ca8db9916d810b5c" }, { "status": "MALICIOUS", "threat_name": "Text.Downloader.SupplyChain", "threat_level": "3", "sha1": "8b242cf78d082e81b5432c19477ebb80e5cf291a", "sha256": "82bd9d21a895327a17a7fd55d8c1270402bd0e5cf0443936be90d3738ce24560" }, { "status": "MALICIOUS", "threat_name": "Script-Shell.Downloader.SupplyChain", "threat_level": "3", "md5": "13f840772c7c04c7d2f4c202ff957b0c", "sha1": "69834f154ea070abccb8b08a10fd2da0bcc83543", "sha256": "21e68b048024ba0cc5a2a94ecbc3a78c626ec7d5d705829a82ea4715131d0509" }, { "status": "MALICIOUS", "threat_name": "Archive-TAR.Downloader.SupplyChain", "threat_level": "3", "md5": "9f5e525644662588972117c108b7ac03", "sha1": "45888251d905bf928db70350717d9451daa60b8c", "sha256": "44b01b5c634f93f2433e1796e8804c6ae4da966999d7539d5b8d62fe8c33d414" }, { "status": "MALICIOUS", "threat_name": "Script-JS.Downloader.SupplyChain", "threat_level": "3", "md5": "a4668a1b3f23b79ef07d1afe0152999e", "sha1": "1b76d2622ee8729704c56f5f8942a75ab729047b", "sha256": "e6cba23d350cb1f049266ddf10f872216f193c5279017408b869539df2e73c83" } ] }, { "event_type": "FP", "md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "sha1": "1234567890abcdef1234567890abcdef12345678", "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "sha512": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "filename": "example-package-1.0.0.tgz", "sample_size": "12345", "source_url": "https://registry.npmjs.org/example-package/-/example-package-1.0.0.tgz", "identity": { "purl": "pkg:npm/example-package@1.0.0", "community": "npm", "package": "example-package", "version": "1.0.0", "homepage": "https://example.com", "repository": "https://github.com/example/example-package", "published": "2025-06-15T10:30:00+0000" }, "sample_list": [ { "status": "KNOWN", "threat_name": "", "threat_level": "0", "md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "sha1": "1234567890abcdef1234567890abcdef12345678", "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" } ] }, { "event_type": "NEW_THREAT_NAME", "md5": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", "sha1": "234567890abcdef1234567890abcdef123456789", "sha256": "bcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab", "sha512": "234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", "filename": "threat-package-2.0.0.tgz", "sample_size": "23456", "source_url": "https://registry.npmjs.org/threat-package/-/threat-package-2.0.0.tgz", "identity": { "purl": "pkg:npm/threat-package@2.0.0", "community": "npm", "package": "threat-package", "version": "2.0.0", "homepage": "https://threat-example.com", "repository": "https://github.com/example/threat-package", "published": "2025-07-20T14:45:00+0000" }, "sample_list": [ { "status": "MALICIOUS", "threat_name": "Script-JS.Trojan.SupplyChain", "threat_level": "4", "md5": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", "sha1": "234567890abcdef1234567890abcdef123456789", "sha256": "bcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab" } ] } ] } } } ```
## Supply Chain Indicators of Compromise Start Starts the Supply Chain Indicators of Compromise (IoC) feed session and initializes access to structured threat intelligence data for malicious Open Source Software (OSS) packages. ### Request ``` PUT /api/feed/supply_chain/ioc/v1/query/start ``` ### Response | Code | Message | |----------|----------------------| | `200` | Successfully started | ## Supply Chain Indicators of Compromise Time Range Retrieve feed data starting from a specific time. The Supply Chain Indicators of Compromise (IoC) service delivers access to large volumes of structured threat intelligence data for malicious Open Source Software (OSS) packages and subsequent reclassifications. ### Request ``` GET /api/feed/supply_chain/ioc/v1/query/{time_format}/{time} ``` #### Path parameters - `time_format` - The format of the time value. Supported values: `utc` or `timestamp`. - Required - `time` - The time value corresponding to the given format. - Required #### Query parameters - `format` - The format of the response. Supported values: `json`, `xml` (default). - Optional - `limit` - The maximum number of results to be retrieved. Supported values: 1 - 1000. Default is 1000. - Optional ### Response The response is a JSON object containing the query parameters and the entries that match the requested query. - `last_timestamp`: Timestamp of the last entry in the feed - Type: string - `time_range.to`: End time of the query range - Type: string - `time_range.from`: Start time of the query range - Type: string - `entries[]`: Array of supply chain IoC entries - Type: array - `event_type`: Type of event. Supported values: `NEW_MALICIOUS`, `FP`, `NEW_THREAT_NAME` - Type: string - `md5`: MD5 hash of the package - Type: string - `sha1`: SHA1 hash of the package - Type: string - `sha256`: SHA256 hash of the package - Type: string - `sha512`: SHA512 hash of the package - Type: string - `filename`: Name of the package file - Type: string - `sample_size`: Size of the package in bytes - Type: string - `source_url`: URL where the package was downloaded from - Type: string - `identity.purl`: Package URL identifier - Type: string - `identity.community`: Package community (e.g., npm, pypi) - Type: string - `identity.namespace`: Package namespace - Type: string - `identity.package`: Package name - Type: string - `identity.product`: Product name - Type: string - `identity.version`: Package version - Type: string - `identity.artifact`: Artifact identifier - Type: string - `identity.homepage`: Package homepage URL - Type: string - `identity.repository`: Package repository URL - Type: string - `identity.published`: Package publication timestamp - Type: string - `sample_list[]`: List of malicious samples found in the package - Type: array - `sample_list[].status`: Sample status. Supported values: `MALICIOUS`, `KNOWN`, `SUSPICIOUS`, `UNKNOWN` - Type: string - `sample_list[].threat_name`: Name of the detected threat - Type: string - `sample_list[].threat_level`: Threat level (1-5) - Type: string - `sample_list[].md5`: MD5 hash of the sample - Type: string - `sample_list[].sha1`: SHA1 hash of the sample - Type: string - `sample_list[].sha256`: SHA256 hash of the sample - Type: string
Response example ``` json { "rl": { "supply_chain_ioc_feed": { "last_timestamp": "string", "time_range": { "to": "string", "from": "string" }, "entries": [ { "event_type": "NEW_MALICIOUS", "md5": "99d1bdaaa2e4a198521bc12df599ead0", "sha1": "aad8d679f15a721ed79454d553e3473f9f0536f1", "sha256": "e37d30c42c9739dfe153a324885937cbb98ed31760d1ba34d5542b309b2a67b0", "sha512": "11d11650fdc393da32c9c4733016d51d85b718b6eae4a3d61cb2a95d23700f917abb4b35c75da698fe0a233a924b3a6782ff3ff291377f8f7fa86046f1582a0a", "filename": "ua-parser-js-0.7.29.tgz", "sample_size": "57690", "source_url": "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-0.7.29.tgz", "identity": { "purl": "pkg:npm/ua-parser-js@0.7.29", "community": "npm", "package": "ua-parser-js", "version": "0.7.29", "homepage": "https://uaparser.dev", "repository": "https://github.com/faisalman/ua-parser-js", "published": "2025-10-10T03:51:52+0000" }, "sample_list": [ { "status": "MALICIOUS", "threat_name": "Archive-GZIP.Downloader.SupplyChain", "threat_level": "3", "md5": "99d1bdaaa2e4a198521bc12df599ead0", "sha1": "aad8d679f15a721ed79454d553e3473f9f0536f1", "sha256": "e37d30c42c9739dfe153a324885937cbb98ed31760d1ba34d5542b309b2a67b0" }, { "status": "MALICIOUS", "threat_name": "Script-BAT.Downloader.SupplyChain", "threat_level": "3", "md5": "d98a3013336b755b739d285a58528cbe", "sha1": "01a2c9815acd76dc827b0325b97b793af3632c18", "sha256": "f4c800066e56dd32d20299c451fe6a2b60a3563f7f1915f8ca8db9916d810b5c" }, { "status": "MALICIOUS", "threat_name": "Text.Downloader.SupplyChain", "threat_level": "3", "sha1": "8b242cf78d082e81b5432c19477ebb80e5cf291a", "sha256": "82bd9d21a895327a17a7fd55d8c1270402bd0e5cf0443936be90d3738ce24560" }, { "status": "MALICIOUS", "threat_name": "Script-Shell.Downloader.SupplyChain", "threat_level": "3", "md5": "13f840772c7c04c7d2f4c202ff957b0c", "sha1": "69834f154ea070abccb8b08a10fd2da0bcc83543", "sha256": "21e68b048024ba0cc5a2a94ecbc3a78c626ec7d5d705829a82ea4715131d0509" }, { "status": "MALICIOUS", "threat_name": "Archive-TAR.Downloader.SupplyChain", "threat_level": "3", "md5": "9f5e525644662588972117c108b7ac03", "sha1": "45888251d905bf928db70350717d9451daa60b8c", "sha256": "44b01b5c634f93f2433e1796e8804c6ae4da966999d7539d5b8d62fe8c33d414" }, { "status": "MALICIOUS", "threat_name": "Script-JS.Downloader.SupplyChain", "threat_level": "3", "md5": "a4668a1b3f23b79ef07d1afe0152999e", "sha1": "1b76d2622ee8729704c56f5f8942a75ab729047b", "sha256": "e6cba23d350cb1f049266ddf10f872216f193c5279017408b869539df2e73c83" } ] }, { "event_type": "FP", "md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "sha1": "1234567890abcdef1234567890abcdef12345678", "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "sha512": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "filename": "example-package-1.0.0.tgz", "sample_size": "12345", "source_url": "https://registry.npmjs.org/example-package/-/example-package-1.0.0.tgz", "identity": { "purl": "pkg:npm/example-package@1.0.0", "community": "npm", "package": "example-package", "version": "1.0.0", "homepage": "https://example.com", "repository": "https://github.com/example/example-package", "published": "2025-06-15T10:30:00+0000" }, "sample_list": [ { "status": "KNOWN", "threat_name": "", "threat_level": "0", "md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "sha1": "1234567890abcdef1234567890abcdef12345678", "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" } ] }, { "event_type": "NEW_THREAT_NAME", "md5": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", "sha1": "234567890abcdef1234567890abcdef123456789", "sha256": "bcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab", "sha512": "234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12", "filename": "threat-package-2.0.0.tgz", "sample_size": "23456", "source_url": "https://registry.npmjs.org/threat-package/-/threat-package-2.0.0.tgz", "identity": { "purl": "pkg:npm/threat-package@2.0.0", "community": "npm", "package": "threat-package", "version": "2.0.0", "homepage": "https://threat-example.com", "repository": "https://github.com/example/threat-package", "published": "2025-07-20T14:45:00+0000" }, "sample_list": [ { "status": "MALICIOUS", "threat_name": "Script-JS.Trojan.SupplyChain", "threat_level": "4", "md5": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", "sha1": "234567890abcdef1234567890abcdef123456789", "sha256": "bcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab" } ] } ] } } } ```
--- ## TAXII Feeds — Spectra Intelligence The TAXII feeds deliver threat intelligence in STIX format via the TAXII 2.1 protocol, enabling integration with third-party platforms like OpenCTI. ## Common Use Cases ### Get ransomware indicators - **[Ransomware Indicators TAXII Feeds (TCTF-0001)](tctf-0001.md)** - Curated ransomware IOCs including files, C2 infrastructure, and payload delivery URLs. ### Get organization-specific indicators - **[Networking Indicators TAXII Feeds - Flexible Intel Feed API (TCTF-0003)](tctf-0003.md)** - Personalized IOC feed based on your organization's submissions to Spectra Intelligence, enriched with ReversingLabs context. ## All TAXII Feeds --- ## TAXII Feed Setup (TCTF-0001) — Spectra Intelligence # Ransomware Indicators TAXII Feed (TCTF-0001) This page provides an overview of the ReversingLabs Ransomware Indicators Feed (TCTF-0001). The Ransomware Indicators Feed is purpose-built to focus exclusively on ransomware-related malware and its associated network activity. Backed by one of the largest malware processing pipelines in the industry handling approximately 20 million samples per day, we identify and extract high-confidence IOCs specifically tied to ransomware campaigns. Each day, relevant ransomware samples are filtered from the broader malware pool. File and network metadata is enriched through both static and dynamic analysis, resulting in a curated feed that includes: - Ransomware-associated files - Command-and-control (C2) infrastructure (extracted from malware configurations) - Payload delivery URLs Only indicators verified as malicious with high confidence are included, significantly reducing false positives compared to broader feeds. To provide meaningful context, each IOC is linked to threat names, malware families, attack stages, MITRE ATT&CK techniques, and threat actor associations. This enrichment helps analysts understand why an IOC matters. Given the rapid deployment of ransomware by human operators, often within hours of initial access, timeliness is critical. Over 50% of our IOCs are published within an hour of first observation, ensuring relevance for proactive defense and detection, not just post-incident response. ## Integrations The ReversingLabs Ransomware Indicators TAXII Feed has been tested to work with many of the most popular SIEM, SOAR, and TIP platforms that support ingestion of STIX/TAXII 2.1 objects. Check out our [integrations documentation](/Integrations/) for additional examples. ## RL-Specific Properties **Name** Currently, each indicator is given a name that matches the entity type prefixed with “Malware”, e.g. “Malware IP”, “Malware Domain”. **Warning: NOTE** Due to feedback from customers, we are actively working on replacing the existing name value with the actual indicator value. **External References** All MITRE ATT&CK techniques associated with the indicator are linked in the external references object. **Labels** Labels to help describe the indicator such as threat names, malware families, attack stages, MITRE ATT&CK techniques, and threat actor associations. **Kill Chain** ReversingLabs describes three stages of a ransomware attack. These are represented in the kill chain property, as well as the labels: - **Early Stage:** Indicators for ports, payload links, and other early-stage IoCs. - **Middle Stage:** Lateral progression within the organization. - **Late Stage:** Expansion, entrenchment, extortion, encryption, and exfiltration happen in late-stage ransomware attacks. ## Ransomware Indicators Feed Query ### API Root Discovery Query #### Request ``` GET api/taxii/ransomware-api-root/ ``` Path parameters: - `ransomware-api-root` - The endpoint to retrieve the API root for the Ransomware Indicators Feed. #### Response ```json { "description": "ReversingLabs ransomware data.", "title": "ReversingLabs ransomware STIX 2.1 Collections", "max_content_length": 999765625, "versions": [ "application/taxii+json;version=2.1" ] } ``` ### List Available Collections Query #### Request ``` GET api/taxii/ransomware-api-root/collections/ ``` Path parameters: - `collections` - The endpoint to retrieve the list of collections available in the feed. #### Response ```json { "collections": [ { "id": "f0997a32-b823-562d-9856-c754ac5e1159", "title": "ReversingLabs Ransomware Collection", "can_write": false, "can_read": true, "media_types": [ "application/stix+json;version=2.1" ] } ] } ``` ### Poll for Objects Query #### Request ``` GET api/taxii/ransomware-api-root/collections/{collection_id}/objects ``` Path parameters: - `collections` - The endpoint to retrieve the list of collections available in the feed. - `collection_id` - The endpoint to retrieve the objects in the specified collection. - `objects` - The endpoint to retrieve the objects in the specified collection. Query parameters: - `added_after` - A timestamp in RFC 3339 format to retrieve all objects after the specified timestamp. - `limit` - Limit the number of objects returned in the response. Range: `1 - 500` - `match[type]` - A comma-separated list of object types to filter by, such as `indicator`, `malware`, `threat-actor`. - [View the full list of supported fields](https://docs.oasis-open.org/cti/taxii/v2.1/os/taxii-v2.1-os.html#_Toc31107518). - `next` - A string value indicating the next record or set of records in the dataset. #### Response ```json { "more": true, "next": "17562276", "objects": [ { "type": "indicator", "spec_version": "2.1", "id": "indicator--dd2207cb-7e85-54a5-99ef-0b952b340435", "created": "2025-05-12T00:12:50Z", "modified": "2025-05-12T00:12:50Z", "valid_from": "2025-05-12T00:12:50Z", "valid_until": "2025-06-11T00:12:50Z", "created_by_ref": "identity--ef2a68d1-a8d2-5cb4-973d-1b9e0858c41e", "name": "30b1966606279762fc1703e68d3f4313a94252cb", "description": "Malware file activity was observed", "confidence": 100, "indicator_types": [ "malicious-activity" ], "pattern_type": "stix", "pattern": "[file:hashes.'SHA-1' = '30b1966606279762fc1703e68d3f4313a94252cb' OR file:hashes.'MD5' = '01d2a7062d6330c7fc4c3d071a75374d' OR file:hashes.'SHA-256' = 'f98f5d21a7643cbd273a69823873a3e8332fe3ad6da68bcd4ff8ad55b356ddbd']", "labels": [ "ReversingLabs", "34634", "PE/Exe/cpTinyGiant", "Zbot", "Trojan", "Early" ], "external_references": [ { "source_name": "mitre", "external_id": "T1018", "description": "Remote System Discovery", "url": "https://attack.mitre.org/techniques/T1018/" }, { "source_name": "mitre", "external_id": "T1027", "description": "Obfuscated Files or Information", "url": "https://attack.mitre.org/techniques/T1027/" } ], "kill_chain_phases": [ { "kill_chain_name": "rl-ransomware-kill-chain", "phase_name": "early" } ], "revoked": false } ] }``` ## Examples ### API Root Discovery **Request** ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/ -H "accept: application/taxii+json;version=2.1" ``` **Response** ```json { "description": "ReversingLabs ransomware data.", "title": "ReversingLabs ransomware STIX 2.1 Collections", "max_content_length": 999765625, "versions": [ "application/taxii+json;version=2.1" ] } ``` ### List Available Collections **Request** ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/ -H "accept: application/taxii+json;version=2.1" ``` **Response** ```json { "collections": [ { "id": "f0997a32-b823-562d-9856-c754ac5e1159", "title": "Reversinglabs Ransomware Collection", "can_write": false, "can_read": true, "media_types": [ "application/stix+json;version=2.1" ] } ] } ``` ### Poll for Objects **Request** ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/ -H "accept: application/taxii+json;version=2.1" ```
**Response** ```json { "more": true, "next": "17562276", "objects": [ { "type": "indicator", "spec_version": "2.1", "id": "indicator--dd2207cb-7e85-54a5-99ef-0b952b340435", "created": "2025-05-12T00:12:50Z", "modified": "2025-05-12T00:12:50Z", "valid_from": "2025-05-12T00:12:50Z", "valid_until": "2025-06-11T00:12:50Z", "created_by_ref": "identity--ef2a68d1-a8d2-5cb4-973d-1b9e0858c41e", "name": "30b1966606279762fc1703e68d3f4313a94252cb", "description": "Malware file activity was observed", "confidence": 100, "indicator_types": [ "malicious-activity" ], "pattern_type": "stix", "pattern": "[file:hashes.'SHA-1' = '30b1966606279762fc1703e68d3f4313a94252cb' OR file:hashes.'MD5' = '01d2a7062d6330c7fc4c3d071a75374d' OR file:hashes.'SHA-256' = 'f98f5d21a7643cbd273a69823873a3e8332fe3ad6da68bcd4ff8ad55b356ddbd']", "labels": [ "ReversingLabs", "34634", "PE/Exe/cpTinyGiant", "Zbot", "Trojan", "Early" ], "external_references": [ { "source_name": "mitre", "external_id": "T1018", "description": "Remote System Discovery", "url": "https://attack.mitre.org/techniques/T1018/" }, { "source_name": "mitre", "external_id": "T1027", "description": "Obfuscated Files or Information", "url": "https://attack.mitre.org/techniques/T1027/" } ], "kill_chain_phases": [ { "kill_chain_name": "rl-ransomware-kill-chain", "phase_name": "early" } ], "revoked": false } ] } ```
#### Filter by timestamp **Request** Use the `added_after` parameter to retrieve all objects after the specified timestamp. The timestamp must be a RFC 3339-formatted timestamp using the format: `YYYY-MM-DDTHH:MM:SS.ssssssZ`. ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/?added_after=2025-05-12T00:00:00.000000Z -H "accept: application/taxii+json;version=2.1" ``` #### Limit Returned Objects **Request** Use the `limit` query parameter to retrieve a specified number of objects. ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/?limit=5 -H "accept: application/taxii+json;version=2.1" ``` #### Matching Use the `match[type]` query parameter to filter objects by type. **Request** ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/?match[type]=indicator,malware,threat-actor -H "accept: application/taxii+json;version=2.1" ``` #### Paging **Request 1** Make the first request using the `limit` query filter. ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/?limit=5 -H "accept: application/taxii+json;version=2.1" ``` **Response** The response should return a `more` property with a boolean value, where `true` indicates more objects available. The value ofthe `next` property is used for the subsequent request. ```json { "more": true, "next": "17562276", "objects": [] } ``` **Request 2** Make the second request using the `next` query filter with the value returned in the previous response. ```shell curl -u "username:password" https://data.reversinglabs.com/api/taxii/ransomware-api-root/collections/f0997a32-b823-562d-9856-c754ac5e1159/objects/?next=17562276 -H "accept: application/taxii+json;version=2.1" ``` ### Error Handling All errors are returned in the TAXII 2.1 standard format. For more details, view the official [TAXII error handling](https://docs.oasis-open.org/cti/taxii/v2.1/os/taxii-v2.1-os.html#_Toc31107520) page. **Example Response** ```json { "description": "Unknown filter count encountered", "http_status": "400", "title": "ProcessingError" } ``` ## Appendix A: Expected STIX Fields | Field | Description | Example Value | |-----------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | Specifies the type of the STIX Object. For Indicators, this MUST be ‘indicator’. | `indicator` | | `spec_version` | The STIX specification version used to represent this object. | `2.1` | | `id` | A unique identifier for this object, following the format indicator--UUID. | `indicator--dd2207cb-7e85-54a5-99ef-0b952b340435` | | `created` | The time at which this object was originally created. | `2025-05-12T00:12:50Z` | | `modified` | The time that this particular version of the object was last modified. | `2025-05-12T00:12:50Z` | | `valid_from` | The time from which this Indicator is considered valid. | `2025-05-12T00:12:50Z` | | `valid_until` | The time at which this Indicator should no longer be considered valid. | `2025-06-11T00:12:50Z` | | `created_by_ref` | Specifies the ID of the Identity object that describes the entity that created this object. | `identity--ef2a68d1-a8d2-5cb4-973d-1b9e0858c41e` | | `name` | The SHA1 value of the Indicator being defined. | `48ee726d8dad030b4cfce7273d4a2bc7d405be4c` | | `description` | A description that provides more details and context about the Indicator. | `Malware file activity was observed` | | `confidence` | A value between 0 and 100 that describes the confidence in the correctness of the data contained within this object. | `100` | | `indicator_types` | Specifies the type of indicator. For example, malicious-activity, anomalous-activity, etc. | `malicious-activity` | | `pattern_type` | Specifies the type of pattern used. Common values include stix, snort, yara, etc. | `stix` | | `pattern` | The detection pattern for the Indicator, expressed in the language defined by pattern_type. | `[file:hashes.'SHA-1' = '30b1966606279762fc1703e68d3f4313a94252cb' OR file:hashes.'MD5' = '01d2a7062d6330c7fc4c3d071a75374d' OR file:hashes.'SHA-256' = 'f98f5d21a7643cbd273a69823873a3e8332fe3ad6da68bcd4ff8ad55b356ddbd']` | | `labels` | A set of labels applicable to this Indicator, providing additional context or metadata. | `ReversingLabs, 34634, PE/Exe/cpTinyGiant, Zbot, Trojan, Early` | | `external_references` | A list of external references that describe where this Indicator originated from or additional information. | `{"source_name": "mitre", "external_id": "T1018", "description": "Remote System Discovery", "url": "https://attack.mitre.org/techniques/T1018/"}` | | `kill_chain_phases` | Specifies the phase of the kill chain that this Indicator is associated with. | `rl-ransomware-kill-chain: early` | | `revoked` | Indicates whether this object has been revoked. | `false` | | `more` | Indicates if there are more objects available in the response. | `true` | | `next` | A token that can be used to retrieve the next set of objects in a paginated response. | `17562276` | --- ## TAXII Feed Subscription (TCTF-0003) — Spectra Intelligence The **Flexible Intel Feed** is a curated, private threat intelligence feed delivered via the [TAXII 2.1](https://docs.oasis-open.org/cti/taxii/v2.1/os/taxii-v2.1-os.html) protocol in [STIX 2.1](https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html) format. This feed provides structured Indicators of Compromise (IOCs) based on your organization's submissions to Spectra Intelligence. The data is enriched with context from across the ReversingLabs product portfolio and made available through a TAXII-compatible API. - The feed is **read-only**. - Data is scoped to your Spectra Intelligence account configured on the Spectra Analyze appliance. - Supports integration with third-party platforms like **OpenCTI**. - A typical usage pattern is to poll the objects endpoint regularly using the `added_after` filter. **Note: **Retention period**: The feed contains data submitted within the past **30 days**.** Feed access is authenticated and personalized per account. Each user is assigned a unique TAXII collection, available under a dedicated API root. ## Enable Feed (Authentication & Access) **Important: To enable the feed and obtain connection credentials, refer to the Spectra Analyze [Flexible Intel Feed](/SpectraAnalyze/Administration/integrations-connectors/flexible-intel-feed/) documentation.** Once the feed is enabled, Spectra Analyze displays a pop-up with the connection details: - **TAXII Discovery URL** The FIF feed supports the global TAXII discovery endpoint: `https://data.reversinglabs.com/api/taxii/taxii2/` - **API Root** The API root for FIF is: `https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/` - **Collection ID** A unique ID assigned to your Spectra Intelligence account. Used to query your private STIX feed. - **Username** Your Spectra Intelligence username with `/fif` appended Example: `u/company/user/a1000` → `u/company/user/a1000/fif` - **Password** Shown only once in the UI. Save it securely or regenerate it if lost. --- ### Authentication Access to the Flexible Intel Feed requires **Basic Authentication** using credentials provided when the feed was enabled. All requests must include: ```http Authorization: Basic Accept: application/taxii+json;version=2.1 User-Agent: ReversingLabs TAXII FIF Public Docs Example ``` --- ## Endpoints ### Discovery ``` GET https://data.reversinglabs.com/api/taxii/taxii2/ ``` Returns a list of available TAXII API roots. --- ### API Root ``` GET https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/ ``` Describes the Flexible Intel Feed root and its associated collections. --- ### Collections ``` GET https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/collections/ ``` Returns the list of collections available under this root. Each user receives a single private collection. ### STIX Objects Retrieves STIX 2.1 objects from your private feed collection. ``` GET https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/collections//objects/ ``` ### Supported Query Parameters | Parameter | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `added_after` | RFC 3339 / ISO 8601 timestamp. Returns only objects added after the given time. | | `limit` | Maximum number of objects per response. Supported range: **1–500**. | | `match[type]` | Comma-separated list of STIX object types to filter on (e.g. `indicator`, `malware`, `threat-actor`). | | `next` | Pagination token for retrieving the next batch of results. Returned in the response when more data is available. | Use these parameters when polling the objects endpoint. #### Example ``` curl --location 'https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/collections/49f2c125-4854-5a12-a0fd-62400f5a7af7/objects/?added_after=2025-06-09T11%3A00%3A00.000Z&limit=500' \ --header 'Accept: application/taxii+json;version=2.1' \ --header 'User-Agent: ReversingLabs TAXII FIF Public Docs Example' \ --header 'Authorization: Basic ' ``` ## Response Example ### Object Types The feed returns STIX 2.1 objects wrapped in a `{"objects": [...]}` structure. Typical object types include: - `url`, `domain-name`, `ipv4-addr`, `file`: Basic observable IOCs - `indicator`: Structured detection logic (e.g. "match if SHA256 is X") - `malware`: Classification and metadata about malware families - `relationship`: Links between objects (e.g., "this indicator indicates this malware") The object structure follows the [STIX 2.1 specification](https://docs.oasis-open.org/cti/stix/v2.1/os/stix-v2.1-os.html). ```json { "objects": [ { "id": "url--8e9478a4-ea09-5679-8b79-9661ee249f68", "type": "url", "value": "http://down.yueshou.net", "spec_version": "2.1" }, { "type": "relationship", "spec_version": "2.1", "id": "relationship--9e7e69a6-7782-5be1-91a9-faa524e4e4b2", "created": "2025-06-09T11:09:41Z", "modified": "2025-06-09T11:09:41Z", "created_by_ref": "identity--b0228148-e101-5bcb-ae0f-220c1a65f2f0", "relationship_type": "based-on", "source_ref": "indicator--af979875-b9b8-5dd4-9417-66e1560bcd23", "target_ref": "url--8e9478a4-ea09-5679-8b79-9661ee249f68" }, { "type": "indicator", "spec_version": "2.1", "id": "indicator--af979875-b9b8-5dd4-9417-66e1560bcd23", "created": "2025-06-09T11:09:41Z", "modified": "2025-06-09T11:09:41Z", "valid_from": "2025-06-09T11:09:41Z", "valid_until": "2025-07-09T11:09:41Z", "created_by_ref": "identity--b0228148-e101-5bcb-ae0f-220c1a65f2f0", "name": "http://down.yueshou.net", "description": "Malware file was observed to contact an URL", "confidence": 60, "indicator_types": ["malicious-activity"], "pattern_type": "stix", "pattern": "[url:value = 'http://down.yueshou.net']", "labels": ["ReversingLabs", "sample-source"] }, { "id": "domain-name--d4bb29e6-946c-5718-9179-5d49f9656337", "type": "domain-name", "value": "bzqcb.kxq79.com", "spec_version": "2.1" }, { "id": "file--d0ad5c70-a0b4-5585-beeb-1f8b6879c4c6", "type": "file", "hashes": { "SHA-1": "62defcf5a81f6def01e80822cec8f5cac8e5c807", "SHA-256": "ef087454771bc2a6bd9a00d110451baa2ba79ca58be7339b7e05abcc3eeb4a62", "MD5": "68ad68a69313bc151f2de06e3d68f4f0" }, "size": 2347784, "name": "62defcf5a81f6def01e80822cec8f5cac8e5c807.rl" } ] } ``` --- ## Example Use Cases Any file submitted to Spectra Intelligence becomes part of the Flexible Intel Feed, whether submitted manually, via API, through connectors, or from features like Bulk Search or YARA matching. Once analyzed, any verified malicious content is enriched with ReversingLabs metadata and exposed in STIX format via the TAXII API. You can use this mechanism to enrich IOCs from multiple workflows, such as: ### Bulk Search 1. Log into [Spectra Analyze](/SpectraAnalyze/). 2. Perform a [Bulk Search](/SpectraAnalyze/search-page/#bulk-search): Paste a list of unstructured IOCs (e.g., hashes or URLs) copied from another threat source 3. Review the Cloud matches, then select [Fetch and Analyze](/SpectraAnalyze/search-page/#spectra-intelligence-sample-actions). If automatic uploads to Spectra Intelligence are disabled on the appliance, you can: - Use **Fetch and Analyze (Advanced)** and check the Spectra Intelligence option - Download the samples, then submit them to Spectra Intelligence using the **Reanalyze** sample action 4. The appliance will analyze the retrieved files. Any verified malicious IOCs will be enriched with ReversingLabs metadata and included in your Flexible Intel Feed. This workflow converts external threat data into enriched, structured STIX IOCs accessible via TAXII — ready for integration into downstream tools like OpenCTI. ### YARA 1. Log into [Spectra Analyze](/SpectraAnalyze/). 2. [Deploy a YARA](/SpectraAnalyze/yara/#creating-new-yara-rulesets) rule to perform a live or retroactive hunt. 3. Review the Cloud matches, then select [Fetch and Analyze](/SpectraAnalyze/yara/#managing-yara-ruleset-matches). If automatic uploads to Spectra Intelligence are disabled on the appliance, you can: - Use **Fetch and Analyze (Advanced)** and check the Spectra Intelligence option - Download the samples, then submit them to Spectra Intelligence using the **Reanalyze** sample action 4. The appliance will analyze the retrieved files and populate the Flexible Intel Feed with any verified malicious IOCs. This enables you to extend **YARA-based detection** into a structured intelligence workflow, turning raw match results into curated, machine-readable STIX indicators. --- ## Trusted Certificates Feed — Whitelist File Indicators — Spectra Intelligence The Whitelist File Indicator feeds provide continuous streams of known-good (whitelisted) files and changes to whitelist status. ## Common Use Cases ### Get newly whitelisted files - **[Whitelisted files (new) (TCF-0501)](tcf-0501.md)** - Continuous list of files confirmed as known-good from trusted sources. ### Monitor whitelist changes - **[Whitelisted files (changes) (TCF-0502)](tcf-0502.md)** - Files whose whitelist status changed (KNOWN to MALICIOUS or SUSPICIOUS). ## All Whitelist File Indicator Feeds --- ## Whitelisted Files Feed (New) (TCF-0501) — Spectra Intelligence # Whitelisted files (new) (TCF-0501) This service provides a continuous list of whitelisted samples in the Spectra Intelligence system. The criteria for a file hash to be included in this feed: (1) file retrieved from trusted source, for example Microsoft; (2) file hash status has to be KNOWN (non-malicious or benign); and (3) at least 2 weeks have passed between the first scan and the latest scan. If a file has one scan or the first and last scanning timestamps aren't at least 2 weeks apart, it will be queued for scanning after two weeks before it's put on the feed. Every record in the feed includes hashes (MD5, SHA1, SHA256) and the `platform` field associated with the whitelisted sample. Users can extract samples related to a specific platform based on the value of the `platform` field. The feed stores records for the last 365 days. ## Continuous Whitelisted Feed Query This query returns a list of newly whitelisted samples since the requested time. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/whitelisted/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=false|true][&limit=N] ``` - `time_format` - Time format in which the date and time should be requested. It is possible to choose between `utc` and `timestamp` - Required - `time_value` - Accepts values in the format set by `time_format`. If the format is set to `utc`, the value should be expressed in the format `YYYY-MM-DDThh:mm:ss`. If the format is set to `timestamp`, the value should be expressed as the number of seconds since 1970-01-01 00:00:00 - Required - `format` - An optional parameter that allows choosing the response format. Supported values are `xml`, `json`, `tsv` (Tab Separated Values, delimiter character t 0x09). The default is `xml` - Optional - `sample_available` - Optional parameter. If this parameter is set to **true** in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to **false**, the query will return all samples, regardless of their download availability status. The default is **false**, meaning that if the parameter is not provided in the request, filtering is not applied. - Optional - `limit` - 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. - Optional ### Response For the requested timestamp, the response contains a list of records. Every record in the list includes hashes (MD5, SHA1, SHA256), the `record_on` field associated with the time when the record entered the feed, and the `platform` field associated with the whitelisted sample. For samples with an undetermined platform, the value of the `platform` field will be `Unknown`. The format of the `last_timestamp` value should match the requested time format. An empty response is returned if no records for the requested timestamp are available. ```json { "rl": { "whitelisted_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "platform" : "platform_value", "record_on" : "record_on_value" }, {...}, …], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## PULL Query This query returns a list of whitelisted samples since a particular point in time. The starting point for this query is defined using the [START query](#start-query). If the user has not previously requested this query, nor has the START query been called, it will return records starting with the current timestamp. Every subsequent call will continue from the timestamp where the previous call ended. In case that the timestamp of the previous call is older than 365 days, the subsequent call will autocorrect this timestamp to the oldest available (i.e. `current - 365 days`), and corresponding records will be returned. Unless the `limit` parameter is specified, the feed returns up to 1000 records and any surplus records sharing the same timestamp. That ensures 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 single thread (single instance). Any concurrent requests will be blocked until the previous one is fulfilled. ### Request ``` GET /api/feed/whitelisted/v1/query/pull[?format=xml|json|tsv][&limit=N][&sample_available=false|true] ``` - `format` - An optional parameter that allows choosing the response format. Supported values are `xml`, `json`, `tsv` (Tab Separated Values, delimiter character t 0x09). The default is `xml` - Optional - `sample_available` - Optional parameter. If this parameter is set to **true** in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to **false**, the query will return all samples, regardless of their download availability status. The default is **false**, meaning that if the parameter is not provided in the request, filtering is not applied - Optional - `limit` - 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. - Optional ### Response The response format is the same as in the [Continuous Whitelisted Feed Query](#continuous-whitelisted-feed-query). ## START Query This query sets the starting timestamp for the previously described [PULL query](#pull-query). The starting timestamp must be within the last 365 days, otherwise the service will respond with the status code **400 Bad Request**. ### Request ``` PUT /api/feed/whitelisted/v1/query/start/{time_format}/{time_value} ``` - `time_format` - Time format in which the date and time should be requested. It is possible to choose between `utc` and `timestamp` - Required - `time_value` - Accepts values in the format set by `time_format`. If the format is set to `utc`, the value should be expressed in the format **YYYY-MM-DDThh:mm:ss**. If the format is set to `timestamp`, the value should be expressed as the number of seconds since 1970-01-01 00:00:00 - Required ### Response A successful query returns an `HTTP 200 OK` message with an empty response body. ## Examples **Retrieving all new whitelisted samples from 2017-03-26 10:33:20** The examples return responses in XML as the default format, since the response format parameter is not specified. ``` /api/feed/whitelisted/v1/query/timestamp/1490517200 /api/feed/whitelisted/v1/query/utc/2017-03-26T10:33:20 ``` **Retrieving all new whitelisted samples from 2017-03-26 10:33:20 that are available in the storage** The examples use the timestamp format in the request. The first example returns the response in XML (as the default, not specified in the request), and the second example returns JSON (as requested). ``` /api/feed/whitelisted/v1/query/timestamp/1490517200?sample_available=true /api/feed/whitelisted/v1/query/timestamp/1490517200?sample_available=true&format=json ``` **Retrieving all new whitelisted samples from 2017-03-26 10:33:20 in JSON and XML format** ``` /api/feed/whitelisted/v1/query/timestamp/1490517200?format=json /api/feed/whitelisted/v1/query/timestamp/1490517200?format=xml ``` --- ## Whitelisted Files Feed (Changes) (TCF-0502) — Spectra Intelligence # Whitelisted files (changes) (TCF-0502) This service provides a continuous list of samples whose whitelisted status changed; i.e. samples that changed classification from KNOWN to MALICIOUS or SUSPICIOUS. Every record in the list includes hashes (MD5, SHA1, SHA256) and the `platform` field associated with the sample. Users can extract samples related to a specific platform based on the value of the `platform` field. The feed stores records for the last 365 days. ## Continuous Whitelisted Change Feed Query This query returns the samples which changed their whitelist status since the requested time. The feed returns up to 1000 records and any surplus records sharing the same timestamp. To fetch the next batch of records, use the timestamp from the response increased by 1. If the requested timestamp is not within the last 365 days, the service will respond with the status code **400 Bad Request**. ### Request ``` GET /api/feed/whitelisted_change/v1/query/{time_format}/{time_value}[?format=xml|json|tsv][&sample_available=true] ``` - `time_format` - Time format in which the date and time should be requested. It is possible to choose between `utc` and `timestamp` - Required - `time_value` - Accepts values in the format set by `time_format`. If the format is set to `utc`, the value should be expressed in the format **YYYY-MM-DDThh:mm:ss**. If the format is set to `timestamp`, the value should be expressed as the number of seconds since 1970-01-01 00:00:00 - Required - `format` - An optional parameter that allows choosing the response format. Supported values are `xml`, `json`, `tsv` (Tab Separated Values, delimiter character t 0x09). The default is `xml` - Optional - `sample_available` - Optional parameter. If this parameter is set to **true** in the request, filtering will be applied and the response will contain only samples that are present in the ReversingLabs storage and available for download. When set to **false**, the query will return all samples, regardless of their download availability status. The default is **false**, meaning that if the parameter is not provided in the request, filtering is not applied - Optional To retrieve at most 1000 latest records with changes in their whitelist status, use the following endpoint: ``` GET /api/feed/whitelisted_change/v1/query/latest[?format=xml|json|tsv] ``` ### Response For the requested timestamp, the response contains a list of records. Every record in the list includes hashes (MD5, SHA1, SHA256), the `record_on` field associated with the time when the record entered the feed, and the `platform` field associated with the sample. For samples with an undetermined platform, the value of the `platform` field will be `Unknown`. The format of the `last_timestamp` value should match the requested time format. ```json { "rl": { "whitelisted_change_feed": { "time_range": { "from": "YYYY-MM-DDTHH:MM:SS", "to": "YYYY-MM-DDTHH:MM:SS" }, "entries": [ { "sha1" : "sha1_value", "md5" : "md5_value", "sha256" : "sha256_value", "platform" : "platform_value", "record_on" : "record_on_value" }, {...}, ...], "last_timestamp": "YYYY-MM-DDTHH:MM:SS_or_timestamp", } } } ``` ## Examples **Retrieving all samples with whitelist changes from 2016-02-09 12:00:00** The examples return responses in XML as the default format, since the response format parameter is not specified. ``` /api/feed/whitelisted_change/v1/query/timestamp/1455019200 /api/feed/whitelisted_change/v1/query/utc/2016-02-09T12:00:00 ``` **Retrieving all samples with whitelist changes from 2016-02-09 12:00:00 that are available in the storage** The examples use the timestamp format in the request. The first example returns the response in XML (as the default, not specified in the request), and the second example returns JSON (as requested). ``` /api/feed/whitelisted_change/v1/query/timestamp/1455019200?sample_available=true /api/feed/whitelisted_change/v1/query/timestamp/1455019200?sample_available=true&format=json ``` **Retrieving all samples with whitelist changes from 2016-02-09 12:00:00 in JSON and XML format** ``` /api/feed/whitelisted_change/v1/query/timestamp/1430485200?format=json /api/feed/whitelisted_change/v1/query/timestamp/1406203200?format=xml ``` --- ## Spectra Intelligence Browser Extension for Chrome — ReversingLabs ## ReversingLabs Browser Extension The ReversingLabs browser extension provides access to Spectra Intelligence and Spectra Analyze. It enables users to query domains, URLs, IP addresses, and hashes from web pages and submit files for analysis. ## Installation The ReversingLabs browser extension is available on the [Chrome Web Store](https://chromewebstore.google.com/detail/reversinglabs-browser-ext/hdnaiimefhaiglkbjdcioegcoofbnomm). Install the extension and follow the configuration steps to connect it with your Spectra Intelligence or Spectra Analyze account. ## Usage ### Querying Threat Intelligence To query threat intelligence for a domain, URL, IP address, or hash, select the item and use the extension's available options. The extension will send the item for analysis and display the results. ### Submitting Files for Analysis To submit a file for analysis, open the extension’s side panel to upload the file. The extension will send the file to Spectra Analyze and display the analysis results. **Info: View the full [ReversingLabs Browser Extension documentation](/Integrations/Browser%20Extension/overview) for more details on installation, configuration, and usage.** --- ## MCP Server — Spectra Intelligence # Configuring MCP server with AI assistants ## Overview The **MCP** (Model Context Protocol) server enables AI assistants to connect to Spectra Intelligence APIs for malware reporting, IOC triage, and reputation lookups. The following steps describe how to configure the MCP server integration with Claude Code or other MCP-compatible AI assistants. **Info: Access** Official marketplace integrations for ChatGPT and Claude.ai are currently in the submission phase and will be available in the near future. For immediate access, refer to the [Manual configuration](#manual-configuration-and-other-mcp-clients) section below. ## Prerequisites - A Spectra Intelligence account with the TCA-0050 API permission. Contact [ReversingLabs support](https://support.reversinglabs.com) to request access. - An MCP client configured to connect to the Spectra Intelligence MCP server. ## ChatGPT app Spectra Intelligence MCP is released as an official ChatGPT app available in the [ChatGPT app store](https://chatgpt.com/apps?q=Spectra+Intelligence). **Note: If you are part of a team or organization on [openai.com](https://openai.com/), you may need to request access to the app from your administrator.** ## Claude.ai connector Spectra Intelligence MCP is listed in the Claude MCP server directory. Find it by searching for *Spectra Intelligence* in the [MCP server list](https://www.claudedirectory.org/mcp-servers). ### Example: Claude Code (CLI) While logged into your Anthropic account, prompt Claude to "List available MCP servers". That should show the Spectra Intelligence connector as one of the available options. ![List of available servers](images/claude-list-servers.png) Once you have confirmed that the server is available, you can use the `/mcp` command to select it in the list, which initializes the authorization flow. ## Manual configuration and other MCP clients If your MCP client does not have an official connector, you can configure the MCP server manually. ### Configuration parameters 1. **MCP server URL** (no trailing slash): `https://mcp.reversinglabs.com/mcp` 2. **OpenID client ID**: `ai-assistant` 3. **OpenID client secret**: not required, leave empty 4. **OAuth scope** (if explicitly requested): `mcp-server-access` ### Example: Windsurf configuration Windsurf uses a JSON file to configure MCP servers. To locate the configuration file, follow [the official Windsurf instructions](https://docs.windsurf.com/windsurf/cascade/mcp). Paste the following section into the configuration file: ```json { "mcpServers": { "spectra-intelligence": { "disabled": false, "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.reversinglabs.com/mcp", "--static-oauth-client-info", "{ \"client_id\": \"ai-assistant\" }" ] } } } ``` ### Example: MCP Inspector If you encounter any issues with the MCP server, use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to debug the connection. ```bash npx \ @modelcontextprotocol/inspector \ npx mcp-remote@latest \ https://mcp.reversinglabs.com/mcp \ --static-oauth-client-info \ '{\"client_id\":\"ai-assistant\"}' ``` ## Available tools Once connected, AI assistants can invoke the following tools to query Spectra Intelligence. Each entry lists the tool's parameters and an example request. ### get_file_reputation Return file reputation with full analysis and generated LLM prompt. **Parameters:** - `hash`: MD5, SHA1, or SHA256 hash of a sample. **Example:** ```json { "hash": "d41d8cd98f00b204e9800998ecf8427e" } ``` ### bulk_file_reputation Analyze multiple file hashes with batch processing. **Parameters:** - `hashes`: List of MD5, SHA1, or SHA256 sample hashes to analyze. - `batch_size`: Positive integer for hashes per API call (max 25). **Example:** ```json { "hashes": [ "d41d8cd98f00b204e9800998ecf8427e", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ], "batch_size": 25 } ``` ### get_network_reputation Evaluate a network indicator (domain, IP, or full URL) and return reputation results including GeoIP, business context, and an automated verdict with a risk score. **Parameters:** - `indicator`: IP address, domain, or URL to analyze. **Example:** ```json { "indicator": "example.com" } ``` ### advanced_search Search ReversingLabs malware intelligence (Threat Hunting Engine) using a query string. For more details, see [Advanced search (TCA-0320)](API/MalwareHunting/tca-0320.md). **Parameters:** - `query`: Search query string with `field:value` syntax. - `limit`: Maximum results per page (1-500, default: 100). - `page`: Page number for pagination (default: 1). - `time_range`: Limit search to specific time range, for example, *7days*, *6months*, *1year*, *2years*, *3years* (default: *7days*). - `sort_by`: Sort results by field, for example, *sha1*, *firstseen*, *threatname* (default: None). - `sort_order`: Sort order, for example, *asc* or *desc* (default: *desc*). **Example:** ```json { "query": "classification:malicious sampletype:PE", "limit": 100, "page": 1, "time_range": "7days", "sort_by": "firstseen", "sort_order": "desc" } ``` ### enhanced_threat_analysis Comprehensive threat intelligence with AI-powered insights, combining multiple analysis engines for comprehensive threat assessment. **Parameters:** - `hash`: File hash for analysis. - `context`: Optional context about the sample origin. - `skip_campaign_analysis`: Skip campaign attribution analysis (boolean). **Example:** ```json { "hash": "d41d8cd98f00b204e9800998ecf8427e", "context": "Suspicious email attachment", "skip_campaign_analysis": false } ``` --- ## Spectra Intelligence Troubleshooting — Fix 401, 429 & Feed Errors # Troubleshooting This guide covers common issues with [Spectra Intelligence](./index.md) APIs and feeds and the steps to resolve them. --- ## 401 Unauthorized response **Symptom** Every API request returns: ```http HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic realm="Spectra Intelligence" ``` **Cause** - The `Authorization` header is missing from the request. - The credentials in the `Authorization` header are incorrect. - The credential string is not correctly base64-encoded for HTTP Basic authentication. - The account has been suspended or deactivated. **Solution** 1. Confirm that every request includes the `Authorization` header using HTTP Basic authentication. All Spectra Intelligence APIs require this header, as described in [Sending requests](./index.md#sending-requests). ```bash curl -u ":" \ "https://data.reversinglabs.com/api/databrowser/malware_presence/query/sha1/?format=json" ``` 2. Verify your credentials by logging in to the ReversingLabs portal. If your password has changed recently, regenerate or update it in all scripts and integrations. 3. If using the [ReversingLabs Python SDK](https://pypi.org/project/reversinglabs-sdk-py3/), check that the `username` and `password` parameters passed to the client constructor are correct: ```python from ReversingLabs.SDK.ticloud import FileReputation client = FileReputation( host="https://data.reversinglabs.com", username="", password="" ) ``` 4. If credentials are correct but requests still return 401, contact [support@reversinglabs.com](mailto:support@reversinglabs.com) to verify that your account is active. --- ## 403 Forbidden response **Symptom** API requests return: ```http HTTP/1.1 403 Forbidden ``` The response body may not include a descriptive message. **Cause** - Your account does not have a subscription or entitlement for the specific API endpoint you are calling. - You are attempting to access a service that requires an upgrade to your current contract. **Solution** 1. Review the API reference page for the endpoint you are calling. Each service documents the required entitlement tier. 2. Check which APIs are included in your contract by contacting [support@reversinglabs.com](mailto:support@reversinglabs.com) or your ReversingLabs account manager. 3. If you believe your account should have access, confirm that you are using the correct username (including the company segment, for example `u/company/username`) — accessing APIs with an account from a different company segment may result in 403 responses. --- ## 404 Not Found — hash not in database **Symptom** A hash lookup returns: ```http HTTP/1.1 404 Not Found ``` **Cause** - The queried hash has not yet been seen by the ReversingLabs database. - The hash value is malformed or contains an encoding error. - You are querying a hash type (for example, MD5) for an endpoint that expects a different hash type (for example, SHA-1). **Solution** 1. A 404 response for a hash query is not an error — it means the file has not been seen by Spectra Intelligence. This is a normal response for previously unseen files. According to the [response status codes](./index.md#response-status-codes), 404 means no matching record was found. 2. Verify that the hash string is correctly formatted and uses the expected algorithm. For example, SHA-1 is 40 hex characters: ```bash # Compute SHA-1 of a local file to cross-check sha1sum /path/to/file ``` 3. If you are certain the file has been analyzed before, check whether you are querying the correct API endpoint. Some endpoints accept only specific hash types; see the relevant API reference (for example, [File Threat Intelligence](./API/FileThreatIntel/tca-0101.md)). --- ## 429 Too Many Requests — quota exceeded **Symptom** API requests return: ```http HTTP/1.1 429 Too Many Requests ``` You may also receive an automated alert email from ReversingLabs. **Cause** - Your account's daily or monthly quota has been exhausted. - Your request rate has exceeded the per-second rate limit for the API, which returns an additional `"Rate limit exceeded"` message. **Solution** 1. Check whether this is a quota exhaustion or a rate limit issue. A rate-limit response includes an additional message: ```json {"message": "Rate limit exceeded"} ``` Quota exhaustion responses typically do not include a body beyond the 429 status. 2. For **rate limiting**: implement exponential backoff and retry logic in your client. Spread bulk lookups across time rather than submitting all requests simultaneously. 3. For **quota exhaustion**: daily quotas reset at 00:00 UTC and monthly quotas reset on the first of the month at 00:00 UTC, as described in [Limits and quotas](./index.md#limits-and-quotas). 4. Monitor your quota consumption proactively using the [Customer Usage API](./API/CustomerUsage/tca-9999.md) before reaching the limit. 5. If your quota is regularly insufficient for your use case, contact your ReversingLabs account manager to discuss an upgrade. 6. For bulk operations, prefer the bulk query endpoints where available. Bulk queries count only successful items against your quota, as explained in [Limits and quotas](./index.md#limits-and-quotas). --- ## Request timeout on large queries **Symptom** Large bulk requests or queries with many items fail with a client-side timeout or return: ```http HTTP/1.1 503 Service Unavailable ``` after an extended wait. **Cause** - The client HTTP timeout is shorter than the time required to process a large bulk request. - A network intermediary (proxy, load balancer) is enforcing a shorter timeout than the API requires. - The request contains close to or more than the maximum allowed number of items (100 hashes per bulk request). **Solution** 1. Check the [response status codes](./index.md#response-status-codes) table. A 503 indicates a temporary overload on the server side; retry the request after a short delay. 2. Ensure your bulk requests do not exceed 100 items. Requests exceeding this limit return HTTP 413. Split large datasets into batches of 100 or fewer: ```python def batch(items, size=100): for i in range(0, len(items), size): yield items[i:i + size] for chunk in batch(all_hashes): response = client.get_bulk_results(chunk) ``` 3. Increase the HTTP client timeout in your code. For the Python SDK, pass a `timeout` parameter: ```python response = client.file_reputation(hash_input=sha1, timeout=60) ``` 4. If timeouts are caused by a proxy, configure the proxy to allow longer-lived connections to `data.reversinglabs.com`. --- ## SSL/TLS certificate error **Symptom** Requests to the Spectra Intelligence API fail with an error such as: ``` curl: (60) SSL certificate problem: unable to get local issuer certificate ``` or in Python: ``` ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed ``` **Cause** - The system's CA certificate bundle does not include the root CA that signed the ReversingLabs server certificate. - A network security appliance (TLS inspection proxy) is presenting its own certificate instead of the ReversingLabs certificate, and it is not trusted by the client. - The system clock is significantly wrong, causing certificate validity checks to fail. **Solution** 1. Verify the server certificate from the command line: ```bash curl -vI https://data.reversinglabs.com 2>&1 | grep -E "subject|issuer|expire" ``` 2. Update the CA certificate bundle on your system: ```bash # Debian/Ubuntu sudo apt-get update && sudo apt-get install --reinstall ca-certificates # RHEL/CentOS sudo yum reinstall ca-certificates ``` 3. If a TLS inspection proxy is in use, add the proxy's root CA certificate to your system trust store or pass it explicitly: ```bash curl --cacert /path/to/proxy-ca.pem \ -u ":" \ "https://data.reversinglabs.com/..." ``` 4. Verify that the system clock is accurate: ```bash date timedatectl status ``` Significant clock skew causes certificate validation to fail even with a valid certificate. 5. Do not use `--insecure` (`-k` in curl) or `verify=False` in Python in production environments, as this disables certificate validation entirely and exposes your traffic to interception. --- ## Python SDK connection error **Symptom** Using the [ReversingLabs Python SDK](https://pypi.org/project/reversinglabs-sdk-py3/), requests raise exceptions such as: ``` requests.exceptions.ConnectionError: HTTPSConnectionPool(host='data.reversinglabs.com', port=443): Max retries exceeded ``` or: ``` requests.exceptions.ConnectTimeout ``` **Cause** - The machine running the SDK cannot reach `data.reversinglabs.com` over HTTPS (port 443). - A proxy is required but not configured in the SDK or the environment. - DNS resolution for `data.reversinglabs.com` is failing. **Solution** 1. Test basic connectivity from the machine: ```bash curl -I https://data.reversinglabs.com ``` If this fails, the issue is network-level, not SDK-related. 2. Check DNS resolution: ```bash nslookup data.reversinglabs.com dig data.reversinglabs.com ``` 3. If a proxy is required, configure it via environment variables before running the SDK: ```bash export HTTPS_PROXY="http://proxy.company.internal:8080" ``` Or pass proxy settings directly to the SDK client using the underlying `requests.Session`: ```python from ReversingLabs.SDK.ticloud import FileReputation session = requests.Session() session.proxies = {"https": "http://proxy.company.internal:8080"} client = FileReputation( host="https://data.reversinglabs.com", username="", password="", proxies={"https": "http://proxy.company.internal:8080"} ) ``` 4. Verify that the SDK version is up to date: `pip install --upgrade reversinglabs-sdk-py3`. --- ## Batch request returns partial results **Symptom** A bulk API request containing multiple hashes returns fewer results than the number of items submitted. Some hashes are missing from the response. **Cause** - Hashes that are not found in the database (404) are omitted from bulk response bodies rather than returned as error entries — only valid, found results are included. - Some items in the request were invalid (malformed hashes) and were silently skipped. - The request contained more than 100 items, causing it to be rejected (HTTP 413) or truncated. **Solution** 1. Cross-reference the hashes in your request against the hashes in the response. Any hash absent from the response was either not found (not yet seen by Spectra Intelligence) or was invalid. 2. Validate hash formats before submission. SHA-1 hashes must be exactly 40 lowercase hex characters. Malformed entries are skipped and not counted against quota. 3. Note that the [quota deduction model](./index.md#limits-and-quotas) for bulk requests counts only valid returned results — invalid items are not charged. Confirming this behavior can help you detect malformed input. 4. Keep batch sizes at or below 100 items to avoid HTTP 413 responses. --- ## TAXII feed returns no data **Symptom** Polling the [TAXII feed](./Feed/TAXII/tctf-0001.md) returns an empty collection or no STIX objects, even though new threat intelligence is expected. **Cause** - The `added_after` timestamp used in the collection request is set to a future time, or is more recent than the latest available data. - The TAXII client is not sending the correct collection ID. - The account does not have entitlement for the TAXII feed. - The collection has not yet published new data within the polled time window. **Solution** 1. Check the `added_after` parameter in your TAXII request. Set it to a known past timestamp to verify that objects are returned: ```bash # Example: request objects from the past 24 hours added_after=$(date -u -d '24 hours ago' +"%Y-%m-%dT%H:%M:%SZ") ``` 2. Confirm you are using the correct TAXII collection ID. Refer to the [TAXII feed documentation](./Feed/TAXII/tctf-0001.md) for available collection IDs and their content. 3. Verify your TAXII client is authenticating correctly with Basic auth credentials. 4. Test the feed endpoint directly with `curl` to isolate whether the issue is with the client or the server: ```bash curl -u ":" \ "https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/collections//objects/?added_after=2024-01-01T00:00:00Z" ``` 5. If you receive a 403 response, confirm with your account manager that the TAXII feed is included in your contract. --- ## Upload API timeouts and retries **Symptom** When uploading files using the [File Upload API](./API/Automation/tca-0202-0203.md), you encounter intermittent errors: - **HTTP 408 Request Timeout**: The client or server timed out waiting for the upload to complete. - **HTTP 503 Service Unavailable**: A transient infrastructure error between the CDN and origin backend. Despite these errors, affected samples are often processed successfully when the request is retried. **Cause** - **408 errors**: The HTTP client timeout is shorter than the time required to upload and process the file. The server-side NGINX proxy allows up to 300 seconds for uploads, but many HTTP clients default to 60 seconds or less. - **503 errors**: Transient failures in the infrastructure layer (for example, between the Varnish cache and origin backend). These are low-frequency, temporary errors that resolve on retry. **Solution** For reliable high-volume uploads in production environments: 1. **Set HTTP timeouts to 300 seconds**: Configure both connect and read timeouts to match the server-side configuration. 2. **Implement retry logic for non-2xx responses**: Retry failed requests, particularly for: - HTTP 408 (Request Timeout) - HTTP 429 (Too Many Requests) - HTTP 5xx errors (500, 502, 503, 504) - Connection or read timeouts 3. **Respect HTTP 429 rate limiting**: When you receive a 429 response, check for the `Retry-After` header and wait the specified duration before retrying. 4. **Use exponential backoff**: If you encounter rate limiting or repeated failures, implement exponential backoff to avoid overwhelming the service. 5. **Apply to both endpoints**: Use the same timeout and retry configuration for both: - `POST /api/spex/upload/{sha1}` - File content upload - `POST /api/spex/upload/{sha1}/meta` - Metadata upload --- ## Unexpected UNKNOWN classification **Symptom** A hash lookup or file analysis returns a classification of `UNKNOWN` rather than `malicious`, `suspicious`, or `goodware`. **Cause** - The file has not been seen by the ReversingLabs network before, so no classification exists yet. - The file is a novel or rare variant that has not been analyzed by enough sources to produce a confident verdict. - The hash is for a container file whose classification depends on extracted children, and those children have not been analyzed. **Solution** 1. An `UNKNOWN` result is not an error — it means the file has no established reputation in the Spectra Intelligence database. This is expected for newly discovered or very rare files. 2. To obtain a classification for an unknown file, submit it for analysis on a [Spectra Analyze](/SpectraAnalyze/) appliance. Spectra Analyze uses [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) to perform deep static analysis and can produce a local classification. 3. Review the [classification methodology](/General/AnalysisAndClassification/Classification) to understand how classifications are assigned and what factors contribute to a confident verdict. 4. If you are seeing a high volume of `UNKNOWN` results for files that you believe are malicious, they may be custom or targeted malware. Submit samples through your ReversingLabs support channel for analyst review. --- ## Analysis Timeout Issues File analysis timeouts can occur when processing complex or large files that require extensive analysis time. Understanding the causes and solutions helps ensure successful file processing. ## Common Causes Analysis timeouts typically happen due to: - **Large file sizes** - Files approaching or exceeding the size limits for your appliance tier - **Deep nesting** - Archives containing multiple layers of compressed files - **Extensive unpacking** - Files that trigger recursive decompression operations - **Complex file structures** - Files with intricate internal structures requiring detailed parsing - **Resource constraints** - Insufficient RAM or CPU allocation for the analysis workload ## Configuration Options ### Spectra Analyze The analysis timeout can be adjusted in the appliance configuration: 1. Navigate to **Administration > Configuration** 2. Locate the analysis timeout setting 3. Increase the timeout value based on your file processing requirements 4. Save the configuration changes ### File Inspection Engine Use the `--analysis-timeout` flag to control the per-file time limit: ```bash rl-scan --analysis-timeout 300 /path/to/file ``` The timeout value is specified in seconds. ## Troubleshooting Steps If analysis timeouts persist: 1. **Increase allocated resources** - Ensure the appliance or container has sufficient RAM (32 GB+ recommended) and CPU cores 2. **Check decompression ratio limits** - Verify that recursive unpacking isn't exceeding configured limits 3. **Review file characteristics** - Examine the file structure to identify potential issues 4. **Monitor system resources** - Check if the appliance is under heavy load from concurrent analyses 5. **Adjust timeout values** - Increase timeout settings for complex file processing workflows ## Related Topics - [Platform Requirements](/General/DeploymentAndIntegration/PlatformRequirements) - Hardware specifications for different appliance tiers - [How Spectra Core analysis works](/General/AnalysisAndClassification/SpectraCoreAnalysis) - Understanding the analysis process --- ## Antivirus Result Availability When a sample is uploaded or rescanned in Spectra Intelligence, it will usually get new antivirus results **within 30 minutes**. When a sample has new antivirus results, these will available in relevant APIs, for example [TCA-0104 File analysis](/SpectraIntelligence/API/FileThreatIntel/tca-0104/). --- ## Certificate Revocation ReversingLabs maintains a certificate revocation database that is updated with each [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) release. Because the database is offline, some recently revoked certificates may not appear as revoked until the next update. Certificate Authority (CA) revocation alone is not sufficient to classify a sample as malicious. Most CAs backdate revocations to the certificate's issuance date, regardless of when or whether the certificate was abused. When additional context is available, ReversingLabs adjusts the revocation date to reflect the most appropriate point in time. If a certificate is whitelisted, this correction is not applied. ## Searching for Revoked Certificates You can find samples signed with revoked certificates using **Advanced Search** with the `tag:cert-revoked` keyword. Advanced Search is available both through the [Spectra Analyze user interface](/SpectraAnalyze/search-page/) and as the [TCA-0320 Advanced Search](/SpectraIntelligence/API/MalwareHunting/tca-0320/) API. --- ## File Classification and Risk Scoring — ReversingLabs # Classification File classification assigns a risk score (0-10) and threat verdict (malicious, suspicious, goodware, or unknown) to every analyzed file using ReversingLabs Spectra Core. The classification algorithm combines YARA rules, machine learning, heuristics, certificate validation, and file similarity matching to determine security status. YARA rules take precedence as the most authoritative signal, followed by other detection methods that contribute to the final verdict. The classification of a sample is based on a comprehensive assessment of its assigned risk factor, threat level, and trust factor; however, it can be manually or automatically overridden when necessary. Based on this evaluation, files are placed into one of the following buckets: - No threats found (unclassified) - Goodware/known - Suspicious - Malicious The classification process weighs signals from all available sources to arrive at the most accurate verdict. Some signals are considered more authoritative than others and take priority. For example, [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) YARA rules always take precedence because they are written and curated by ReversingLabs analysts. These rules provide the highest degree of accuracy, as they target specific, named threats. This does not mean that other classification methods are less important. Similarity matching, heuristics, and machine learning still contribute valuable signals and may produce additional matches. In cases where multiple detections apply, YARA rules simply serve as the deciding factor for the final classification. ## Risk score A risk score is a value representing the trustworthiness or malicious severity of a sample. Risk score is expressed as a number from 0 to 10, with 0 indicating whitelisted samples from a reputable origin, and 10 indicating the most dangerous threats. At a glance: Files with no threats found don't get assigned a risk score and are therefore **unclassified**. Values from 0 to 5 are reserved for samples classified as **goodware/known**, and take into account the source and structural metadata of the file, among other things. Since goodware samples do not have threat names associated with them, they receive a description based on their risk score. Risk scores from 6 to 10 are reserved for **suspicious** and **malicious** samples, and express their severity. They are calculated by a ReversingLabs proprietary algorithm, and based on many factors such as file origin, threat type, how frequently it occurs in the wild, YARA rules, and more. Lesser threats like adware get a risk score of 6, while ransomware and trojans always get a risk score of 10. ### Malware type and risk score In cases where multiple threats are detected and there are no other factors (such as user overrides) involved, the final classification is always the one that presents the biggest threat. If they belong to the same risk score group, malware types are prioritized in this order: | Risk score | Malware types | |------------|---------------------------------------------------------------------------------------------------------------------| | 10 | EXPLOIT > BACKDOOR > RANSOMWARE > INFOSTEALER > KEYLOGGER > WORM > VIRUS > CERTIFICATE > PHISHING > FORMAT > TROJAN | | 9 | ROOTKIT > COINMINER > ROGUE > BROWSER | | 8 | DOWNLOADER > DROPPER > DIALER > NETWORK | | 7 | SPYWARE > HYPERLINK > SPAM > MALWARE | | 6 | ADWARE > HACKTOOL > PUA > PACKED | ## Threat level and trust factor The [risk score table](#risk-score) describes the relationship between the risk score, and the threat level and trust factor used by the [File Reputation API](/SpectraIntelligence/API/FileThreatIntel/tca-0101). The main difference is that the risk score maps all classifications onto one numerical scale (0-10), while the File Reputation API uses two different scales for different classifications. ### Nomenclature The following classifications are equivalent: | File Reputation API | Spectra Analyze | Spectra Detect Worker | | ------------------- | --------------- | ------------------------ | | known | goodware | 1 (in the Worker report) | In the Worker report, the [risk score](#risk-score) is called `rca_factor`. ## Deciding sample priority The [risk score table](#risk-score) highlights that the a sample's risk score and its classification don't have a perfect correlation. This means that a sample's risk score cannot be interpreted on its own, and that the primary criterion in deciding a sample's priority is its classification. Samples classified as suspicious can be a result of heuristics, or a possible early detection. A suspicious file may be declared malicious or known at a later time if new information is received that changes its threat profile, or if the user manually modifies its status. The system always considers a malicious sample with a risk score of 6 as a higher threat than a suspicious sample with a risk score of 10, meaning that samples classified as malicious always supersede suspicious samples, regardless of the calculated risk score. The reason for this is certainty - a malicious sample is decidedly malicious, while suspicious samples need more data to confirm the detected threat. It is a constant effort by ReversingLabs to reduce the number of suspicious samples. While a suspicious sample with a risk score of 10 does deserve user attention and shouldn't be ignored, a malicious sample with a risk score of 10 should be triaged as soon as possible. ## Acting on classification and risk tolerance When appliances or integrations surface data from ReversingLabs Threat Intelligence lookups, the **classification** and **rca_factor** fields are the primary signal to act upon. - Always evaluate the `classification` field first: it determines whether a sample is known goodware, suspicious, or malicious and therefore dictates priority. - Use `rca_factor` to adjust the risk aversion profile and suppress alerts for low-level threats when appropriate. Lower factors correspond to less severe detections. Additional fields worth reviewing: - `propagated`: `true` means one of the extracted child files caused the verdict, so you may need to investigate nested artifacts. - `scan_results`: contains all malicious detections found in the file; the worst detection is propagated as the final file verdict. - `result`: verbal verdict name. - `factor`: can usually be ignored because it is actionable only in conjunction with clean samples. - `propagated_source`: contains the extracted file hash that was found to be malicious and triggered propagation. ### Risk tolerance profiles 1. **Low risk tolerance**: the user wants to be alerted about any possible threat. In this profile, act on both **Suspicious** and **Malicious** verdicts, which generates the maximum number of matches. 2. **High risk tolerance**: the user only wants to be notified about highly impactful threats. In this profile, filter for `classification:Malicious` and `rca_factor >= 7` so only the most severe detections surface. For deployments using Spectra Analyze, the [Risk Tolerance Levels](/SpectraAnalyze/Administration/users-personalization/risk-tolerance-levels) guide explains how appliance sensitivity settings choose which analysis sources count toward classification. For more context on interpreting the classification structure and `rca_factor`, refer to the [Spectra Detect Analysis](/SpectraDetect/Usage/Analysis) documentation, which outlines the fields returned in Worker reports. ## Malware naming standard --- ## Handling False Positives # Handling False Positives A false positive occurs when a legitimate file is incorrectly classified as malicious. While ReversingLabs strives for high accuracy, false positives can occasionally happen due to the complexity of malware detection across hundreds of file formats and millions of samples. ## What You Can Do If you encounter a false positive, you have several options: ### 1. Local Classification Override On Spectra Analyze, you can immediately override the classification using the classification override feature: - Navigate to the file's Sample Details page - Use the classification override option to manually set the file as goodware - The override takes effect immediately on your appliance - All users on the same appliance will see the updated classification ### 2. Spectra Intelligence Reclassification Request Submit a reclassification request through Spectra Intelligence: - The override propagates across all appliances connected to the same Spectra Intelligence account - Other appliances in your organization will automatically receive the updated classification - This is the recommended approach for organization-wide corrections ### 3. Goodware Overrides Use Goodware Overrides to propagate trusted parent classifications to extracted child files: - If a trusted parent file (e.g., from Microsoft or another reputable vendor) contains files that trigger false positives - The parent's goodware classification can automatically override the child files - This is particularly useful for legitimate installers that may contain components flagged by heuristics ## How ReversingLabs Handles False Positive Reports If a customer reports a false positive (through Zendesk, or by contacting the Support team at support@reversinglabs.com), the first thing we do is re-scan the sample to make sure that the results are up-to-date. If the results are still malicious, our Threat Analysis team will: 1. Conduct our own research of the software and the vendor 2. Contact the AV scanners and notify them of the issue 3. Change the classification in our system (we do not wait for AVs to correct the issue) --- If the file is confirmed to be a false positive, we begin by analyzing why the incorrect classification occurred. Then we try to correct the result by making adjustments related to file relationships, certificates, AV product detection velocity (e.g. are detections being added or removed), we will re-scan and reanalyze samples, adjust/add sources and, if necessary, manually investigate the file. If these efforts do not yield a correct result, we have the ability to **manually override the classification** — but we only do so after thorough analysis confirms the file is benign. --- ## ReversingLabs malware naming standard The ReversingLabs detection string consists of three main parts separated by dots. All parts of the string will always appear (all three parts are mandatory). ``` platform-subplatform.type.familyname ``` 1. The first part of the string indicates the **platform** targeted by the malware. This string is always one of the strings listed in the [Platform string](#platform-string) table. If the platform is Archive, Audio, ByteCode, Document, Image or Script, then it has a subplatform string. Platform and subplatform strings are divided by a hyphen (`-`). The lists of available strings for Archive, Audio, ByteCode, Document, Image and Script subplatforms can be found in their respective tables. 2. The second part of the detection string describes the **malware type**. Strings that appear as malware type descriptions are listed in the [Type string](#type-string) table. 3. The third and last part of the detection string represents the malware family name, i.e. the name given to a particular malware strain. Names "Agent", "Gen", "Heur", and other similar short generic names are not allowed. Names can't be shorter than three characters, and can't contain only numbers. Special characters (apart from `-`) must be avoided as well. The `-` character is only allowed in exploit (CVE/CAN) names (for example CVE-2012-0158). #### Examples If a trojan is designed for the Windows 32-bit platform and has the family name "Adams", its detection string will look like this: ``` Win32.Trojan.Adams ``` If some backdoor malware is a PHP script with the family name "Jones", the detection string will look like this: ``` Script-PHP.Backdoor.Jones ``` Some potentially unwanted application designed for Android that has the family name "Smith" will have the following detection string: ``` Android.PUA.Smith ``` Some examples of detections with invalid family names are: ``` Win32.Dropper.Agent ByteCode-MSIL.Keylogger.Heur Script-JS.Hacktool.Gen Android.Backdoor.12345 Document-PDF.Exploit.KO Android.Spyware.1a Android.Spyware.Not-a-CVE Win32.Trojan.Blue_Banana Win32.Ransomware.Hydra:Crypt Win32.Ransomware.HDD#Cryptor ``` #### Platform string The platform string indicates the operating system that the malware is designed for. The following table contains the available strings and the operating systems for which they are used. | String | Short description | | ----------- | ------------------------------------------------------------------------------------------ | | ABAP | SAP / R3 Advanced Business Application Programming environment | | Android | Applications for Android OS | | AOL | America Online environment | | Archive | Archives. See [Archive subplatforms](#archive-subplatforms) for more information. | | Audio | Audio. See [Audio subplatforms](#audio-subplatforms) for more information. | | BeOS | Executable content for Be Inc. operating system | | Boot | Boot, MBR | | Binary | Binary native type | | ByteCode | ByteCode, platform-independent. See [ByteCode subplatforms](#bytecode-subplatforms) for more information. | | Blackberry | Applications for Blackberry OS | | Console | Executables or applications for old consoles (e.g. Nintendo, Amiga, ...) | | Document | Documents. See [Document subplatforms](#document-subplatforms) for more information. | | DOS | DOS, Windows 16 bit based OS | | EPOC | Applications for EPOC mobile OS | | Email | Emails. See [Email subplatforms](#email-subplatforms) for more information. | | Firmware | BIOS, Embedded devices (mp3 players, ...) | | FreeBSD | Executable content for 32-bit and 64-bit FreeBSD platforms | | Image | Images. See [Image subplatforms](#image-subplatforms) for more information. | | iOS | Applications for Apple iOS (iPod, iPhone, iPad…) | | Linux | Executable content for 32 and 64-bit Linux operating systems | | MacOS | Executable content for Apple Mac OS, OS X | | Menuet | Executable content for Menuet OS | | Novell | Executable content for Novell OS | | OS2 | Executable content for IBM OS/2 | | Package | Software packages. See [Package subplatforms](#package-subplatforms) for more information. | | Palm | Applications for Palm mobile OS | | Script | Scripts. See [Script subplatforms](#script-subplatforms) for more information. | | Shortcut | Shortcuts | | Solaris | Executable content for Solaris OS | | SunOS | Executable content for SunOS platform | | Symbian | Applications for Symbian OS | | Text | Text native type | | Unix | Executable content for the UNIX platform | | Video | Videos | | WebAssembly | Binary format for executable code in Web pages | | Win32 | Executable content for 32-bit Windows OS's | | Win64 | Executable content for 64-bit Windows OS's | | WinCE | Executable content for Windows Embedded Compact OS | | WinPhone | Applications for Windows Phone | ##### Archive subplatforms | String | Short description | | ---------------------------------- | ------------------------------------------------------------ | | ACE | WinAce archives | | AR | AR archives | | ARJ | ARJ (Archived by Robert Jung) archives | | BZIP2 | Bzip2 archives | | CAB | Microsoft Cabinet archives | | GZIP | GNU Zip archives | | ISO | ISO image files | | JAR | JAR (Java ARchive) archives | | LZH | LZH archives | | RAR | RAR (Roshal Archive) archives | | 7ZIP | 7-Zip archives | | SZDD | Microsoft SZDD archives | | TAR | Tar (tarball) archives | | XAR | XAR (eXtensible ARchive) archives | | ZIP | ZIP archives | | ZOO | ZOO archives | | *Other Archive identification* | All other valid [Spectra Core](/General/AnalysisAndClassification/SpectraCoreAnalysis) identifications of Archive type | ##### Audio subplatforms | String | Short description | | -------------------------------- | ---------------------------------------------------------- | | WAV | Wave Audio File Format | | *Other Audio identification* | All other valid Spectra Core identifications of Audio type | ##### ByteCode subplatforms | String | Short description | | ------ | ----------------- | | JAVA | Java bytecode | | MSIL | MSIL bytecode | | SWF | Adobe Flash | ##### Document subplatforms | String | Short description | | ----------------------------------- | ------------------------------------------------------------ | | Access | Microsoft Office Access | | CHM | Compiled HTML | | Cookie | Cookie files | | Excel | Microsoft Office Excel | | HTML | HTML documents | | Multimedia | Multimedia containers that aren't covered by other platforms (e.g. ASF) | | Office | File that affects multiple Office components | | OLE | Microsoft Object Linking and Embedding | | PDF | PDF documents | | PowerPoint | Microsoft Office PowerPoint | | Project | Microsoft Office Project | | Publisher | Microsoft Office Publisher | | RTF | RTF documents | | Visio | Microsoft Office Visio | | XML | XML and XML metafiles (ASX) | | Word | Microsoft Office Word | | *Other Document identification* | All other valid Spectra Core identifications of Document type | ##### Email subplatforms | String | Short description | | ------ | ------------------------------------- | | MIME | Multipurpose Internet Mail Extensions | | MSG | Outlook MSG file format | ##### Image subplatforms | String | Short description | | -------------------------------- | ------------------------------------------------------------ | | ANI | File format used for animated mouse cursors on Microsoft Windows | | BMP | Bitmap images | | EMF | Enhanced Metafile images | | EPS | Adobe Encapsulated PostScript images | | GIF | Graphics Interchange Format | | JPEG | JPEG images | | OTF | OpenType Font | | PNG | Portable Network Graphics | | TIFF | Tagged Image File Format | | TTF | Apple TrueType Font | | WMF | Windows Metafile images | | *Other Image identification* | All other valid Spectra Core identifications of Image type | ##### Package subplatforms | String | Short description | | ---------------------------------- | ------------------------------------------------------------ | | NuGet | NuGet packages | | DEB | Debian Linux DEB packages | | RPM | Linux RPM packages | | WindowStorePackage | Packages for distributing and installing Windows apps | | *Other Package identification* | All other valid Spectra Core identifications of Package type | ##### Script subplatforms | String | Short description | | --------------------------------- | ------------------------------------------------------------ | | ActiveX | ActiveX scripts | | AppleScript | AppleScript scripts | | ASP | ASP scripts | | AutoIt | AutoIt scripts (Windows) | | AutoLISP | AutoCAD LISP scripts | | BAT | Batch scripts | | CGI | CGI scripts | | CorelDraw | CorelDraw scripts | | Ferite | Ferite scripts | | INF | INF Script, Windows installer scripts | | INI | INI configuration file | | IRC | IRC, mIRC, pIRC/Pirch Script | | JS | Javascript, JScript | | KiXtart | KiXtart scripts | | Logo | Logo scripts | | Lua | Lua scripts | | Macro | Macro (e.g. VBA, AmiPro macros, Lotus123 macros) | | Makefile | Makefile configuration | | Matlab | Matlab scripts | | Perl | Perl scripts | | PHP | PHP scripts | | PowerShell | PowerShell scripts, Monad (MSH) | | Python | Python scripts | | Registry | Windows Registry scripts | | Ruby | Ruby scripts | | Shell | Shell scripts | | Shockwave | Shockwave scripts | | SQL | SQL scripts | | SubtitleWorkshop | SubtitleWorkshop scripts | | WinHelp | WinHelp Script | | WScript | Windows Scripting Host related scripts (can be VBScript, JScript, …) | | *Other Script identification* | All other valid Spectra Core identifications of Script type | #### Type string This string is used to describe the general type of malware. The following table contains the available strings and describes what each malware type is capable of. For a catalog of common software weaknesses that enable malware, see [CWE](https://cwe.mitre.org/) maintained by MITRE. CISA maintains advisories on actively exploited vulnerabilities at [cisa.gov/known-exploited-vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities). | String | Description | | ----------- | ------------------------------------------------------------ | | Adware | Presents unwanted advertisements | | Backdoor | Bypasses device security and allows remote access | | Browser | Browser helper objects, toolbars, and malicious extensions | | Certificate | Classification derived from certificate data | | Coinminer | Uses system resources for cryptocurrency mining without the user's permission | | Dialer | Applications used for war-dialing and calling premium numbers | | Downloader | Downloads other malware or components | | Dropper | Drops malicious artifacts including other malware | | Exploit | Exploits for various vulnerabilities, CVE/CAN entries | | Format | Malformations of the file format. Classification derived from graylisting, validators on unpackers | | Hacktool | Software used in hacking attacks, that might also have a legitimate use | | Hyperlink | Classifications derived from extracted URLs | | Infostealer | Steals personal info, passwords, etc. | | Keylogger | Records keystrokes | | Malware | New and recently discovered malware not yet named by the research community | | Network | Networking utilities, such as tools for DoS, DDoS, etc. | | Packed | Packed applications (UPX, PECompact…) | | Phishing | Email messages (or documents) created with the aim of misleading the victim by disguising itself as a trustworthy entity into opening malicious links, disclosing personal information or opening malicious files. | | PUA | Potentially unwanted applications (hoax, joke, misleading...) | | Ransomware | Malware which encrypts files and demands money for decryption | | Rogue | Fraudulent AV installs and scareware | | Rootkit | Provides undetectable administrator access to a computer or a mobile device | | Spam | Other junk mail that does not unambiguously fall into the Phishing category, but contains unwanted or illegal content. | | Spyware | Collects personal information and spies on users | | Trojan | Allows remote access, hides in legit applications | | Virus | Self-replicating file/disk/USB infectors | | Worm | Self-propagating malware with exploit payloads | --- ## Risk score reference table --- ## How Spectra Core analysis works # How Spectra Core Analysis Works All ReversingLabs products are powered by [Spectra Core](https://www.reversinglabs.com/products/spectra-core) - the engine that analyzes every file and sample. The process of analyzing software involves several steps, and the final output are the analysis reports. To better understand the source and significance of the information contained in those reports, it's helpful to learn what Spectra Core does in the background of ReversingLabs products. This page provides an overview of the Spectra Core analysis process and explains what happens with files in each of the analysis steps. The following main steps have dedicated sections where they are described in detail: 1. [Identification](#1-identification) 2. [Unpacking](#2-unpacking) 3. [Validation](#3-validation) 4. [Metadata processing](#4-metadata-processing) 5. [Classification](#5-classification) ## Automated static analysis When you scan a file with Spectra Core, the engine automatically performs static analysis on the file and all files extracted from it. Automated static analysis is also referred to as **complex binary analysis**. This unique approach to software analysis decomposes files, collects their metadata, and classifies them in terms of the security risk they pose to end-users. Files are analyzed recursively, which means that every file extracted from the software package goes through the same analysis process like its container software package. As implemented in Spectra Core, automated static analysis does not require access to the source code (like SAST tools typically do). It can directly examine compiled software binaries to determine their structure, dependencies and behaviors. In addition to analyzing software binaries (which is the primary use-case), Spectra Core can analyze library code and source code for specific scripting languages. Another benefit of automated static analysis is that **files are not executed during the analysis process**. All available data is extracted even if the files are compressed, executable, or damaged - regardless of their target OS or platform. Because the analysis process does not execute any files, it can be completed in milliseconds and performed on very large files without significant performance penalties. All these features of automated static analysis give Spectra Core a unique advantage - it can analyze post-build artifacts and detect more novel, sophisticated software supply chain attacks than SCA tools are able to. SCA tools typically analyze package managers, manifest files, or source code repositories to find vulnerabilities. They are limited by the need for known signatures of open source dependencies that have to be cross-referenced against a vulnerability database. Being used in pre-build environments, SCA tools lack visibility into deep file structures and build process tampering evidence - insights that Spectra Core readily provides. ## The Spectra Core analysis process The process starts with the input file. The analysis engine performs several distinct steps on every object it extracts from the input file. The following diagram illustrates the flow that every object goes through. You can interact with the diagram to learn more about the process: - Select steps in the diagram to access their dedicated sections on this page ### 1. Identification Format identification is the initial step of the Spectra Core analysis process. To successfully perform the subsequent analysis steps, we first need to know the file format of every object we are analyzing. Specifically, this step analyzes the object structure to determine whether it's **binary** or **text**, and assigns the analyzed object a unique file format description. This description - file format identification - instructs the analysis engine on which rules and modules to use for further file processing. Two main approaches are used for format identification: - **Signatures** - created by ReversingLabs researchers to identify **binary** file formats based on their unique features. For example, Windows .exe files start with bytes "MZ", while PNG files will usually start with "‰PNG". Signatures describe expectations of what a file format should contain. Using heuristics, the analysis process checks whether those expectations align with the actual file structure. In addition to signatures, the analysis process also evaluates any relevant YARA rules (built into the engine as well as user-provided). If there are multiple matches, those from signatures take priority over YARA rule matches. - **Machine learning models** - created and trained by ReversingLabs researchers to identify **textual** file formats based on statistical text identification. The models are able to recognize basic text objects as scripting languages and distinguish software source code from other types of textual content. **Note: ✅ Completing the identification step** The results of the format identification step are: - File hashes - calculated by the analysis engine - File format descriptions - represented as File type.File subtype.Identification (for example, `Binary/Archive/ZIP`). If there are multiple versions of a file format, they can be identified through the additional `version` field. After the format has been identified, the file is either directed to the proper unpacking module according to its signature, or to the validation step. ### 2. Unpacking Unpacking, also referred to as **file decomposition**, is a step in the Spectra Core analysis process where the analyzed file is taken apart to extract all available components and metadata. During the unpacking process, the analysis engine eliminates obfuscation, encryption, compression, and any other protections that may have been applied to the file and its contents. The engine has built-in mechanisms to prevent infinite recursion, and supports configuring the decompression ratio and unpacking depth (how many layers of a file to extract). Different file formats require different unpacking approaches because of their structure and complexity. Because static analysis does not execute a file, it requires **unpackers** - specialized tools for parsing and unpacking individual file formats. ReversingLabs develops in-house static unpackers tailored to specific file formats, and Spectra Core relies on those unpackers during analysis. Generally speaking, goodware file formats are easier to unpack because their structure is known and well-defined, and file behavior can be observed from the format definition. File formats commonly used for malware are good at hiding code, which makes their unpacking more challenging. To create an unpacker for malware file formats, researchers have to identify each format and document its structure. The unpacker must be able to simulate file execution so that its code can be reconstructed and its behavior observed. Any obfuscation and protection artifacts must also be removed to allow extracting further objects. Information about the file behavior allows the unpacker - and consequently, the analysis process - to reveal the original software intent and to let users understand the true meaning of the code that was packed in that particular file format. The ability to unpack a file format makes it possible for the Spectra Core analysis engine to extract a wealth of metadata and critical information often not available from other tools. The collected metadata includes but is not limited to: format header details, strings (including secrets and URIs), function names, library dependencies, and file segments. Unpacking greatly increases the surface that can be analyzed and helps file classification by providing more metadata to look at. This makes it easier to confirm classification verdicts and increases the chance to catch every threat. **Note: ✅ COMPLETING THE UNPACKING STEP** After the file has been successfully unpacked, all collected metadata and the unpacked file content are passed to the validator assigned to the file format. The validator then performs integrity checks on the available data. ### 3. Validation Validation is a step in the Spectra Core analysis process where the **structure** and the **digital signatures** of the analyzed file are verified according to specific criteria for each file format. In the validation step, the previously identified file format is checked against its specification (the formal definition of the file format by its designer). In other words, the validation process looks for differences between the file format specification and its implementation. By doing this, we can gather additional information about the file format and detect anomalies in it. Any malformations that violate the file format specification are further examined to determine if they are capable of triggering potentially malicious behavior. Such malformations may be reported as known vulnerabilities. ReversingLabs uses these malformation patterns to create heuristics for potential future exploits and predictive vulnerability detection. Multiple validators may be used to verify a file format. They are called successively, first to last, or until one of them acknowledges that it recognizes and can handle the specific file format. If validation fails for one of them, the entire file is marked as invalid. Detected issues are reported as validation warnings or errors, depending on their severity. In addition to performing integrity checks of the file format structure, the validation step also verifies any digital certificates that have been used for code signing. Depending on its status, a certificate may influence the classification of files signed with it. The validation step assigns one of the following statuses to every detected certificate: - Valid certificate - Invalid certificate - Bad checksum - Bad signature - Malformed certificate - Self-signed certificate - Impersonation attempt - Expired certificate - Untrusted certificate - Revoked certificate **Note: ✅ COMPLETING THE VALIDATION STEP** After the file has been validated, all collected metadata is processed, evaluated, and transformed into actionable information that can be used to deliver the final file classification. ### 4. Metadata processing Metadata processing is a step in the Spectra Core analysis process where all previously collected metadata is translated into **human-readable**, **explainable information**. That information is used to produce or support the final file classification. Most of it is surfaced in Spectra Core analysis reports. In this step, metadata is converted into **capabilities** and **indicators**. They build up on the file format properties and platform-specific features of the analyzed file to describe software behavior and intent in more detail. The goal is to make it clearer what the analyzed code means and what each object is trying to do. #### Indicators Indicators can be described as behavior markers that are triggered when a specific pattern is found in the collected metadata or in the file content. An indicator may be triggered for multiple reasons. While some indicators can only be found in specific file formats, most are universal and therefore generally applicable. Indicators contribute to the final file classification, but not in an equal measure. Those deemed highly relevant are better at describing the detected malware type, while those with less relevant contributions help in solidifying the machine learning detection. #### Capabilities Based on the indicators triggered on a file, the analysis engine infers that the file exhibits a specific behavior, or that it is capable of performing specific actions. Similar software behaviors are grouped into broader categories - capabilities - according to the features they have in common. For example, a file can have the filesystem capability, which is a broad description that says the file can access the filesystem or perform filesystem operations, but doesn't describe which operation will actually take place. More fine-grained software behavior descriptions are derived from the indicators (e.g. "Accesses the httpd.conf file"). #### Tags The metadata processing step also assigns tags to files based on their properties such as certificate information, software behaviors, file contents, and many more. Some tags can only be applied to specific file types (for example, web browsers or mobile applications). Tags are visible in [Spectra Analyze](/SpectraAnalyze/system-and-user-tags) and can be queried through the [Spectra Intelligence Advanced Search (TCA-0320)](/SpectraIntelligence/API/MalwareHunting/tca-0320) API. In SAFE reports generated by Spectra Assure, tags appear for all unpacked files and for URIs in the Networking section, where they can be used for filtering. **Note: ✅ COMPLETING THE METADATA PROCESSING STEP** After the metadata has been fully processed, the file receives its classification status in the next step of the analysis. ### 5. Classification Classification is a step in the Spectra Core analysis process where the analysis engine produces a **verdict** on whether the analyzed file contains threats harmful to the end-user. Multiple technologies are used for file classification: - format identification - signatures (byte pattern matches) - file structure validation - extracted file hierarchy - file similarity (RHA1) - certificates - machine learning - heuristics (for scripts and fileless malware) - YARA rules included in the analysis engine They are shipped with the analysis engine and can be used offline, without connecting to any external sources. Their coverage varies based on threat and file format type. In other words, not all technologies can detect all threat types, and not all of them work on all file formats. Those default classification abilities of the Spectra Core platform can be extended with **threat intelligence from the ReversingLabs Cloud** to retrieve file reputation information, and with **custom YARA rules for user-assisted classification**. Some classification approaches are more specific than others, with signatures being the most specific. The final classification result relies on the information from all analysis steps, and it is a combination of all technologies applicable to the file format. It will always match one of the technologies even though they may have differing results between them. Because of differences in how malicious files and malware families behave, some files might end up classified as malicious by one technology, and still be considered goodware by others. This doesn’t negate or diminish the final classification. #### Explainable Machine Learning Spectra Core is the first and only solution on the market that relies on [Explainable Machine Learning (xAI)](https://www.reversinglabs.com/blog/machine-learning-for-humans) for threat detection. Explainable Machine Learning was launched by ReversingLabs in 2020 as a predictive threat detection method that can detect novel malware. It focuses on providing threat analysts with human-readable insights into machine learning-driven classifications. The goal of ReversingLabs Explainable Machine Learning is to go beyond the basic verdict of "goodware vs malware", and to help analysts understand **what type of threat was found**, **why it was detected**, and **what to do with it next**. To achieve that, the classification system combines: - **explainability** (by surfacing software behaviors in the form of indicators), - **relevance** (by ranking behaviors based on their contribution to the final verdict), - and **transparency** (by displaying why each software behavior was triggered). Using natural language to provide clear explanations for classification decisions helps security analysts understand how analyzed software behaves and what malware is capable of doing to the system. This transparency fosters trust, facilitates informed decision-making, and makes the logic behind machine learning classification verdicts easier to follow. Over the years, ReversingLabs threat analysts and researchers have carefully transformed raw code and metadata produced by static analysis into indicators - descriptions of software intent. Those indicators are used in training machine learning (ML) models to recognize if a file is malicious based on the described software functionality and behavior. Many of the threats in the training datasets are hand-picked by ReversingLabs experts and fully, correctly labeled so that ML models can learn what constitutes a specific threat type, and distinguish it from other threat types as well as from clean software. This allows ML models to proactively detect and describe threats - even brand new malware - without the need for additional training. When Spectra Core scans a file and extracts some indicators from it, ML models can match them against the indicators they have learned to recognize as typical for malware or a specific threat type. Some indicators are more meaningful in the context of a malware or threat type, so they contribute more to the classification. When the model decides that something is malicious, the decision can be verified through indicators and reasons why they were triggered. This makes the decision more transparent, relevant, and explainable in terms that are familiar to human analysts. ReversingLabs ML models are tailored to threat types to increase accuracy and [continuously improved](https://www.reversinglabs.com/blog/how-to-harden-ml-models-against-adversarial-attacks) to boost their resilience. All classification models can detect if a file is malicious or not. The PE (Portable Executable) malware classifier is also able to provide the information on the detected threat type. The exact threat type indicates higher confidence in the classification result, while threats that get assigned a generic threat type ("Malware") may point to new, emerging malware. The following ML models are used for malware classification: - PE malware classifier - detects if a file is malicious (that covers all the threat types) and if it is a specific malware type (one of **Backdoor**, **Downloader**, **Infostealer**, **Keylogger**, **PUA**, **Ransomware**, **Worm**) - Script classifiers - apply to `Text/