Jobs#

A job represents the analysis of a sample and is used to track its progress. On its own it holds no analysis results or verdicts, but contains information such as when an analysis job was started and completed, and whether it failed or not. A job also contains one or more job tasks. The jobs API is intended to be used by the external system managing the analysis itself.

Job creation#

A job can not be created manually via any API endpoint. It is automatically created by the Sample service based on incoming submissions.

Whenever a new job is created, it is posted to the Kafka topic Sample.Analysis.Job.OSL/SVG. The format of messages in this topic will be in JSON format and contain the job ID, the submission it was created from, and the sample classification.

{
  "jobID": "12345678-1234-1234-1234-123456789abc",
  "submission": {
    "id": "abcdef01-abcd-abcd-abcd-abcdef012345",
    "customer": "customerid",
    "sample": {
      "id": "8f84837cf04c1694512256ef78fa67c051b92326e31af2598efad37ccd2e01d9"
    },
    "createdByUser": {
      "id": 0,
      "shortName": "sn",
      "name": "name",
      "customer": null,
      "domain": null
    },
    "createdTimestamp": 123,
    "name": "fielname.exe",
    "timestamp": 124,
    "mimeType": "application/octet-stream",
    "metaData": {
      "key": "value"
    },
    "tlp": "white",
    "acl": [],
    "userAgent": {
      "name": "python-requests",
      "version": "3"
    }
  },
  "classification": {
    "sample": "8f84837cf04c1694512256ef78fa67c051b92326e31af2598efad37ccd2e01d9",
    "classificationID": "12345678-1234-1234-1234-123456789012",
    "createdTimestamp": 123,
    "version": "1",
    "type": "PE",
    "superType": "executable",
    "arch": "x86",
    "platform": "win",
    "meta": {}
  }
}

Updating jobs#

The role SAMPLEDB-ANALYZER is required to be able to update jobs.

As the analysis job progresses the status should be updated. This can be done using the job endpoint with a PUT operation. The response body will be in JSON format, and contain the updated job.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/sampledb/v2/job/<job id> -d '{
	"state": "executing"
}'

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

Aborting jobs#

The role SAMPLEDB-USER or higher is required to be able to abort jobs.

Since the analysis jobs themselves are executed externally, the Sample service can’t abort analysis jobs directly. It can however request the job to be aborted. This can be done using the DELETE operation for the jobs endpoint. The response body will be in JSON format and contain the updated job status.

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/job/<job id>

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

Fetching jobs#

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

List#

To list analysis jobs, the jobs endpoint can be used with a GET operation. The response body will be in JSON format, and contain a list of objects containing information about the job. By default only active jobs are returned (enqueued or executing).

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/job

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

Fetch#

To fetch a single instance of an analysis job, the fetch job endpoint can be used with a GET operation. The response body will be in JSON format, and contain all information about the job.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/job/<job id>

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

Searching for jobs#

To perform an advanced search the job 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 job objects.

The example below will search for jobs that were aborted or timed out in the last week.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/sampledb/v2/job/search -d '{
	"state": [
		"aborted",
		"timeout"
	],
	"startTimestamp": "now - 1 week",
	"endTimestamp": "now",
	"timeFieldStrategy": [
		"enqueuedTimestamp",
		"startTimestamp",
		"endTimestamp"
	],
	"timeMatchStrategy": "any"
}'

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

limit

25

Limit the number of search results. Can be anywhere in the range of 0 to 10,000.

offset

0

Skip the first ‘offset’ number of objects

sortBy

enqueuedTimestamp

Sort the result by the value of certain fields. This parameter may be a list of parameter values. Refer to the Swagger API documentation for a list of possible values

state

enqueued, executing

Return jobs in the defined states only

sampleSha256

Return jobs for certain samples only

customer

Return jobs for certain customers only

startTimestamp

The start timestamp to search for jobs within a time range

endTimestamp

The end timestamp to search for jobs within a time range

timeFieldStrategy

Which timestamp fields to use when searching within a time range

timeMatchStrategy

Whether all or any of the time fields must fall within the specified time range