# Dynamic Analysis Submission API (tca-0207) — Spectra Intelligence

> Submit files or URLs to Spectra Intelligence tca-0207 for sandbox detonation on Win11, Win10, Win7, macOS, Linux, or Android; retrieve results via tca-0106.

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

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/dynamic-analysis-reversinglabs-cloud-sandbox/post/apidynamicanalysisanalyzev1querypost_format" />

### 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`.
