Sample

Uploading a sample

The role SAMPLEDB-UPLOADER or higher 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

Tip

For more detailed information on what the response model looks like, you can check out the Swagger API 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 SAMPLEDB-VIEWER or higher 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

Tip

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

Unsafe

The role SAMPLEDB-VIEWER or higher 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

Tip

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

Fetching sample metadata

The role SAMPLEDB-VIEWER or higher 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>/

Tip

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

Searching for samples

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

Simple search

To perform a simple search the sample endpoint can be used with a GET operation along with the keywords query parameter. The response body will be JSON formatted and contain a list of sample metadata objects.

The example below will search for samples updated within the last month, and that also contain at least one submission, analysis, link, classification, or sample ID matching either of the keywords evil and apex.

curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/sample?indexStartTimestamp=now%20-%201%20months&indexEndTimestamp=now&keywords=evil&keywords=apex

Tip

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

The table below contains a list of valid query parameters and how they work:

Query parameter	Default value	Description
keywords		A list of strings used to match against submissions, analyses, links, the classification, and IDs of samples. This parameter can be specified multiple times. If there are more than one keywords parameters, samples containing one or more of the keywords will match. e.i “sample contains keyword1 OR keyword2 OR keyword3”. If no keywords parameter is specified, all samples falling within the indexStartTimestasmp and indexEndTimestamp will match the search
limit	25	Used to limit the number of search results. Can be anywhere in the range of 0 to 10,000.
indexStartTimestamp	now - 1 month	Limit the search to samples updated after this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the Time formats section of the general integration guide.
indexEndTimestamp	now	Limit the search to samples updated before this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the Time formats section of the general integration guide.

Advanced search

To perform an advanced search the sample search endpoint can be used with A POST operation along with a JSON body making up the search criteria. The response body will be JSON formatted and contain a list of sample metadata objects.

The example below will search for samples updated within the last month, and that also contain at least one submission, analysis, link, classification, or sample ID matching either of the keywordsevil and apex:

curl -X POST -H 'Content-Type: application/json' -H "Argus-API-Key: my/api/key" -d '{"indexStartTimestamp":"now - 1 month","indexEndTimestamp":"now","keywords":["evil","apex"],"keywordFieldStrategy":["all"],"keywordMatchStrategy":"any"}' https://devapi.mnemonic.no/sampledb/v2/sample/search

Tip

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

Search criteria	Field Name	Default	Description
Keyword search	keywords		A list of strings used to match against submissions, analyses, links, the classification, and IDs of samples.
	keywordFieldStrategy	all	Defines what fields to match keywords against.
	keywordMatchStrategy	any	Whether all or any of the keyword fields must match the keywords
Time Search	startTimestamp		The timestamps indicated by the timeFieldStrategy must be after this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the:ref:Time formats section of the general integration guide<api-iguide-general-time-search>
	endTimestamp		he timestamps indicated by the timeFieldStrategy must be before this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the:ref:Time formats section of the general integration guide<api-iguide-general-time-search>
	timeFieldStrategy	all	Defines what time fields to match startTimestamp and endTimestamp against.
	timeMatchStrategy	any	Whether all or any of the time fields must fall within the time range.
	indexStartTimestamp	now - 1 month	Limit the search to samples updated after this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the:ref:Time formats section of the general integration guide<api-iguide-general-time-search>
	indexEndTimestamp	now	Limit the search to samples updated before this timestamp. Supports milliseconds since epoch, ISO8601 time string, and a relative time format. For more information, see the:ref:Time formats section of the general integration guide<api-iguide-general-time-search>
User Search	user		A list of user IDs or short names. Matching samples must have resources, indicated by userFieldStrategy, created by any of these users.
	userFieldStrategy	all	Defines what fields to match the list of users against.
	userMatchStrategy	any	Whether all or any of the user fields must match the users.
Sample Search	sha256		A list of sha256 sample IDs. The search will be restricted to these samples only if defined.
	classification		A list of classification criteria. The matching samples must contain a classification matching any of the defined classification criteria.
	submission		A list of submission criteria. The matching samples must contain at least one submission matching any of the defined submission criteria.
	analysis		A list of analysis criteria. The matching samples must contain at least one analysis matching any of the defined analysis criteria.
	link		A list of link criteria. The matching samples must contain at least one link matching any of the defined link criteria.
	tlp		A list of TLP strings. The matching samples must contain at least one submission, analysis, or link matching any of the defined TLP values.
	fact		A list of fact criteria. The matching samples must contain at least one fact matching any of the defined fact criteria.
Sub criteria	subCriteria (recursive)		A list of sub-criteria. The matching samples must contain at least one matching sub-criteria. The sub-criteria model contains all of the fields described above, in addition to itself (making it recursive). It also contains these parameters : exclude: whether or not to exclude samples matching this sub-criteria required required: whether or not to require samples to match this sub-criteria
	limit	25	Used to limit the number of search results. Can be anywhere in the range of 0 to 10,000.

If multiple different search criteria are defined in the request, the matching samples must match all the criteria.

Fields defined in the object of the JSON request are ANDed together, while objects in arrays are ORed together if both exclude and required are false (default).

See the table above for an explanation of the exclude and required parameters.

For example, a user issues a search containing keywords, time, user, classification, and TLP parameters. The search results returned to the user will be samples satisfying all these criteria. For example, the search criteria below:

{
  "keywords": ["evil", "apex"],
  "keywordFieldStrategy": ["submission"],
  "keywordMatchStrategy": "any",
  "user": [123, 234, 345],
  "userFieldStrategy": ["submittedByUser"],
  "classification": [{
    "version": ["0.9", "1.0"],
    "superType": ["executable"]
  }, {
    "version": ["1.1"],
    "type": ["elf"]
  }],
  "tlp": ["white", "green"]
}

can be translated into the following SQL-like query:

SELECT * FROM samples WHERE
  (submission.* CONTAINS "evil" OR "apex") AND
  (submission.submittedByUser CONTAINS 123 OR 234 OR 345) AND
  ((classification.version CONTAINS "0.9" OR "1.0") AND classification.superType IS "executable") AND
  ((classification.version IS "1.1" AND classification.type IS "elf") AND
  ((submission.tlp CONTAINS "white" or "green") OR (analysis.tlp CONTAINS "white" or "green") OR (link.tlp CONTAINS "white" or "green"));