Kaspersky Endpoint Security for Linux

Scan request

Purpose

Scan of the object specified in the request body.

The following objects can be scanned:

Path

http://<server>:<port>/scans[?wait=1]

Settings

The optional wait setting specifies the type of the scan session.

If the setting value is 1, synchronous scan is performed and the application sends a report when scan finishes.

If the setting value is 0, asynchronous scan is performed, and the response is as follows:

{

"id"="7d27e9b4-a4d7-469b-bdcf-ebfe953498e4",

"location"="/scans/7d27e9b4-a4d7-469b-bdcf-ebfe953498e4"

}

where:

  • id – unique identifier of the scan session.
  • location – path for requesting information on this section: http://<server>:<port>/scans/<location>.

Request headers

The request can contain the following headers:

  • Content-Type

    Defines the type of the object submitted for scan.

    Supported values:

    • application/octet-stream – one file
    • multipart/form-data – multiple files
    • text/plain – one or multiple Docker images located in a specific repository
    • application/json – one or multiple Docker images located in a specific repository with additional settings
  • x-api-key (optional)

    API key specified in the KRAS4D_XAPIKEY environment variable or the xapikey variable in the configuration file.

Possible errors

If an unsupported value is specified in the Content-Type header, the application returns the following error:

{

"error"={

"code"="NOT_SUPPORTED_CONTENT_TYPE",

"details"="<content type>",

"message"="Not supported Content-Type"

},

"status"="error"

}

In this section

Scan file request

Request to scan multiple files

Request to scan Docker images

Request to scan Docker images with additional settings

Page top
[Topic 213875]

Scan file request

Content-Type

application/octet-stream

Request body

File.

Response example:

{

"completed": "Mon, 01 Mar 2021 06:54:39 GMT",

"created": "Mon, 01 Mar 2021 06:54:38 GMT",

"progress": 100,

"scan_result": {

"noname": {

"started": "2021-03-01 06:54:39",

"stopped": "2021-03-01 06:54:39",

"threats": [

{

"name": "EICAR-Test-File",

"object": "/root/kesl-service/tmp/b8eb4128-8cb4-4964-87cf-b9853e6544ec"

}

],

"verdict": "infected"

}

},

"status": "completed",

"verdicts": [

"infected"

]

}

Page top
[Topic 213876]

Request to scan multiple files

Content-Type

multipart/form-data

Request body

Multiple files.

Response example:

{

"completed": "Mon, 01 Mar 2021 06:55:44 GMT",

"created": "Mon, 01 Mar 2021 06:55:43 GMT",

"progress": 100,

"scan_result": {

"clean": {

"started": "2021-03-01 06:55:43",

"stopped": "2021-03-01 06:55:43",

"verdict": "clean"

},

"corrupted.com": {

"errors": [

{

"error": "Corrupted object",

"object": "/root/kesl-service/tmp/75d28fe6-8154-4361-9382-90a76861518a"

}

],

"started": "2021-03-01 06:55:43",

"stopped": "2021-03-01 06:55:43",

"verdict": "non scanned"

},

"error.com": {

"errors": [

{

"error": "read error",

"object": "/root/kesl-service/tmp/37f6e0dd-13f9-4d11-899c-5fe0f23e407d"

}

],

"started": "2021-03-01 06:55:44",

"stopped": "2021-03-01 06:55:44",

"verdict": "non scanned"

},

"infected.com": {

"started": "2021-03-01 06:55:44",

"stopped": "2021-03-01 06:55:44",

"threats": [

{

"name": "EICAR-Test-File",

"object": "/root/kesl-service/tmp/7d664646-bf56-4060-b958-5ce9e746c929"

}

],

"verdict": "infected"

}

},

"status": "completed",

"verdicts": [

"clean",

"non scanned",

"infected"

]

}

Page top
[Topic 213878]

Request to scan Docker images

Content-Type

text/plain

Request body

Link to the Docker images to scan.

The following values are available:

  • Path to an image in the repository (for example, https://index.docker.io/jerbi/eicar:latest).
  • Path mask for multiple images (for example, https://index.docker.io/<name mask>:<tag mask>). You can use the ? and * characters to specify a mask.

Response example:

{

"completed": "Sun, 31 Jan 2021 10:29:26 GMT",

"created": "Sun, 31 Jan 2021 10:29:20 GMT",

"progress": 100,

"scan_result": {

"jerbi/eicar:latest": {

"started": "2021-01-31 10:29:25",

"stopped": "2021-01-31 10:29:26",

"threats": [

{

"name": "EICAR-Test-File",

"object": "[image:docker.io/jerbi/eicar:latest] /eicar.com.txt"

}

],

"verdict": "infected"

}

},

"status": "completed",

"verdicts": [

"infected"

]

}

Possible errors

A request using the Docker REST API is used to get a list of images by mask.

However, on many public servers it is disabled for security reasons. An attempt to scan images by mask on such servers results in an error.

Error example:

{

"completed": "Mon, 01 Mar 2021 07:02:24 GMT",

"created": "Mon, 01 Mar 2021 07:02:22 GMT",

"scan_errors": [

{

"code": 401,

"details": {

"context": {

"image_mask": "/jerbi/eic*:latest",

"repository": "index.docker.io",

"repository_base": "index.docker.io"

},

"errors": [

"Unauthorized"

]

},

"message": "Invalid source"

},

[

"Unauthorized"

]

],

"status": "completed"

}

Page top
[Topic 213879]

Request to scan Docker images with additional settings

Content-Type

application/json

Request body

JSON of the following type:

{

"source": "https://index.docker.io/jerbi/eicar:latest",

"params": {

"destination": "https://fake",

"skipimageifexists": true,

"custom_callbacks": {

"on_detect": {

"uri": "http://10.16.42.75:5050",

"content-type": "application/json",

"body": {

"session_id": "100",

"session_init": "20201105T072403+0300",

"infected_items": "$infected"

}

},

"on_complete": {

"body": {

"session_id": "100",

},

"uri": "http://10.16.42.75:5050/on_complete",

}

}

}

}

Additional request settings

The params section can contain the following settings:

  • destination (optional) – the server to which the scanned image will be copied.
  • skipimageifexists (optional) – do not scan or copy the image if the destination server already has an image with the same name and SHA256 hash. This setting can only be specified if the destination setting is specified.
  • custom_callbacks (optional) – describes the requests that should be sent when scan finishes:
    • on_detect – the request is sent if a threat is detected.
    • on_complete – the request is always sent when scan finishes.

In the description of the request body, you can specify the $infected substitution variable. The list of infected objects is substituted instead of this variable.

Response example:

{

"completed": "Mon, 01 Mar 2021 07:13:49 GMT",

"created": "Mon, 01 Mar 2021 07:13:42 GMT",

"progress": 100,

"scan_errors": [

{

"code": 500,

"message": "Unable to get images hash from destination registry"

}

],

"scan_params": {

"destination": "https://fake",

"skipimageifexists": true

},

"scan_result": {

"jerbi/eicar:latest": {

"started": "2021-03-01 07:13:48",

"stopped": "2021-03-01 07:13:49",

"threats": [

{

"name": "EICAR-Test-File",

"object": "[image:docker.io/jerbi/eicar:latest] /eicar.com.txt"

}

],

"verdict": "infected"

}

},

"status": "completed",

"verdicts": [

"infected"

]

}

Page top
[Topic 213880]