Dynamic analysis submission (TCA-0207)

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)

The report about the performed analysis and behavior can be retrieved using the TCA-0106 Dynamic Analysis Report 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 API. After the sample and its metadata are uploaded, the hash of the sample can be submitted to the Dynamic Analysis API.

Samples must not exceed the maximum size limit of 400 MB.

For more information on uploading files to the cloud, please refer to the TCA-0202/0203 File Upload 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.

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.

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

{
  "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

{
  "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:

{
  "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:

{
  "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:

{
  "rl": {
    "sha1": "83c69d2b26a1d1e5218e666316080b458e2e6948",
    "platform": "windows7"
  }
}

Submitting a URL for analysis

/api/dynamic/analysis/analyze/v1/query/json

Request body:

{
  "rl": {
    "url": "http://www.google.com",
    "platform": "windows7"
  }
}

Submitting a Base64 encoded URL for analysis

/api/dynamic/analysis/analyze/v1/query/json

Request body:

{
  "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

{
  "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.