REST API¶

Полный и всегда актуальный справочник по API доступен в самом развёрнутом экземпляре Hub:

https://<адрес-вашего-hub>/swagger/index.html

Там описаны все эндпоинты — их около 190, включая административные. Эта страница описывает только те, что нужны для внешних интеграций, и общие правила работы с API.

Общие правила¶

Базовый путь — /api/v1. Все примеры ниже приводятся относительно него.

Формат — JSON. Имена полей в теле запросов и ответов записываются строчными буквами через подчёркивание (product_id, created_at).

Успешный ответ оборачивается в поле data:

{ "data": { "id": "…", "name": "…" } }

Ошибка возвращается в поле error. Текст сообщения локализован: язык выбирается по заголовку Accept-Language, поддерживаются русский и английский.

Время — во всех полях в UTC, в формате RFC 3339 с признаком Z.

Аутентификация¶

Есть два способа, и путать их нельзя.

Кто обращается	Заголовок	Примечание
Пользователь или внешнее приложение с токеном	`Authorization: Bearer <токен>`	Значение проверяется как JWT
Сервисная учётная запись	`X-API-Key: <ключ>`	Также принимается `Authorization: ApiKey <ключ>`

Ключ сервисной учётной записи и Bearer несовместимы

Ключ вида sa_…, переданный как Authorization: Bearer sa_…, будет разобран как JWT, не пройдёт проверку и вернёт 401. Для ключей используйте X-API-Key.

Ключ имеет вид sa_<8 шестнадцатеричных символов>_<секрет>. В базе хранится только хеш ключа и его начало — по началу можно понять, какой именно ключ использовался, но восстановить сам ключ нельзя. Полное значение показывается один раз при создании.

Ограничение частоты¶

Что	Значение по умолчанию	Переменная
Обычные эндпоинты	100 запросов в минуту	`RATE_LIMIT_API`
Эндпоинты входа	10 запросов в минуту	`RATE_LIMIT_AUTH`

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

Коды ответов¶

Код	Когда
`200`	Успех
`201`	Объект создан
`202`	Принято в обработку; результат появится позже
`400`	Некорректный запрос: неверное поле, недопустимое расширение файла
`401`	Нет аутентификации, ключ неверен, истёк или отозван
`403`	Аутентификация есть, прав на этот объект нет
`404`	Объект не найден либо возможность выключена
`409`	Конфликт: объект уже существует
`413`	Тело запроса больше допустимого
`422`	Запрос корректен, но выполнить его нельзя в текущем состоянии
`429`	Превышена частота запросов
`503`	Очередь задач недоступна

Загрузка отчёта сканера¶

Основной эндпоинт интеграции с системой сборки.

POST /api/v1/products/<product_id>/reports
X-API-Key: <ключ>
Content-Type: multipart/form-data

Поля формы:

Поле	Тип	Обязательное	Назначение
`file`	файл	да	Отчёт. Расширение только `.sarif` или `.json`; архивы не принимаются
`format`	строка	нет	`sarif` либо `sonarqube`. Если не указан — определяется по содержимому
`engine`	строка	нет	Имя сканера, если в отчёте его нет
`engine_version`	строка	нет	Версия сканера
`commit_id`	строка	нет	Идентификатор ревизии
`verify_fixes`	булево	нет	Пометить отчёт как пригодный для автоматического закрытия исправленных находок

Заголовок X-Commit-Id — альтернатива полю commit_id.

Ответ — 202 Accepted:

{
  "data": {
    "message": "Report queued for processing",
    "report_id": "…",
    "job_id": 12345
  }
}

Обработка асинхронная

Код 202 означает «отчёт принят и поставлен в очередь», а не «отчёт разобран». Счётчиков найденного в ответе нет. Ошибки разбора возникают позже: узнать итог можно, запросив состояние отчёта по GET /api/v1/reports/<report_id> — оно перейдёт из pending в completed либо в failed.

Пример:

curl -X POST "https://hub.example.com/api/v1/products/$PRODUCT_ID/reports" \
  -H "X-API-Key: $HUB_API_KEY" \
  -H "X-Commit-Id: $(git rev-parse HEAD)" \
  -F "file=@scan.sarif"

Подробности и примеры для систем сборки: Загрузка SARIF.

Поиск продукта по репозиторию¶

Позволяет заданию сборки не хранить идентификатор продукта, а находить его по адресу репозитория.

GET /api/v1/products/lookup?repository_url=<адрес>
X-API-Key: <ключ>

Требует права list_products.

Чтение находок¶

GET /api/v1/products/<product_id>/findings

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

Требует права read_findings.

Периметр сканирования¶

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

Метод и путь	Назначение
`GET /projects/<id>/scope/export`	Выгрузка периметра для сканера
`GET /projects/<id>/scope`	Просмотр записей периметра
`POST /projects/<id>/scope/entries`	Добавление записи
`POST /projects/<id>/scope/proposals`	Предложение добавить обнаруженный объект
`GET /projects/<id>/scope/proposals`	Список предложений, ожидающих решения
`POST /projects/<id>/scope/import/netbox`	Импорт из NetBox

Предложение не расширяет периметр само по себе — его подтверждает администратор. Требуется право manage_scope.

Ручная перепроверка¶

POST /api/v1/projects/<id>/rescan
POST /api/v1/findings/<id>/rescan?via=scanner|llm

Доступны только при включённом признаке ручной перепроверки; иначе — 404. Подробнее: Ручная перепроверка.

Приём обратных вызовов¶

Метод и путь	Кто вызывает
`POST /api/v1/scanner-callbacks/verify-finding`	Сканер — с результатом перепроверки находки
`POST /api/v1/webhooks/jira/<project_id>/<секрет>`	Jira — при изменении задачи

Обратный вызов сканера проверяется ключом и подписью тела; поддерживается окно смены ключа, когда действительны сразу два. Адрес приёма уведомлений от Jira содержит секрет в пути, и его можно перевыпустить через POST /projects/<id>/jira/webhook/rotate.

Состояние фоновых задач¶

Метод и путь	Назначение
`GET /api/v1/jobs`	Список фоновых задач
`GET /api/v1/jobs/stats`	Сводка по состояниям
`GET /api/v1/jobs/<id>`	Одна задача
`POST /api/v1/jobs/<id>/retry`	Повторить
`POST /api/v1/jobs/<id>/cancel`	Отменить

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

Нарушения сроков¶

Метод и путь	Назначение
`GET /api/v1/sla/violations`	Открытые нарушения сроков
`POST /api/v1/sla/violations/<id>/resolve`	Закрыть нарушение
`GET /api/v1/dashboard/sla-compliance`	Сводка соблюдения сроков
`GET /api/v1/dashboard/sla-trend`	Динамика

Метрики для систем мониторинга¶

Метод и путь	Назначение
`GET /api/v1/grafana/projects/stats`	Показатели по проектам
`GET /api/v1/grafana/products/stats`	Показатели по продуктам
`GET /api/v1/grafana/sla/metrics`	Показатели по срокам

Требуют права read_metrics, которое выдаётся только на общем уровне.

Вход и токены¶

Метод и путь	Назначение
`GET /api/v1/auth/config`	Режим входа и список провайдеров с адресами кнопок
`GET /api/v1/auth/sso/<provider>/login`	Начало входа через провайдера
`GET /api/v1/auth/sso/<provider>/callback`	Возврат от провайдера
`POST /api/v1/auth/local/login`	Вход по логину и паролю
`POST /api/v1/auth/token/refresh`	Обновление токена доступа
`POST /api/v1/auth/logout`	Выход с отзывом всех токенов обновления
`GET /api/v1/auth/me`	Текущий пользователь и его права

Обновление токена выполняется без тела запроса: токен обновления читается из защищённой cookie и там же обновляется. Сохранены прежние адреса /auth/keycloak/login и /auth/keycloak/callback — они работают как синонимы для провайдера keycloak.

Права сервисных учётных записей¶

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

Право	Что разрешает	Уровни
`upload_report`	Загружать отчёты	проект, продукт, общий
`read_findings`	Читать находки	проект, продукт, общий
`read_reports`	Читать загруженные отчёты	проект, продукт
`list_products`	Искать продукты по адресу репозитория	проект, общий
`create_project`	Создавать проекты	общий
`create_product`	Создавать продукты	проект, общий
`update_product`	Изменять свойства продукта	проект, продукт, общий
`delete_product`	Удалять продукт	проект, продукт, общий
`read_metrics`	Читать показатели	общий
`manage_scope`	Управлять периметром	проект
`manage_notifications`	Управлять настройками каналов уведомлений	проект

Выдача права с несовместимым уровнем отклоняется с кодом 400. Права delete_product и manage_notifications дают доступ к разрушительным действиям и к секретам каналов — выдавайте их осознанно.

Версия¶

GET /version
GET /api/v1/version

Возвращают версию компонента. Используются интерфейсом для сверки версий и удобны как признак работоспособности после обновления.