Page tree
Skip to end of metadata
Go to start of metadata

For more technical documentation of the endpoints, API models, and how to use them, visit the Swagger API documentation.


Introduction

The sample service is a database used for storing and retrieving sample files that may or may not be malicious. Along with the sample file itself, there is also stored metadata, analysis results, evidence, links, and submissions.
Have a look at the table below for an explanation of some key concepts related to the sample service.


ConceptDescription
Sample

A file that may or may not be malicious. A sample can be uploaded and downloaded via the API if the user has the appropriate access. 

See the samples section for a description of the available API endpoints and how to use them.

Analysis

The data produced from an analysis of a sample. This analysis can contain information about f.ex., specific characteristics from executing the sample, like network traffic, loaded libraries, or other things.

See the analysis section for a description of the available API endpoints and how to use them.

Evidence

An entity added to an analysis. An evidence entry can contain information such as mime type and other data resulting from the analysis.

See the evidence section for a description of the available API endpoints and how to use them.

Link

An entity used to indicate a relationship between samples. If, f.ex a sample downloads or loads another sample they have a relationship of that given type.

See the link section below for a description of the available API endpoints and how to use them.

Submission

A recorded event of a spotted sample in the wild. This is typically submitted by a customer that has spotted a sample on their 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.

See the submission section for a description of the available API endpoints and how to use them.

Challenge

A challenge the user must solve in order to prove that he/she possesses a given sample. The challenge solution is used when adding a sample submission.

See the challenge section for a description of the available API endpoints and how to use them.


Sample

Uploading a sample

The role submitSample is required to be able to upload samples.

To upload a sample file, the sample endpoint can be used with a POST operation, along with the raw file.
Upon success, the HTTP response will contain either a 201 or 200 status code, depending on whether the sample already exists or not. The response body will be JSON formatted, and contain, among other things, the ID of the sample which will be the calculated sha256 hash of the file. This ID is used in all requests relating to a sample, like downloading a sample, adding an analysis, or submission.

curl -XPOST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/octet-stream" -d @./sample-file.exe https://api.mnemonic.no/sampledb/v2/sample

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

Downloading a sample

There are two ways of downloading a sample. Using the safe method will download a sample that has been zipped and password protected with the word "infected". The unsafe method will download a raw sample without any form of protection.

Safe

The role downloadSample is required to be able to download a safe, zipped sample. In addition, the customer needs to have access to at least one submission for the same sample.
The example below will download a sample and store it in a file named safe-sample.zip.

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

For more detailed information, you can check out the swagger documentation.

Unsafe

The role downloadRawSample is required to be able to download the raw sample. In addition, the customer needs to have access to at least one submission for the same sample.
The example below will download a sample and store it in a file named raw-sample.

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

For more detailed information, you can check out the swagger documentation.

Fetching sample metadata

The role viewSamples is required to be able to fetch sample metadata. In addition, the customer needs to have access to at least one submission for the same sample.

To fetch metadata about a sample, the sample endpoint can be used with a GET operation along with the sample ID. The response body will be JSON formatted and contain information like size, and timestamp.

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

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

Analysis

An analysis is the result of an analysis of a sample and a submission. An analysis thus belongs to a sample and must be added or fetched from a specific sample.

Adding an analysis

The role addSampleAnalysis is required to be able to add an analysis. In addition, read access to the sample is required. Below is an example of how to add an analysis.

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>/analysis -d '{
  "customer": "mnemonic",
  "userAgent": {
    "name": "user agent",
    "version": "1.0"
  },
  "tlp": "white",
  "acl": [],
  "analysisResult": {
    "meta": "data"
  }
}'

The field analysisResult may contain arbitrary data, as long as it is valid Json. In other words, it can be a string, array, object, ..

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

Fetching analyses

The role viewSampleAnalysis is required to be able to fetch or list analyses.

List

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

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

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

Fetch

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

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

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

Evidence

Evidence is an entity that belongs to an analysis. It can contain information such as mime type and other data resulting from the analysis.

Adding evidence

The role addSampleAnalysisEvidence is required to be able to add an evidence entity.

To add an evidence entity, the evidence endpoint can be used with a POST operation along with the sample ID, and the analysis ID. The request and response body will be JSON formatted and contain the submitted evidence.

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>/analysis/<analysis ID>/evidence -d '{
  "evidence": [65, 65, 65, 65],
  "mimeType": "mime type of the evidence",
  "name": "evidence name"
}'

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

Fetching evidence metadata

The role viewSampleAnalysis is required to be able to fetch or list evidence metadata.

List

To list evidence entries of an analysis, the evidence endpoint can be used with a GET operation along with the sample ID, and analysis ID. The response body will be JSON formatted and contain metadata about the evidence.

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

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

Fetch

To fetch a specific evidence entry of an analysis, the evidence endpoint can be used with a GET operation along with the sample ID, analysis ID, and the evidence ID. The response body will be JSON formatted and contain metadata about the evidence.

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

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

Fetching evidence data

The role viewSampleAnalysis is required to be able to download the raw data in an evidence entry.

To download the raw data of an evidence entity the evidence download endpoint can be used with a GET operation along with the sample ID, analysis ID, and evidence ID. The response body will be the raw bytes of the evidence, with the Content-Type  HTTP header set accordingly. 

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

For more detailed information you can check out the swagger documentation.

Link

A link is an entity used to indicate a relationship between two samples. If, for example, a sample downloads or loads another sample they have a relationship of that given type.

The role addSampleAnalysis is required to be able to add a link.

To add a link to a sample, the link endpoint can be used with a POST operation along with the sample ID. The request and response body is JSON formatted and contains information about the link. The example request below adds a link between the given samples defined in the context path in the URL, and in the reference -field in the JSON request, of type downloads.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://devapi.mnemonic.no/sampledb/v2/sample/<sample sha256 ID>/link -d '{
  "customer": "customer",
  "userAgent": {
    "name": "user agent",
    "version": "version"
  },
  "tlp": "white",
  "acl": [],
  "type": "downloads",
  "reference": "<sample sha256 ID 2>"
}'

For more detailed information on what the request and response model looks like, you can check out the swagger documentation.

The role viewSampleAnalysis is required to be able to fetch or list links.

List

To list links of a sample, the link endpoint can be used with a GET operation along with the sample ID. The response body will be JSON formatted and contain data about the link.

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

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

Fetch

To fetch a specific link, the link endpoint can be used with a GET operation along with the sample ID, and the link ID. The response body will be JSON formatted and contain data about the link.

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

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

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 addSampleSubmission 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 section below. 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"
  }
}'

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

Fetching submissions

The role viewSampleSubmission 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/

For more detailed information on what the response model looks like, you can check out the swagger 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>

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

Challenges

A challenge can be generated and used by the user to prove to the sample service that he/she possesses a particular sample file. The answer to this challenge will be the challenge token and must be used in the request when adding a sample submission. A challenge can only be used once – if you want to submit multiple sample submissions a challenge must be created and answered for each submission.

Generating a challenge

To generate a challenge, the challenge endpoint must be used with a POST operation along with the sample ID. The response body will be JSON formatted and contain the challenge itself.

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

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

This request can return three different responses, depending on whether the sample file exists and its file size. For how to handle each scenario, see the section solving a challenge below.

Solving a challenge

Generating a challenge might return three different kinds of responses in the form of HTTP status code 404, 422, or 200.

HTTP status code 404

This means that the sample file does not exist in the system. In this case, you need to upload the sample file using the sample-upload endpoint. See the sample section for how to do this. When the upload is finished, the JSON response will contain an object challenge with an id and sha256. This is then the solution to a challenge and can be used in the request when adding a submission.

HTTP status code 422

This means that the sample file is so small that a challenge cannot be generated. Instead, a full upload of the sample file must be done. When the upload is finished, the JSON response will contain an object challenge with an id and sha256. This is then the solution to a challenge and can be used in the request when adding a submission.

HTTP status code 200

The response will in this case contain a JSON object with three fields inside the object data: id, offset, and length.

Field nameDescription
id The ID of the challenge itself. This must be submitted along with the solution to the challenge
offset Represents an offset (in bytes) into the sample file
length Represents the number of bytes starting from offset in the sample file

The solution to the challenge will be the sha256 hash of length bytes, starting from the given offset into the sample file. Below is an example of how to solve the challenge for an arbitrary sample file in bash.

$ curl -X POST -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample/36621fe568d2bea6c98fb388d1e36a696bbc1885ad7a72e83b86c279e14e4177/challenge
{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "id": "4e8341a0-ba36-4eaa-8c0a-ce70ea92879b",
    "offset": 1239,
    "length": 1024
  },
  "size": 0
}
$ dd if=sample-file bs=1 skip=1239 count=1024 | shasum -a 256
1024+0 records in
1024+0 records out
1024 bytes transferred in 0.004667 secs (219411 bytes/sec)
7d97adb3783d3e136eba8542a1bb388eb70a291fdbde9bd63bc06f66a3ef7460 -

The solution is 7d97adb3783d3e136eba8542a1bb388eb70a291fdbde9bd63bc06f66a3ef7460, and must be submitted along with the challenge id 4e8341a0-ba36-4eaa-8c0a-ce70ea92879b when adding a submission.

  • No labels