Актуально для Kraken 2.22.4.
API Kraken Stress Testing Toolkit предназначено для удалённого управления генератором событий и получения статистики. API работает по HTTP и использует GET-запросы; параметры передаются в query-строке.
- Быстрый старт
- Базовый URL
- Аутентификация
- Формат запросов и ответов
- Коды ответов
- Ограничения
- Журналирование
- Эндпоинты
- Состояние и версия
- GET /state/live
- GET /version/build
- GET /version/app
- GET /v2/statistics
- Плейбуки
- GET /play/{id}
- GET /playbook/list
- Messages: управление отправкой
- GET /messages/start
- GET /messages/stop
- GET /messages/eps
- GET /messages/avg
- GET /messages/sent
- GET /messages/time
- GET /messages/state
- GET /messages/set
- GET /messages/clear и /messages/disable
- GET /messages/add
- Профили Messages
- Sender: одиночные события
- GET /sender/start
- Templates: шаблоны
- GET /templates/list
- POST /templates/add
- Настройки: отладка
- GET /set/settings
- Версионирование
- История изменений
- Связанные разделы
Быстрый старт
- Включите API в разделе Settings → API и при необходимости измените порт (по умолчанию 6015). После смены порта перезапустите API или приложение.
- Скопируйте значение поля API KEY - оно уникально для каждой установки.
- Проверьте доступность API запросом к
/state/live.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/state/live |
Код 200 означает, что API доступен. Если вернулся 401, проверьте ключ; если 502 - ключ не задан на сервере.
Базовый URL
Базовый адрес API: http://<host>:<port>, по умолчанию http://127.0.0.1:6015. API слушает HTTP без TLS - если нужен защищённый канал, используйте SSH-туннель, VPN или обратный прокси с TLS.
Смена порта выполняется в Settings → API. После изменения порта API нужно перезапустить.
Аутентификация
Для авторизации используется HTTP-заголовок X-API-KEY. Передача ключа в query-строке (?X-API-KEY=..., ?key=..., ?api_key=...) не поддерживается - такой запрос вернёт 401.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/state/live |
Ключ генерируется автоматически при первом запуске, уникален для каждой установки и хранится в config.db в зашифрованном виде (DPAPI). Ключ отображается в Settings → API; кнопка Re-create создаёт новый ключ. Старые статические ключи из предыдущих версий недействительны.
Формат запросов и ответов
- Большинство команд выполняется методом
GET; параметры передаются в query-строке и должны быть URL-кодированы. - Исключение -
POST /templates/add: параметры передаются в телеapplication/x-www-form-urlencoded; GET с теми же параметрами сохранён для обратной совместимости. - Для остальных команд тело запроса не используется.
- Длина GET-запроса ограничена request-line (около 16 КиБ); большие шаблоны добавляйте через POST.
- Для большинства команд тело ответа пустое, а результат определяется HTTP-кодом.
- Команды чтения возвращают простой текст: число, строку или список (по одному значению в строке).
- JSON возвращает только
/v2/statistics- см. раздел API v2.
Коды ответов
200- запрос успешно выполнен.201- задача запущена (/play/...,/templates/add).400- ошибка в параметрах запроса.401- неверный или отсутствующий API-ключ.403- недопустимое имя или путь (Path Traversal).404- плейбук или элемент не найден.405- метод не поддерживается для этого маршрута; допустимыGETиPOST. Для/templates/addиспользуйтеPOST.413- слишком большое тело запроса или шаблона: тело POST больше 1 МиБ илиmessageбольше 256 КиБ.423- операция недоступна в текущем состоянии: отправка уже запущена или ещё не запущена, либо профиль/правило нельзя изменить во время отправки.429- превышен лимит запросов; см. заголовокRetry-After.500- внутренняя ошибка сервера.502- API-ключ не настроен на сервере.
Ограничения
- 600 запросов в минуту с одного IP-адреса.
- 20 неудачных попыток авторизации за 5 минут - блокировка IP на 15 минут.
- Метод
/templates/add- 10 запросов в минуту; тело POST-запроса - до 1 МиБ, длина GET-запроса - до ~16 КиБ. - Тело шаблона (параметр
message) - не более 262 144 байт UTF-8 (256 КиБ). - Имя шаблона - не более 64 символов; имя профиля - не более 128 символов.
При превышении лимита возвращается 429 и заголовок Retry-After с количеством секунд до снятия блокировки.
Журналирование
Каждый запрос пишется в access-лог logs\access_ГГГГММДД.log в формате nginx combined:
| 1 | IP - - [дата] "МЕТОД URI HTTP/версия" КОД РАЗМЕР "Referer" "User-Agent" |
Значение API-ключа в журнал не записывается. Служебные предупреждения (неудачная авторизация, превышение лимитов, блокировка) пишутся в основной лог.
Эндпоинты
Все команды ниже вызываются методом GET с заголовком X-API-KEY; исключение - POST /templates/add.
Состояние и версия
GET /state/live
Проверка доступности API. Возвращает 200, если сервер запущен.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/state/live |
Тело ответа пустое: успех определяется кодом 200.
GET /version/build
Возвращает номер сборки в виде простого текста.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/version/build |
Пример ответа: 490 (номер зависит от сборки 2.22.4.490).
GET /version/app
Возвращает версию приложения в виде простого текста.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/version/app |
Пример ответа: 2.22.4.
GET /v2/statistics
Возвращает текущую статистику в JSON. Описание полей - на странице API v2.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/v2/statistics |
Плейбуки
GET /play/{id}
Запускает плейбук по идентификатору. Параметр пути id - UUID плейбука.
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/play/CCD142CE-0AB5-4492-A9F7-762019803C96" |
201- плейбук запущен.400- идентификатор не является UUID.404- плейбук не найден.
Тело ответа пустое: успех определяется кодом 201.
GET /playbook/list
Возвращает список плейбуков в виде строк имя=id.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/playbook/list |
| 1 | My Playbook=CCD142CE-0AB5-4492-A9F7-762019803C96 |
Messages: управление отправкой
GET /messages/start
Запускает отправку событий с текущим профилем. Необязательные параметры:
eps- количество событий в секунду;stoptime- время работы в секундах;stopcount- остановка после указанного количества событий.
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/messages/start?eps=1000&stoptime=3600&stopcount=100000" |
Тело ответа пустое: успех определяется кодом 200.
200- отправка запущена.400- неверное значениеeps.423- отправка уже запущена.
GET /messages/stop
Останавливает отправку событий.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/stop |
Тело ответа пустое: успех определяется кодом 200.
200- отправка остановлена.423- отправка не запущена.
GET /messages/eps
Текущее количество событий в секунду.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/eps |
| 1 | 19075 |
GET /messages/avg
Средний EPS за период.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/avg |
| 1 | 27032.0 |
GET /messages/sent
Количество отправленных событий.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/sent |
| 1 | 162192 |
GET /messages/time
Время работы отправки в секундах.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/time |
| 1 | 3600 |
GET /messages/state
Состояние отправки: active, если отправка идёт, и stop, если остановлена.
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/state |
| 1 | active |
GET /messages/set
Изменяет параметры отправки без запуска и остановки. Параметры:
eps- новое значение EPS;stoptime- время работы в секундах;stopcount- количество событий до остановки;timeout- пауза между отправками;randomtimeout- случайная пауза (true/false).
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/messages/set?eps=100&stoptime=5&stopcount=1000&timeout=1&randomtimeout=true" |
Тело ответа пустое: успех определяется кодом 200.
200- параметры применены.400- неверное значениеeps.423- отправка уже запущена.
GET /messages/clear и /messages/disable
/messages/clear удаляет все правила отправки, /messages/disable отключает их без удаления.
| 1 2 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/clear curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/messages/disable |
Тело ответа пустое: успех определяется кодом 200.
GET /messages/add
Добавляет правило отправки. Параметры:
proto- протокол; по умолчаниюUDP;port- порт; по умолчанию514;host- хост; по умолчанию127.0.0.1;template- имя шаблона;json- отправка в JSON (true/false), по умолчаниюfalse.
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/messages/add?template=nginx&host=10.0.0.10&port=514&proto=UDP&json=false" |
Тело ответа пустое: успех определяется кодом 200.
200- правило добавлено.400- неверный протокол, порт или хост.403- недопустимое имя шаблона (Path Traversal).
Профили Messages
/profiles/list возвращает список имён профилей (по одному в строке).
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/profiles/list |
| 1 2 | default test |
/profiles/save, /profiles/load и /profiles/delete управляют профилем по имени:
| 1 2 3 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/profiles/save?name=test" curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/profiles/load?name=test" curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/profiles/delete?name=test" |
Тело ответа пустое: успех определяется кодом 200.
- Параметр
nameобязателен, до 128 символов. 400- имя отсутствует или недопустимо.423- отправка запущена; операции с профилями недоступны.
Sender: одиночные события
GET /sender/start
Отправляет одно событие. Параметры:
message- сообщение; обязательный параметр;host- хост;port- порт;proto- протокол;index- значение индекса в шаблоне;json- отправка в JSON (true/false).
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/sender/start?message=hello&host=10.0.0.10&port=514&proto=UDP&index=test&json=false" |
Тело ответа пустое: успех определяется кодом 200.
200- событие отправлено.400- отсутствуетmessageили неверный хост/порт.
Templates: шаблоны
GET /templates/list
Возвращает список имён шаблонов (по одному в строке).
| 1 | curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/templates/list |
| 1 2 3 | Nginx JSON Demo Suricata |
POST /templates/add
Добавляет событие в шаблон. Предпочтительный метод - POST с телом application/x-www-form-urlencoded. Для обратной совместимости поддерживается и GET с теми же параметрами в query-строке, но GET ограничен длиной request-line (~16 КиБ).
Параметры (в теле POST или в query GET):
name- имя шаблона; обязательно, до 64 символов;message- событие; обязательно, до 262 144 байт UTF-8 (256 КиБ);index- индекс в шаблоне (необязательно).
Пример POST:
| 1 | curl -X POST -H "X-API-KEY: $API_KEY" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "name=Test" --data-urlencode "message=hello" --data-urlencode "index=test" http://127.0.0.1:6015/templates/add |
Пример GET (для коротких событий):
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/templates/add?name=Test&message=hello&index=test" |
Тело ответа пустое; результат определяется HTTP-кодом.
201- событие добавлено.400- отсутствуют или недопустимыname/message.403- недопустимое имя (Path Traversal).413- тело POST больше 1 МиБ (проверяется до чтения тела) илиmessageбольше 262 144 байт UTF-8.429- превышен лимит 10 запросов в минуту.
Ограничения: тело POST - до 1 МиБ; message - до 262 144 байт UTF-8; GET request-line - около 16 КиБ, поэтому большие шаблоны добавляйте через POST.
Настройки: отладка
GET /set/settings
Переключает уровень логирования: ?debug=true устанавливает уровень Debug, ?debug=false возвращает Warn. Это не флаг, а выбор уровня; подробнее - на странице Уровни логирования.
| 1 | curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/set/settings?debug=true" |
Тело ответа пустое: успех определяется кодом 200.
Версионирование
Версия API входит в путь: команды с префиксом /v2/ относятся к API v2 (см. API v2), команды без префикса - к API v1. Существующие методы и поля не удаляются без предупреждения: изменения публикуются в разделе обновлений.
История изменений
История изменений API публикуется в новостях сайта. Формат записи: версия, дата, категории "Добавлено / Изменено / Исправлено / Безопасность". При обновлении проверяйте:
- способ передачи ключа - только заголовок
X-API-KEY; - лимиты запросов и размеры шаблонов;
- формат ответа
/v2/statistics; - коды ответов
403,413,423,429,502.
Связанные разделы
- API v2
- Модуль Settings - включение API и ключ
- Модуль Templates
- Переменные