Contents
Scan request
Purpose
Scan of the object specified in the request body.
The following objects can be scanned:
- One file
- Multiple files
- One or multiple Docker images located in a specific repository
- One or multiple Docker images located in a specific repository with additional settings
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"
}
Scan file request
Content-Type
application/octet-stream
Request body
File.
Response example:
|
Request to scan multiple files
Content-Type
multipart/form-data
Request body
Multiple files.
Response example:
|
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:
|
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:
|
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 thedestination
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:
|