Submission#

A submission is a record of a sample file being spotted in a customer network in some way. A submission contains information about f.ex., file name, mime type of the sample, and the timestamp when it was discovered. For the customer to get access to a sample file, and its metadata, it needs to have at least one submission for the given sample.

Adding a submission#

The role SAMPLEDB-USER or higher is required to be able to add a submission.

Additionally, the user needs to prove that he/she actually possesses the sample file in question. This is done in accordance with the challenge protocol described in the next section. First, the challenge must be generated, then solved. The solution to the challenge will be the challenge token and must be present in the request when adding the submission.

To add a submission, the submission endpoint can be used with a POST operation along with the sample ID. The request and response body will be JSON formatted and contain all the submission information.

curl -X POST -H "Argus-API-Key: my/api/key" H "Content-Type: application/json" https://api.mnemonic.no/sampledb/v2/sample/<sample sha256 hash>/submission -d '{
  "fileName": "sample file name",
  "timestamp": 1608557674,
  "mimeType": "sample file mime type",
  "metaData": {
    "metadata-key1": "metadata-value1"
  },
  "tlp": "green",
  "acl": [],
  "userAgent": {
    "name": "user agent",
    "version": "1.0"
  },
  "challengeToken": {
    "id": "challenge id",
    "sha256": "challenge token"
  }
}'

Tip

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

Fetching submissions#

The role SAMPLEDB-VIEWER or higher is required to be able to fetch or list submissions.

List#

To list submissions of a sample, the submission endpoint can be used with a GET operation along with the sample ID. The response body will be in a JSON format, and contain all information in the submission. Note that only submissions that the customer has access to will be listed.

curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample/<sample sha256 hash>/submission/

Tip

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

Fetch#

To fetch a specific submission of a sample, the submission endpoint can be used with a GET operation along with the sample ID and the submission ID. The response body will be JSON formatted and contain all information in the submission.

curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample/<sample sha256 hash>/submission/<submission ID>

Tip

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

Searching for submissions#

The role SAMPLEDB-VIEWER or higher is required to be able to search for samples.

Fetching submission statistics#

The role SAMPLEDB-VIEWER or higher is required to be able to see submission statistics.

To perform a simple aggregation the submission endpoint can be used with a POST operation along with a JSON body making up the aggregation criteria. The response body will be JSON formatted and contain the submission statistics.

The submission statistics request is an extension of the advanced search endpoint, but has the following additional parameters:

Aggregation criteria

Field Name

Values

Description

groupBy

field

[customer, fileName, sampleSha256, mimeType, tlp, metaData]

The field by which to group Submissions when generating statistics

limit

Min 0, default 25

The maximum number of distinct categories for the given group field for which to generate statistics

metaDataField

If the statistics should be group by a MetaData-related field, the metadata subfield needs to be specified here

statisticsMetrics

name

The name for this aggregation. Must be unique for the parent statistics request. Sanitized to alphanumeric, “-” and “_”

field

[submittedTimestamp, observedTimestamp, expiryTimestamp]

The submission field for which we want statistics

rangeMetrics

name

The name for this aggregation. Must be unique for the parent statistics request. Sanitized to alphanumeric, “-” and “_”

field

[submittedTimestamp, observedTimestamp, expiryTimestamp]

The submission field for which we want statistics

resolution

[hour, day, week, month, quarter]

The temporal resolution by which to sub-aggregate the range metric

It is possible to aggregate on multiple fields at the same time, but it will fail if all fields are empty.

Tip

For more detailed information on all the different search criteria and possible values check out the Swagger API documentation.