Содержание
Приложение 4. Управление KESL-контейнером через REST API
Взаимодействие с KESL‑контейнером реализовано через REST API.
Средствами REST API вы можете отправлять следующие запросы:
- запрос на проверку (POST);
- запрос на получение информации по сессиям проверки (GET);
- запрос на добавление сертификата реестра без перезагрузки контейнера (POST).
Запрос на проверку (POST)
Назначение
Проверка объекта, указанного в теле запроса.
Предусмотрена проверка следующих объектов:
- одного файла;
- нескольких файлов;
- Docker-образа или нескольких Docker-образов, расположенных в определенном репозитории;
- Docker-образ или несколько Docker-образов, расположенных в определенном репозитории, с указанием дополнительных параметров.
Путь
http://<server>:<port>/scans[?wait=1]
Параметры
Необязательный параметр wait задает тип сессии проверки.
Если параметру присвоено значение 1, то выполняется синхронная проверка и приложение присылает отчет после окончания проверки.
Если параметру присвоено значение 0, то выполняется асинхронная проверка, а ответ будет иметь вид:
{
"id"="7d27e9b4-a4d7-469b-bdcf-ebfe953498e4",
"location"="/scans/7d27e9b4-a4d7-469b-bdcf-ebfe953498e4"
}
где:
- id – уникальный идентификатор сессии проверки;
- location – путь для запроса информации по этой секции вида http://<server>:<port>/scans/<location>.
Заголовки запроса
Запрос может содержать следующие заголовки:
- Content-Type
Определяет тип объекта, который передается на проверку.
Поддерживаемые значения:
- application/octet-stream – один файл;
- multipart/form-data – несколько файлов;
- text/plain – Docker-образ или несколько Docker-образов, расположенных в определенном репозитории;
- application/json – Docker-образ или несколько Docker-образов, расположенных в определенном репозитории, с указанием дополнительных параметров.
- x-api-key (необязательный)
API-ключ, заданный в переменной окружения KRAS4D_XAPIKEY или переменной xapikey конфигурационного файла.
Возможные ошибки
Если в заголовке Content-Type указано неподдерживаемое значение, приложение вернет ошибку следующего вида:
{
"error"={
"code"="NOT_SUPPORTED_CONTENT_TYPE",
"details"="<content type>",
"message"="Not supported Content-Type"
},
"status"="error"
}
Запрос на проверку файла
Content-Type
application/octet-stream
Тело запроса
Файл.
Пример ответа:
|
Запрос на проверку нескольких файлов
Content-Type
multipart/form-data
Тело запроса
Несколько файлов.
Пример ответа:
|
Запрос на проверку Docker-образов
Content-Type
text/plain
Тело запроса
Ссылка на Docker‑образ или Docker‑образы для проверки.
Возможны следующие значения:
- Путь в репозитории к одному образу (например, https://index.docker.io/jerbi/eicar:latest).
- Маска пути, соответствующая несколькими образам (например, https://index.docker.io/<name mask>:<tag mask> ). Для указания маски можно использовать символы ? и *.
Пример ответа:
|
Возможные ошибки
Для получения списка образов по маске используется запрос с использованием Docker REST API.
Однако на многих публичных серверах эта возможность запрещена по причинам безопасности. Попытка проверки образов по маске на таких серверах приводит к ошибке.
Пример ошибки:
|
Запрос на проверку Docker-образов с дополнительными параметрами
Content-Type
application/json
Тело запроса
JSON следующего вида:
{
"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",
}
}
}
}
Дополнительные параметры запроса
Секция params может содержать следующие параметры:
destination(необязательный параметр) – сервер, на который нужно скопировать проверенный образ.skipimageifexists(необязательный параметр) – не проверять и не копировать образ, если на сервере-приемнике уже есть образ с тем же именем и хеш-суммой SHA256. Этот параметр можно указать только при наличии параметраdestination.custom_callbacks(необязательный параметр) – описываются запросы, которые должны быть отправлены после окончания проверки:- on_detect – запрос отправляется в случае нахождения угрозы.
- on_complete – запрос отправляется всегда по окончании проверки.
В описании тела запроса можно указать переменную подстановки $infected, вместо которой подставляется список зараженный объектов.
Пример ответа:
|
Запрос на получение информации по сессиям проверки (GET)
Назначение
Получение информации о сессиях проверки.
Путь
http://<server>:<port>/scans[?force] – запрос на получение списка сессий
http://<server>:<port>/scans/<уникальный идентификатор сессии проверки>[?force] – запрос на получение информации по конкретной сессии
Параметры
KESL‑контейнер хранит данные о сессиях проверки в памяти, записывая их в базу данных результатов проверок.
Необязательный параметр ?force инициирует чтение информации из базы данных в случае, если несколько экземпляров KESL‑контейнера работают с одной и той же базой данных. В случае отсутствия параметра будет выводиться информация только о тех сессиях, которые были инициированы конкретным экземпляром KESL‑контейнера.
Запрос на получение списка сессий проверки
Путь
http://<server>:<port>/scans[?force]
Пример ответа:
|
Запрос на получение информации по конкретной сессии
Путь
http://<server>:<port>/scans/<уникальный идентификатор сессии проверки>[?force]
Пример ответа:
|
Запрос на добавление сертификата реестра (POST)
Назначение
Добавление сертификата реестра без перезагрузки KESL‑контейнера.
Путь
http://<server>:<port>/addcert
Заголовки запроса
Запрос содержит заголовок Content-Type.
Поддерживаемые значения:
- application/octet-stream – один файл сертификата;
- multipart/form-data – несколько файлов сертификатов.