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.
Simple search#
To perform a simple search the submission 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 submission objects.
The example below will search for submissions updated within the last month, and that also
contain either of the keywords evil
and apex
.
curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/submission?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 |
---|---|---|
|
A list of strings used to match against submissions. This parameter can be specified multiple times. If there are more than one keywords parameters, submission containing one or more of the keywords will match. e.i “submission contains keyword1 OR keyword2 OR keyword3”. If no keywords parameter is specified, all samples falling within the indexStartTimestasmp and indexEndTimestamp will match the search |
|
keywordFieldStrategy |
all |
Specifies which fields to search for keywords on |
keywordMatchStrategy |
any |
Whether the keywords must match all or any of the keyword fields |
sortBy |
-observedTimestamp |
A list of fields that the results should be sorted by. This parameter can be specified multiple times. Prepending the field with a ‘-’ will sort in descending order. |
|
|
Used to limit the number of search results. Can be anywhere in the range of 0 to 10,000. |
|
|
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. |
|
|
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 submission 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 submission objects.
The example below will search for submission updated within the last month, and that also
contain 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://api.mnemonic.no/sampledb/v2/submission/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 |
|
A list of strings used to match against submissions. . |
|
|
|
Defines what fields to match keywords against. |
|
|
|
Whether all or any of the keyword fields must match the keywords |
|
Time search |
|
The timestamps indicated by the 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> |
|
|
he timestamps indicated by the 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> |
||
|
|
Defines what time fields to match |
|
|
|
Whether all or any of the time fields must fall within the time range. |
|
Top level field search |
id |
Restrict the search to known submission IDs |
|
sampleSha256 |
Restrict the search to submissions belonging to any of the specified samples |
||
tlp |
Restrict the search to submissions where it must contain any of the specified TLPs |
||
mimeType |
Restrict the search to submissions where it must contain any of the specified mime types |
||
fileName |
Restrict the search to submissions where it must contain any of the specified file names |
||
customer |
Restrict the search to submissions belonging to any of the specified customers |
||
excludeFlags |
Restrict the search to submissions that does not contain any of the specified flags |
||
includeFlags |
Restrict the search to submissions that contains any of the specified flags |
||
Metadata search (search on submission metadata) |
path |
The path (dot-notation) to the field to match the value against. May not contain spaces. The path should refer to a field inside the metadata object, not including the top level metadata field itself. |
|
value |
Values to match against the field pointed to by ‘path’ |
||
exclude |
Whether submissions matching this path and value should be excluded from the search result |
||
required |
Whether submissions matching this path and value should be required to be present for the search to match |
||
User agent search |
version |
Restrict the search to user agents with either of the specified versions |
|
name |
Restrict the search to user agents with either of the specified names |
||
Sub criteria |
|
A list of sub-criteria. The matching submission 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 :
|
|
Top level criteria |
|
|
Specify sort ordering for returned submissions. |
|
|
Used to limit the number of search results. Can be anywhere in the range of 0 to 10,000. |
|
|
|
Limit the search to submissions 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> |
|
|
|
Limit the search to submission 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> |
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, customer, and TLP parameters. The search results returned to the user will be submissions satisfying all these criteria. For example, the search criteria below:
{
"keywords": ["evil", "apex"],
"keywordFieldStrategy": ["submission"],
"keywordMatchStrategy": "any",
"customer": ["123", "234", "345"],
"tlp": ["white", "green"]
}
can be translated into the following SQL-like query:
SELECT * FROM samples WHERE
(submission.* CONTAINS "evil" OR "apex") AND
(submission.customer CONTAINS "123" OR "234" OR "345") AND
(submission.tlp CONTAINS "white" or "green");
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 by 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 |
||
statistics |
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 |
|
timeline |
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.