File upload (TCA-0202-0203)

This service allows a user to upload a sample and sample metadata to the Spectra Intelligence repository. Uploading the sample will automatically trigger analysis of the sample in the ReversingLabs processing pipeline.

The file upload is actually two requests: the first request uploads the file contents, and the second uploads the metadata.

The upload of archives is supported and recommended only for files that will later be submitted for dynamic analysis using the TCA-0207 Dynamic Analysis service. When submitting a ZIP file with a custom password for upload, the password needs to be provided in the Metadata Upload Request. If the password is one of the standard passwords (infected, password, or 1234), the password does not need to be specified in the Metadata Upload Request.

When submitting an archive for upload, it is recommended to include the archive object when uploading sample metadata. If omitted, the sample will undergo standard sample processing, potentially resulting in incomplete processing of the zip content.

To be accepted by the TCA-0207 service, submitted archives must follow the size and file limits described in the TCA-0207 Dynamic Analysis user guide.

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, TCA-0103 Historic Multi-AV Scan Records, TCA-0104 File Analysis services, and TCA-0106 File Dynamic Analysis Report. 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 service, AV detections from the TCA-0103 Historic Multi-AV Scan Records service, and source info from the TCA-0104 File Analysis 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 classifies them as "KNOWN".

This API is rate limited to 10 requests per second.

Sample upload 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.

sha1sum example_file.tar.gz

Then, pass that hash as a path parameter (sha1_value in the URL above).

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 and TCA-0105). You can also add metadata several 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.

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.

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:

The metadata itself must be sent in XML format. The metadata may include an optional XML declaration in the beginning, such as <?xml version="1.0" encoding="UTF-8"?>.

<rl>
  <properties>
    <property>
       <name>string</name>
       <value>string</value>
    </property>
  </properties>
  <domain>string</domain>
  <archive>
    <archive_type>string</archive_type>
    <archive_password>string</archive_password>
  </archive>
</rl>

XML POST body example

<?xml version="1.0" encoding="UTF-8"?>
<rl>
  <properties>
    <property>
        <name>application_name</name>
        <value>MyApplication</value>
    </property>
    <property>
    <name>application_version</name>
        <value>7.0.3</value>
    </property>
    <property>
        <name>url</name>
        <value>http://myapplications.com/apps/utilities</value>
    </property>
    <property>
        <name>file_name</name>
    <value>MyApplication_7.0.3_English.exe</value>
    </property>
    <property>
    <name>tags</name>
        <value>application, utilities</value>
    </property>
  </properties>
  <domain>myapplications.com</domain>
  <archive>
    <archive_type>zip</archive_type>
    <archive_password>password123</archive_password>
  </archive>
</rl>

Custom Response Status Codes

This API implements custom response status codes:

CODE	DESCRIPTION
413	The request contained more than the maximum allowed amount of hashes (100).