The Sample Object

{
  // The unique ID of this sample.
  "id": "190329-rerrjddcaj", // string

  // The current status of the analysis process. Can be any of the values
  // listed below:
  //
  // "pending"
  // A sample has been submitted and is queued for static analysis or the
  // static analysis is in progress.
  //
  // "static_analysis"
  // The static analysis report is ready. The sample will remain in this
  // status until a profile is selected.
  //
  // "scheduled"
  // All parameters for sandbox analysis have been selected. The sample is
  // scheduled for running on the sandbox.
  //
  // "running"
  // The sample is being run by the sandbox.
  //
  // "processing"
  // The sandbox has finished running the sample and the resulting metrics
  // are being processed into reports.
  //
  // "reported"
  // The sample has reports that can be retrieved. This status is terminal.
  //
  // "failed"
  // Analysis of the sample has failed. Any other status may transition into
  // this status. This status is terminal.
  "status": "reported", // string

  // The sample kind that was submitted. Either "file" or "url".
  "kind": "file", // string

  // If the sample kind is file, this is the name of the uploaded file.
  // Otherwise, this field is omitted.
  "filename": "evil.bat" // string

  // If the sample kind is url, this is the url that was submitted. Otherwise,
  // this field is omitted.
  "url": "http://example.com/evil.js", // string

  // If true, the sample can be viewed by only the requesting user or
  // organization the user belongs to. If false, the sample can be viewed by
  // anyone with a Hatching Triage account.
  "private": false, // bool

  // The time this sample was submitted.
  "submitted": "2019-04-05T13:37:00Z", // timestamp string

  // The time the analysis has been completed and a report has been generated.
  // Only present if the status is equal to "reported".
  "completed": "2019-04-05T13:42:00Z", // timestamp string
}

GET /samples

Queries the collection of samples submitted by requester.

Query Parameters

  • subset (default owned), if set to owned, all the samples that the requesting user is able to access are returned. If set to public all samples that can be viewed by any user returned.

POST /samples

Submits a new sample for analysis. This endpoint allows both files and URLs to be submitted by setting the kind field to either "file" or "url" respectively.

Key Type Description
kind String Either "file" or "url"
interactive Boolean If set to true, the analysis profile must be chosen manually after static analysis has finished. Optional
profile_id String The ID of the profile to use. Optional
url String The URL to use as sample. Requires kind to be set to "url"
file File The uploaded file. Requires kind to be set to "file"

Submitting a file

File submissions are required to be performed using the multipart/form-data scheme instead of JSON.

The uploaded file should be named file in the form and have a filename. Any other parameters should be encoded in a JSON object named _json.

Submitting a URL

Using URLs as a sample is not implemented yet. Attempting to submit a URL will trigger an internal server error.

Submitting an URL requires a regular JSON request. To submit a URL, set the kind to "url" and include the URL of the sample as url.

Choosing a profile

By default, interactive is set to false, meaning that a profile is chosen automatically, requiring no interaction with the analysis process.

To manually set a profile, set the profile_id to the ID of the profile to use. This option requires interactive to be false.

If interactive is set to true, analysis pauses when the sample status reaches static_analysis. To continue, you must manually select a profile.

Please refer to the documentation for POST /samples/{sampleID}/profile.

Examples

Submitting a file:

$ curl -H 'Authorization: Bearer <YOUR_ACCESS_KEY>' \
    -X POST \
    -F 'file=@<YOUR_SAMPLE_FILE_PATH>' \
    -F '_json={"kind":"file","interactive":true}' \
    'https://api.tria.ge/v0/samples'

Note that the interactive bit is set, this requires us to manually select an analysis profile later.

GET /samples/{sampleID}

Queries the sample with the specified ID.

Errors

  • 404, "NOT_FOUND", if the sample does not exists.

POST /samples/{sampleID}/profile

When a sample is in the static_analysis status, a profile should be selected in order to continue.

Examples:

Set a profile automatically:

$ curl -H 'Authorization: Bearer <YOUR_ACCESS_KEY>' \
    -X POST \
    --data-raw '{"auto":true}' \
    'https://api.tria.ge/v0/samples/<SAMPLE_ID>/profile'

Set a profile manually by specifying its ID:

$ curl -H 'Authorization: Bearer <YOUR_ACCESS_KEY>' \
    -X POST \
    --data-raw '{"profile_id":"942cede0-88ca-4cac-a8ba-5e2926d59ed6"}' \
    'https://api.tria.ge/v0/samples/<SAMPLE_ID>/profile'

Errors

  • 404, "NOT_FOUND", if the sample does not exists.
  • 409, "PROFILE_NOT_SETTABLE", the profile could not be set due to the status of the sample not being static_analysis or the analysis not being interactive.

GET /samples/{sampleID}/reports/static

Retrieves the generated static report.

Errors

  • 404, "NOT_FOUND", if the sample does not exists.
  • 404, "REPORT_NOT_AVAILABLE", if the status of the sample is before "static_analysis" or the status is "failed".

GET /samples/{sampleID}//report_triage.json

Retrieves the generated Triage Report for a single task.

Examples

$ curl -H 'Authorization: Bearer <YOUR_ACCESS_KEY>' http://api.tria.ge/v0/samples/<SAMPLE_ID>/task1/report_triage.json | jq

Errors

  • 404, "NOT_FOUND", if the sample does not exists.
  • 404, "REPORT_NOT_AVAILABLE", if the status of the task is not "reported".

GET /samples/{sampleID}/events

Opens a server-sent event stream to keep track of the progress of a sample in real time. The stream consists of a series of events labeled sample with a JSON encoded sample object as payload.

When the connection is opened, the current status of the sample is always sent.

After a sample with a terminal status ("reported", "failed") is sent, the connection is closed. The client should not attempt to reconnect since no further updates will be sent.

Examples

$ curl -H 'Authorization: Bearer <YOUR_ACCESS_KEY>' \
    'https://api.tria.ge/v0/samples/<SAMPLE_ID>/events'

Caveats

The EventSource API in web-browsers does not support setting headers, such as the Authorization header required by this API. If you are developing an API client which connects directly from a web-browser, consider using a fetch based polyfill.

Errors

  • 404, "NOT_FOUND", if the sample does not exists.