REST API

GET /api/v1/sample

Returns a list of all samples in the db along with some properties

Request

GET /api/v1/sample

Request Parameter Description

No parameters

Response

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": 1,
    "name": "sample.exe",
    "md5": "9551ff314306e062e21535ce99073883",
    "sha1": "507055a04151fa843eee67f85cdbe12fca5d0868",
    "sha256": "5427922f4f730f185a5e739a5a50b00e8f40241c739cf898a74c15b047d63b8d",
    "size": "537043",
    "start_date": "Mon Jul  8 13:42:45 2019",
    "end_date": "Mon Jul  8 13:46:46 2019"
  },
  ...
]

Error codes

400 Bad Request Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "invalid sample id"
}

POST /api/v1/sample

This endpoint is used to upload a new sample to the system.

Request

POST /api/upload
{
  "allow_internet": STRING,
  "minspeed": INT,
  "sample": STRING,
  "sample_name": STRING
}

Request Parameter Description

• allow_internet: True, False - Specifies whether the system is allowed to scan the sample with containers which have internet access.
• minspeed: -1, 0, 1, 2, 3 - MultiAV will use only scanners which are faster than the provided speed level. -1 = Ultra, 0 = Fast, 1 = Medium, 2 = Slow, 3 = All
• sample: BASE64 - Base64 encoded sample
• sample_name: String - Filename of the sample

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": INT,
  "hashes": {
    "md5": STRING,
    "sha1": STRING,
    "sha256": STRING
  },
  "file": {
    "name": STRING,
    "size": INT,
}
}

Error codes

400 Bad Request Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "missing parameter: allow_internet"
}

GET /api/v1/sample/<SAMPLE_ID>

Returns a list of all samples in the db along with some properties

Request

GET /api/v1/sample/<SAMPLE_ID>

Request Parameter Description

• SAMPLE_ID: id of the sample for which the report should be returned

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": 1,
  "name": "sample.exe",
  "md5": "9551ff314306e062e21535ce99073883",
  "sha1": "507055a04151fa843eee67f85cdbe12fca5d0868",
  "sha256": "5427922f4f730f185a5e739a5a50b00e8f40241c739cf898a74c15b047d63b8d",
  "size": "537043",
  "infected": -1,
  "start_date": "Mon Jul  8 13:42:45 2019",
  "end_date": "Mon Jul  8 13:46:46 2019",
  "result": [
    {
      "name": "FileInfo",
      "plugin_type": 2,
      "speed": -1,
      "has_internet": false,
      "queued": 0,
      "scanning": 0,
      "magic": {
        ...
      },
      "ssdeep": "6144:fuY8d8TTNMMIunNtaRYHYDtXk5LGE0S8Rbfie3qIy+QYY:MmF7zCY4DuL1+fie39lY",
      "trid": [
        "STRING"
      ],
      "exiftool": {
        ...
      }
    },
    {
      "infected": false,
      "result": "",
      "engine": "5.53.0",
      "database": "5.65",
      "updated": "20190708",
      "name": "Sophos",
      "plugin_type": 1,
      "speed": 2,
      "has_internet": false,
      "queued": 0,
      "scanning": 0
    },
    {
      "infected": false,
      "result": "",
      "engine": "7.141118",
      "updated": "20190708",
      "name": "BitDefender",
      "plugin_type": 1,
      "speed": 1,
      "has_internet": false,
      "queued": 0,
      "scanning": 0
    },
	...
  ]
}

If the end_date field is set, the scanning of this sample has been completed. Additionally, each scanner result in the result array contains the flags "queued" and "scanning" which can be used to determine the current state of the individual scans. The current state is represented by the flag which has 1 as it's value.

Error codes

400 Bad Request

{
  "error": "invalid sample id"
}