Модуль Playbook

Актуально для Kraken 2.22.4.

Модуль Playbook позволяет создавать и отправлять плейбуки - цепочки событий для проверки корреляций по последовательности. Плейбук состоит из событий: для каждого задаются текст и число повторов, а между отправками можно выдержать паузу.

Быстрый старт

  1. Откройте вкладку Playbook.
  2. Нажмите New Playbook - поля заполнятся значениями по умолчанию: host 127.0.0.1, port 514, Index Test, Event Timeout 0.
  3. В поле Message укажите событие (поддерживаются переменные), в поле Count - количество повторений.
  4. Нажмите Add Element, затем Save - программа запросит имя плейбука и сохранит его в config.db.
  5. Нажмите Check для предпросмотра или Play для отправки.

Интерфейс

Модуль Playbook: плейбук из двух событий (Kraken 2.22.4)

Рис. 1. Модуль Playbook: плейбук из двух событий (Kraken 2.22.4).

Поля

  • Playbook list - список сохранённых плейбуков; кнопка Load загружает выбранный.
  • host - адрес получателя; по умолчанию 127.0.0.1.
  • port - порт получателя, от 1 до 65535; по умолчанию 514.
  • proto - протокол отправки.
  • Index - индекс (используется коннекторами, где он предусмотрен); поддерживает переменные.
  • Count - количество повторений события; минимум 1.
  • Message - текст события; поддерживаются переменные.
  • Event Timeout - пауза в секундах после каждого отправленного события (включая повторы Count); от 0 до 360000, по умолчанию 0.
  • Json - отправка событий в формате JSON.
  • Play Random - собрать все события плейбука и перемешать их перед отправкой.

Кнопки

  • New Playbook - создать новый плейбук и сбросить поля.
  • Add Element - добавить событие в плейбук.
  • Save - сохранить плейбук: настройки отправки и список событий; запрашивает имя плейбука.
  • Play - запустить отправку плейбука в фоне; каждый элемент отправляется Count раз.
  • Check - предпросмотр событий с подставленными переменными без отправки.
  • Copy ID - сохранить плейбук (при необходимости) и скопировать его GUID для запуска через API.
  • Delete - удалить событие из плейбука (кнопка в строке события).
  • Load - загрузить выбранный плейбук из списка.
  • Help - открыть эту страницу документации.

Отдельной кнопки Stop в Playbook нет: запущенный плейбук выполняется до конца.

Как работает отправка

  • Плейбук - последовательность событий; у каждого элемента свои Message и Count.
  • При Play элементы отправляются по порядку; каждый - Count раз.
  • После каждого отправленного события выдерживается пауза Event Timeout секунд (0 - без паузы).
  • Play Random перемешивает события перед отправкой, порядок в этом режиме не сохраняется.
  • Check подставляет переменные и показывает результат без отправки.

Формат плейбука

Плейбук хранится в базе конфигурации config.db, таблица playbook: id (GUID), name (имя плейбука), value (JSON). Если при сохранении имя не задано, используется GUID.

JSON плейбука содержит:

  • host - адрес получателя;
  • port - порт получателя;
  • index - индекс для коннекторов; поддерживает переменные;
  • proto - протокол отправки;
  • json - отправка в формате JSON (true/false);
  • PlayRandom - случайный порядок событий;
  • etimeout - Event Timeout в секундах;
  • playbook - массив событий; у каждого элемента tag (порядковый номер), count (число повторов) и message (текст события).

Числовые значения сохраняются в JSON строками. При сохранении и отправке переводы строк из поля Message удаляются: событие уходит одной строкой.

Пример сохранённого плейбука из двух событий (неудачный вход SSH и HTTP-запрос nginx):

{
  "host": "127.0.0.1",
  "port": "514",
  "index": "Test",
  "proto": "UDP",
  "json": false,
  "PlayRandom": false,
  "etimeout": "1",
  "playbook": [
    {
      "tag": "0",
      "count": "1",
      "message": "{{date1}} {{hostname}} sshd[{{id}}]: Failed password for invalid user admin from {{sIp}} port {{port_low}} ssh2"
    },
    {
      "tag": "1",
      "count": "2",
      "message": "{{date5}} nginx nginx: {{small_localnet}} - - [{{date6}} +0000] \"{{http_method}} {{url}} HTTP/1.1\" {{http_code}} {{id}}"
    }
  ]
}

В этом примере первое событие отправляется один раз, второе - дважды; после каждого отправленного события выдерживается пауза Event Timeout 1 с. Значения переменных подставляются при каждой отправке.

Запуск через API

API позволяет получить список сохранённых плейбуков и запустить плейбук по его GUID. Ключ передаётся в заголовке X-API-KEY; общее описание API - на странице API.

Список плейбуков:

curl -H "X-API-KEY: $API_KEY" http://127.0.0.1:6015/playbook/list

Ответ 200 - строки имя=id, по одной в строке. Если плейбуков нет, тело ответа пустое.

Запуск плейбука по GUID (GUID можно скопировать кнопкой Copy ID):

curl -H "X-API-KEY: $API_KEY" "http://127.0.0.1:6015/play/CCD142CE-0AB5-4492-A9F7-762019803C96"

Запуск выполняется в фоне; тело ответа пустое, результат определяется кодом:

  • 201 - плейбук запущен;
  • 400 - неверный формат GUID: ожидаются шестнадцатеричные символы в верхнем регистре в формате 8-4-4-4-12;
  • 404 - плейбук с таким GUID не найден;
  • 401 - API-ключ отсутствует или неверный;
  • 405 - метод не поддерживается: для запуска используется GET;
  • 429 - превышен лимит запросов (600 в минуту с одного IP-адреса).

Для /playbook/list допустимые коды - 200, 401 и 405. Статус выполнения плейбука через API не возвращается: /messages/state относится к отправке модуля Messages, а не к плейбуку, а доступность API проверяется через /state/live.

Ограничения

  • Event Timeout - от 0 до 360000 секунд, по умолчанию 0.
  • Count - целое число, не меньше 1; порт - от 1 до 65535.
  • Play Random отправляет события в случайном порядке.
  • Запущенный плейбук выполняется в фоне; отдельной кнопки Stop в Playbook нет.
  • API: 600 запросов в минуту с одного IP-адреса; 20 неудачных попыток авторизации за 5 минут блокируют IP-адрес на 15 минут.
  • Статус выполнения плейбука через API не возвращается; /messages/state относится к отправке Messages.

Связанные разделы

Поделиться с друзьями