Официальные плагины: установка и настройка¶

На этой странице — как подключить каталог официальных плагинов, установить из него плагин и что в каждом из них настраивается. Устройство самой платформы, модель изоляции и ограничения описаны отдельно: Плагины.

Каталог официальных плагинов¶

Официальные плагины публикуются издателем в открытом каталоге. Для подключения нужны два значения:

Что	Значение
Адрес каталога	`https://gitlab.com/hub_public/plugins/-/raw/main/catalog.json`
Открытый ключ	`https://gitlab.com/hub_public/plugins/-/raw/main/publickey.txt`

Открытый ключ не является секретом — он проверяет подпись, а не даёт прав. Закрытая половина ключа не покидает сборочный контур издателя, поэтому подменить содержимое каталога, сохранив верную подпись, нельзя.

Сами артефакты плагинов лежат в открытом реестре образов registry.gitlab.com/hub_public/plugins; исходный код плагинов туда не публикуется.

В каталоге тринадцать плагинов: три обогатителя, источник инвентаря, шесть каналов уведомлений и три провайдера задач. Устройство каждого вида — в Плагинах.

Ключ вводится один раз и осознанно

Каталог, зарегистрированный без открытого ключа, считается неподписанным: подпись у устанавливаемых из него плагинов не проверяется. Это допустимо для вашего внутреннего каталога, который вы сами и наполняете, но для официального каталога ключ указывать обязательно — иначе теряется весь смысл подписи.

Шаг 1. Подключить каталог¶

С версии 0.33 источник уже подключён

Официальный каталог hub-official заводится при обновлении и виден в списке источников сразу — регистрировать его руками больше не нужно. Разделы ниже нужны, если вы поднимаете своё зеркало, работаете в закрытом контуре или удалили предустановленную запись.

Что предустановка не делает: разрешение на нативные плагины остаётся выключенным (см. следующий раздел) — это решение оператора, а не наше.

Инсталляции, зарегистрировавшие тот же каталог раньше, дубля не получат: запись добавляется, только если источника с таким адресом ещё нет.

Через интерфейс¶

Административный раздел → Плагины (/admin/plugins-management) → вкладка источников → Добавить. Заполните имя, адрес каталога и открытый ключ из таблицы выше.

Через API¶

curl -X POST https://hub.example.com/api/v1/admin/plugin-marketplaces \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hub-official",
    "catalog_url": "https://gitlab.com/hub_public/plugins/-/raw/main/catalog.json",
    "public_key": "AKT8z1ROWc2/V/ZC1sktlTVR2x8Lqei16D5BPTlYn3U=",
    "is_active": true
  }'

Обязательны name и catalog_url. В ответе открытого ключа нет — он не возвращается ни одной ручкой, чтобы значение нельзя было прочитать обратно и перепутать с секретом.

У источника, которому уже разрешено исполнение вне песочницы, ключ сменить нельзя: иначе подменой ключа можно было бы переназначить доверие у разрешённого источника. Сначала снимите разрешение, потом меняйте ключ.

Закрытый контур

В сети без выхода наружу выложите catalog.json, publickey.txt и сами артефакты на внутреннее зеркало и укажите его адрес. Формат каталога и порядок установки при этом не меняются. Если зеркало отдаёт HTTP или отвечает по внутреннему адресу, потребуются PLUGIN_CATALOG_ALLOW_HTTP и PLUGIN_CATALOG_ALLOW_LOCAL_DIAL — см. Плагины. Включайте их вместе с PLUGIN_CATALOG_ALLOWLIST, а не по отдельности: второй флаг снимает защиту от обращений во внутреннюю сеть по адресу каталога.

Каналы уведомлений требуют отдельного разрешения¶

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

Разрешение выдаётся после добавления источника: откройте его управление и включите «разрешить исполнение вне песочницы». Интерфейс попросит подтверждение — это не формальность: плагин получает те же права, что процесс Hub, тогда как обычный плагин ограничен средой исполнения.

Обратное выключение подтверждения не требует.

Через API — тем же обновлением источника:

curl -X PUT https://hub.example.com/api/v1/admin/plugin-marketplaces/<id> \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allows_native": true}'

При создании источника это поле не принимается

allows_native задаётся только обновлением, и это не описка API: разрешение отделено от заведения намеренно, чтобы оно не проскочило вместе с остальными полями. Источник без него выглядит настроенным, а каналы уведомлений из него не ставятся.

Второе условие — источник обязан быть подписанным: без открытого ключа разрешение не действует.

Шаг 2. Установить плагин¶

Через интерфейс¶

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

Через API¶

curl -X POST https://hub.example.com/api/v1/admin/installed-plugins \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "marketplace",
    "marketplace_id": "<id источника из шага 1>",
    "catalog_plugin_id": "jira-ticketing"
  }'

Поле runtime не задано, поэтому подставляется wasm. Для каналов уведомлений его нужно указать явно — "runtime": "native", — и источник при этом обязан нести разрешение из предыдущего раздела.

Установка из файла идёт другим маршрутом: у неё два файла (модуль и описание), то есть multipart, а не JSON — POST /api/v1/admin/installed-plugins/sideload. Запрос с source_type: sideload на маршрут выше отвергается с ошибкой, а не выполняется наполовину.

Шаг 3. Заполнить настройки¶

Настройки плагина заполняются в его карточке (Настроить) либо через PUT /api/v1/admin/installed-plugins/<id>. Поля, помеченные как секретные, хранятся отдельно от остальной конфигурации и обратно не отдаются: пустое значение при сохранении означает «не менять», а не «стереть».

После заполнения плагин нужно включить — установка сама по себе его не запускает.

У тикетинга настройки ещё и попроектные

Плагины заведения задач читают конфигурацию установки как основу, а поверх неё — настройки конкретного проекта (правка проекта → раздел учёта задач). Так один установленный плагин обслуживает несколько проектов с разными досками, ключами и шаблонами. Секрет при этом тоже попроектный.

Что есть в каталоге¶

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

`metabase-cmdb` — теги из CMDB¶

Подтягивает сведения об узле (владелец, окружение, роль сервера) из таблицы Metabase по IP-адресу находки и превращает их в теги.

Настройка	Обяз.	Назначение
`metabase_base_url`	да	Адрес Metabase
`database_id`	да	Идентификатор базы в Metabase
`servers_table_id`	да	Идентификатор таблицы с узлами
`column_to_tag_key`		Соответствие «колонка таблицы → имя тега»
`api_token`		Токен Metabase (секрет)

Запускается автоматически при появлении находки и кнопкой в карточке — второе нужно для находок, накопленных до установки плагина.

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

`fleetdm` — узлы и их уязвимости из FleetDM¶

Периодически забирает из FleetDM хосты вместе с уязвимостями и заводит по ним находки. Умеет сопоставлять команды FleetDM с продуктами Hub.

Настройка	Обяз.	Назначение
`fleet_base_url`	да	Адрес FleetDM
`target_project_id`	да	Проект Hub, в который попадают находки
`fleet_edition`		Редакция FleetDM; для Premium доступно сопоставление команд с продуктами
`default_product_name`		Продукт для хостов без команды
`stale_host_ignore`		Пропускать хосты, давно не выходившие на связь
`cve_severity_max_lookups`		Потолок обращений за критичностью CVE за один проход
`cve_severity_budget_seconds`		Потолок времени на те же обращения
`api_token`		Токен FleetDM (секрет)

Расписание опроса задаётся при установке; опрос можно запустить и вручную.

Требует Hub 0.33 или новее

Версия 1.0.8 объявляет hub_version: >=0.33. На более старом Hub она не установится — это защита, а не ошибка: плагин пользуется возможностями, которых там нет.

Заведение задач¶

Все три плагина этой группы дают один и тот же набор операций: создать задачу, создать одну задачу на группу находок, добавить комментарий, перевести по статусу, прочитать статус, собрать ссылку, разобрать вебхук, найти задачу по метке, отдать список целей.

`jira-ticketing` — задачи в Jira¶

Настройка	Обяз.	Назначение
`base_url`	да	Адрес Jira
`project_key`	да	Ключ проекта по умолчанию
`auth_method`		Способ входа: по паре «почта + токен» либо OAuth
`email`, `api_token`		Пара для базового способа (второе — секрет)
`client_id`, `client_secret`		Пара для OAuth (второе — секрет)
`issue_type`, `issuetype_id`		Тип задачи
`issuetype_by_engine`		Тип задачи в зависимости от сканера
`projects`		Курируемый список целей, из которого выбирает оператор
`labels`, `priority_id`		Метки и приоритет создаваемой задачи
`summary_template`, `description_template`		Шаблоны заголовка и описания
`partial_*`		Те же шаблоны для полуручного режима
`extra_fields`, `extra_params`, `value_maps`		Дополнительные поля Jira и их соответствия
`transition_fields`		Поля, требуемые при переводе по статусу

`github-issues-ticketing` — issue в GitHub¶

Настройка	Обяз.	Назначение
`owner`	да	Владелец репозитория
`repo`	да	Репозиторий
`token`	да	Токен доступа (секрет)
`api_base_url`		Адрес API — для GitHub Enterprise
`html_base_url`		Адрес веб-интерфейса — для GitHub Enterprise
`labels`		Метки создаваемого issue

`trello-ticketing` — карточки в Trello¶

Настройка	Обяз.	Назначение
`board_id`	да	Идентификатор доски
`list_name`	да	Список на доске, куда попадают карточки
`api_key`	да	Ключ приложения (секрет)
`api_token`	да	Токен пользователя (секрет)
`labels`		Метки карточки
`summary_template`, `description_template`		Шаблоны заголовка и описания
`api_base_url`		Адрес API

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

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

Плагин	Канал	Куда обращается
`telegram-notifier`	Telegram	`api.telegram.org`
`slack-notifier`	Slack	`hooks.slack.com`
`teams-notifier`	Microsoft Teams	`webhook.office.com`
`maxru-notifier`	MAX	`botapi.max.ru`
`mattermost-notifier`	Mattermost	ваш сервер — см. ниже
`email-notifier`	Электронная почта	ваш SMTP-сервер

Общие настройки проекта у всех каналов одинаковы:

Настройка	Назначение
`enabled`	Включить доставку в этот проект
`min_severity`	Порог критичности для новых находок
`notify_on_close`	Сообщать о закрытии находок
`fixed_min_severity`	Порог для сводки об исправленном

Сверх них у каждого канала свои поля адресации:

Плагин	Поля проекта
`telegram-notifier`	`chat_id`, `bot_token` (секрет)
`slack-notifier`, `teams-notifier`	`webhook_url` (секрет)
`mattermost-notifier`	`webhook_url` (секрет), `channel`
`maxru-notifier`	`chat_id`, `access_token` (секрет), `base_url`
`email-notifier`	`recipients`, `subject_prefix`, при необходимости — свой SMTP

Mattermost: адрес сервера задаётся один раз на установку¶

Остальным каналам адрес известен заранее и записан в подписанном описании плагина. Mattermost вы размещаете у себя, поэтому его адрес называете вы — в настройках установки плагина:

Настройка	Значение
`mattermost_base_url`	`https://mattermost.example.com` — адрес сервера целиком, без пути к webhook

Без него установка и настройка проходят, а доставка отклоняется. Нужна версия плагина 1.0.1 и новее.

Переменная PLUGIN_EGRESS_ALLOWLIST для этого не подходит

Название похоже, но это другой слой защиты — про обращения внутрь сети. Перечень адресов, разрешённых плагину, он не расширяет.

Электронная почта: SMTP на установку или на проект¶

email-notifier отправляет письма средствами Hub, а не собственным соединением. SMTP задаётся на уровне установки:

Настройка	Назначение
`smtp_host`, `smtp_port`	Сервер отправки
`smtp_username`, `smtp_password`	Учётные данные (пароль — секрет)
`smtp_from`	Адрес отправителя
`smtp_tls_mode`	Режим шифрования
`allow_project_smtp`	Разрешить проектам задавать свой SMTP
`smtp_allowed_hosts`	Перечень серверов, допустимых для проектов

Проект может переопределить SMTP только при allow_project_smtp: true. Перечень smtp_allowed_hosts действует только если он задан: пустой означает, что проекту разрешён любой сервер. Заполняйте его — иначе право настраивать проект становится способом отправлять почту откуда угодно от имени Hub.

Двойной доставки не бывает

Если плагин канала установлен и включён, доставку ведёт он. Встроенных путей для Telegram, Mattermost, MAX, Slack и Teams в 0.33 не осталось вовсе, поэтому продублировать сообщение нечем.

Обновление и удаление¶

Обновить до последней версии — кнопка в карточке плагина. Подпись проверяется заново.
Поставить конкретную версию или откатиться — выбор версии в панели подробностей: запись каталога несёт всю историю. Понижение требует подтверждения — более старая версия могла быть отозвана из-за уязвимости, и защита от отката для неё снимается. У записи без истории выбор не показывается.
Выключить — плагин остаётся установленным вместе с настройками, но не запускается.
Удалить — снимает установку.

Обновление не расширяет права молча

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

Если что-то не работает¶

Признак	Куда смотреть
Каталог не открывается	Доступность адреса из пода Hub; в закрытом контуре — `PLUGIN_CATALOG_ALLOW_HTTP` и `PLUGIN_CATALOG_ALLOW_LOCAL_DIAL`
Установка отклонена по подписи	Открытый ключ источника; он должен быть ключом того же издателя, что подписал плагин
Установка отклонена по версии	Установка более старой версии поверх более новой запрещена намеренно
Плагин установлен, но ничего не делает	Включён ли он; заполнены ли обязательные настройки; для тикетинга — привязан ли к проекту
Обращения плагина наружу не проходят	Список разрешённых адресов плагина; см. Плагины

Официальные плагины: установка и настройка¶

Каталог официальных плагинов¶

Шаг 1. Подключить каталог¶

Через интерфейс¶

Через API¶

Каналы уведомлений требуют отдельного разрешения¶

Шаг 2. Установить плагин¶

Через интерфейс¶

Через API¶

Шаг 3. Заполнить настройки¶

Что есть в каталоге¶

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

metabase-cmdb — теги из CMDB¶

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

fleetdm — узлы и их уязвимости из FleetDM¶

Заведение задач¶

jira-ticketing — задачи в Jira¶

github-issues-ticketing — issue в GitHub¶

trello-ticketing — карточки в Trello¶

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

Mattermost: адрес сервера задаётся один раз на установку¶

Электронная почта: SMTP на установку или на проект¶

Обновление и удаление¶

Если что-то не работает¶

`metabase-cmdb` — теги из CMDB¶

`fleetdm` — узлы и их уязвимости из FleetDM¶

`jira-ticketing` — задачи в Jira¶

`github-issues-ticketing` — issue в GitHub¶

`trello-ticketing` — карточки в Trello¶