Плагины

Плагины расширяют Hub, не требуя его пересборки: добавляют сведения к находкам из ваших систем учёта, приносят находки из внешних источников, добавляют каналы уведомлений.

Главное свойство: плагин исполняется в отдельном процессе, а не внутри backend. У него нет прямого доступа к базе данных Hub, и всё общение с внешним миром идёт через фиксированный набор обращений к среде исполнения.

Что умеют плагины

Возможность	Что делает	Пример из поставки
Обогащение находок	Добавляет находке метки по данным внешней системы	Получение сведений об узле из CMDB
Источник находок	Периодически опрашивает внешнюю систему и приносит из неё находки	Сбор узлов и их уязвимостей из системы управления парком устройств
Канал уведомлений	Добавляет способ доставки уведомлений	Отправка в Telegram

Модель изоляции

flowchart TD
    Backend["Backend Hub"]
    Runner["Среда исполнения<br/>отдельный процесс"]
    Plugin["Код плагина"]
    Ext["Внешняя система"]
    DB[("PostgreSQL Hub")]

    Backend --> |"запуск с задачей"| Runner
    Runner --> Plugin
    Plugin --> |"только 4 разрешённых обращения"| Runner
    Runner --> |"HTTP по списку разрешённых узлов"| Ext
    Runner --> |"результат"| Backend
    Backend --> DB
    Plugin -.-> |"прямого доступа нет"| DB

    classDef hub fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#111827
    classDef ext fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,stroke-dasharray:4 3,color:#111827
    classDef store fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#111827
    class Backend,Runner,Plugin hub
    class Ext ext
    class DB store

Плагину доступны ровно четыре обращения к среде исполнения:

Обращение	Назначение
Выполнить HTTP-запрос	Единственный способ обратиться наружу
Получить секрет	Токен доступа к внешней системе
Получить секрет проекта	Тот же механизм, но со значением, заданным для конкретного проекта
Записать сообщение в журнал	Диагностика

Исходящие обращения ограничены:

• по умолчанию запрещены схема http и обращения к локальным и внутренним адресам — это защита от подделки запросов на стороне сервера;
• разрешённые узлы задаются либо в описании плагина, либо через его настройки: если адрес внешней системы вводит администратор, он же и становится разрешённым;
• ослабить ограничения можно переменными PLUGIN_EGRESS_ALLOW_HTTP, PLUGIN_EGRESS_ALLOW_LOCAL_DIAL, PLUGIN_EGRESS_ALLOWLIST — делайте это осознанно.

Секреты плагина хранятся отдельно от его обычных настроек: поля, помеченные как секретные, нельзя записать через обычное сохранение настроек — попытка отклоняется.

Установка

Плагины распространяются как артефакты реестра образов, подписанные ключом издателя. Установка проходит через административный раздел интерфейса:

1. Подключить источник плагинов. Указывается адрес реестра и открытый ключ, которым проверяется подпись. Источников может быть несколько.
2. Просмотреть каталог подключённого источника.
3. Установить плагин. Проверяются подпись и версия: установка более старой версии поверх более новой отклоняется.
4. Заполнить настройки и секреты, затем включить плагин.

Ограничения на источники плагинов и на реестр образов задаются отдельными переменными: PLUGIN_CATALOG_ALLOW_HTTP, PLUGIN_CATALOG_ALLOW_LOCAL_DIAL, PLUGIN_CATALOG_ALLOWLIST — для каталога, PLUGIN_OCI_* — для загрузки самих артефактов.

Изменение набора возможностей при обновлении

Если новая версия плагина заявляет возможности, которых не было у установленной, обновление не применяется молча — требуется явное подтверждение администратора. Так обновление не может незаметно расширить права плагина.

Обогащение находок

Плагин обогащения получает находку и возвращает набор меток. Метки сохраняются у находки и доступны для отбора, поиска и правил маршрутизации.

Запускается двумя способами:

• автоматически — появление находки ставит фоновую задачу обогащения;
• вручную — кнопкой в карточке находки (POST /api/v1/findings/<id>/enrich-tags/<plugin_id>), что удобно для находок, накопленных до установки плагина.

Частота ручного обогащения ограничена переменной ENRICH_TAGS_RATE_LIMIT_PER_MINUTE.

Список доступных плагинов обогащения отдаёт GET /api/v1/plugins/capabilities/finding-enrichers.

Источники находок

Плагин-источник опрашивает внешнюю систему по расписанию и приносит из неё находки. Расписание задаётся в описании плагина и переопределяется при установке; опрос можно запустить вручную — POST /api/v1/admin/installed-plugins/<id>/sync-now.

Принесённые находки проходят тот же путь, что и загруженные извне: та же дедупликация, те же состояния, те же интеграции.

Пустой ответ и удалённые узлы

Плагин-источник обязан сообщать об ошибке, если не смог опросить свою систему. Пустой корректный ответ означает «в системе действительно ноль узлов» — а это, в свою очередь, может привести к массовому закрытию находок как относящихся к исчезнувшим узлам.

Hub дополнительно защищён: если опрос вернул пустой перечень, а сведения об узлах в базе есть, сверка исчезнувших узлов не выполняется. Но это вторая линия обороны, а не замена корректному поведению плагина.

Каналы уведомлений

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

Метод и путь	Назначение
GET /api/v1/projects/<id>/plugin-channels	Доступные каналы проекта
GET /api/v1/projects/<id>/plugin-channels/<plugin_id>/config	Настройки канала
PUT /api/v1/projects/<id>/plugin-channels/<plugin_id>/config	Изменение настроек

Для изменения требуется право manage_notifications. Оно даёт доступ к токенам ботов — выдавайте его так же осторожно, как административные права.

Настройки среды исполнения

Переменная	Назначение
PLUGIN_RUNNER_GLOBAL_LIMIT	Предел одновременно работающих процессов плагинов
PLUGIN_RUNNER_PER_PLUGIN_LIMIT	Предел одновременных запусков одного плагина
PLUGIN_RUNNER_KEEP_WARM_SECONDS	Сколько держать процесс готовым после работы
PLUGIN_FINDING_SOURCE_SYNC_WORKERS	Параллелизм опроса источников
WASM_RUNNER_BINARY_PATH	Путь к исполняемому файлу среды исполнения

Число обработчиков очереди обогащения выводится из PLUGIN_RUNNER_PER_PLUGIN_LIMIT: оно на единицу меньше, чтобы задачи обогащения не занимали все доступные запуски плагина и не блокировали ручной вызов.

Для плагинов, исполняемых как обычные процессы, а не в виртуальной машине, существует отдельная группа настроек с префиксом PLUGIN_NATIVE_ — ограничение памяти, тайм-ауты, политика перезапуска после аварийного завершения и ограничение частоты обращений. Значения по умолчанию рассчитаны на то, что аварийно завершающийся плагин не должен ни перезапускаться бесконечно, ни оставаться выключенным навсегда.

Плагины в поставке

Плагин	Возможность	Что делает
Обогащение из CMDB	Обогащение находок	Подтягивает сведения об узле из системы учёта активов и превращает их в метки
Интеграция с системой управления парком устройств	Источник находок	Периодически забирает узлы и их уязвимости, сопоставляет команды с продуктами
Отправка в Telegram	Канал уведомлений	Доставка уведомлений через бота

Подробности по обогащению из CMDB — в описании самого плагина в каталоге: набор настроек и перечень переносимых полей задаются там и могут отличаться между версиями.