Документация / Руководство администратора / Интеграции
Системы контроля версий
Интеграция с системой контроля версий (VCS) заводит репозитории ассетами продуктов, запускает сканирование по пушу, переносит уязвимости между ветками при слиянии и выполняет действия quality gate в pull request. Ссылки из уязвимости на строку кода настраиваются отдельно шаблонами ссылок. Интеграции VCS требуют платной лицензии.
Раздел: "Глобальные настройки" → "Интеграции" → "Контроль версий". Создавать и менять интеграции может роль с "Глобальные настройки": "Изменение", импортировать репозитории в продукт - роль с "Продукты": "Изменение".
Что поддержано
| Возможность | GitHub | GitLab | Bitbucket | Azure Repos |
|---|---|---|---|---|
| импорт репозиториев | да | да | да | да |
| сканирование по пушу | да | да | да | да, только Azure DevOps Services |
| перенос уязвимостей при слиянии | да | да | да | нет |
| quality gate: комментарии и закрытие pull request | да | да | да | нет |
| quality gate: статус коммита | да | да | да | нет |
| URL по умолчанию | https://github.com/ |
https://gitlab.com/ |
обязателен | обязателен |
- GitHub - GitHub.com и GitHub Enterprise. Для своего адреса Core обращается к API по
<URL>api/v3. - GitLab - GitLab.com и свой экземпляр.
- Bitbucket - Bitbucket Server и Data Center: Core ждёт их события и REST API.
- Azure Repos - Core принимает только событие пуша. SSH-адрес репозитория он строит в формате Azure DevOps Services:
git@ssh.dev.azure.com:v3/<организация>/<проект>/<репозиторий>.
Подключение
- Откройте "Глобальные настройки" → "Интеграции" → "Контроль версий" и создайте интеграцию.
- Выберите "Система контроля версий".
- Укажите URL системы и токен доступа ("Ввести токен доступа").
- Настройте запуск аудитов и quality gate.
- Сохраните и скопируйте "URL вебхука".
При создании Core проверяет токен запросом к API системы. Ошибка - 400 "Wasn't able to authorize with provided credentials".
| Поле | Что задаёт | По умолчанию |
|---|---|---|
| "Система контроля версий" | GitHub, GitLab, Bitbucket или Azure Repos | GitHub |
| "Название" | имя интеграции | <система> Instance #<номер> |
| "{система} URL" | базовый адрес системы; косую черту в конце Core добавит сам | для GitHub и GitLab - публичные адреса |
| токен доступа | токен для API системы; хранится зашифрованным | - |
| "Проверять SSL сертификат" | проверка TLS при обращении к системе | включено |
| "Автор интеграции" | пользователь Core, от имени которого запускаются аудиты по пушу | пользователь, создавший интеграцию |
| "Включить сканирование при пуше коммита" | запускать аудит на каждый пуш | включено |
| "Применять любые действия только на ветках master/main" | реагировать только на ветки master и main; у pull request проверяется ветка-источник |
выключено |
| "Задержка перед применением любых действий (минуты)" | пауза перед действиями quality gate, от 0 до 10 | 0 |
| "Контроль качества" | quality gate интеграции, не больше одного | - |
| "Токен URL вебхука (UUID v4)" | секрет в адресе вебхука | генерируется |
Нужные права токена форма показывает для выбранной системы. Для GitHub с quality gate: Commit statuses, Contents, Discussions, Issues, Pull requests - чтение и запись, Metadata - чтение. Для одного импорта и сканирования по пушу достаточно чтения репозиториев.
Автор интеграции
Radar отправляет отчёты по аудитам от пуша с API-токеном автора интеграции. Ему нужна роль с "Уязвимости": "Изменение". Удаление автора останавливает сканирование по пушу: Блокировка.
Ошибки обращения к системе интеграция хранит в журнале: последние записи видны в форме, кнопка "Очистить лог" очищает журнал.
Вебхук
Адрес вебхука строится от "Внешнего URL приложения":
https://core.example.ru/api/v1/version-control/<gitlab|github|bitbucket|azure>/webhook/<токен>/
Токен в адресе - единственная аутентификация вебхука. Храните URL как секрет. Чтобы сменить токен, измените "Токен URL вебхука" и обновите адрес в системе.
| Система | Где добавить | События |
|---|---|---|
| GitLab | Settings → Webhooks группы или проекта | Push events, Merge request events |
| GitHub | Settings → Webhooks организации или репозитория, Content type application/json |
Pushes, Pull requests |
| Bitbucket | настройки вебхуков проекта или репозитория | Repository: Push; Pull request: Opened, Source branch updated, Modified, Merged |
| Azure Repos | Service hooks проекта | Code pushed |
Для GitHub выбирайте Content type application/json: событие пуша в другом формате Core отклоняет с ответом "Expecting JSON".
Что происходит по событиям
Пуш
Если включено "Включить сканирование при пуше коммита":
- Core ищет ассет "Репозиторий" с точно таким SSH-адресом репозитория.
- Ассета нет - создаёт его в продукте по умолчанию. Продукта по умолчанию нет - отвечает "Create default product first" и ничего не запускает.
- Создаёт аудит с хешем, автором и веткой коммита.
- Запускает в Radar последовательность джоб ассета или последовательность по умолчанию на ветке пуша.
При включённом "Применять любые действия только на ветках master/main" пуши в другие ветки пропускаются. В GitLab пропускается и пуш, который удаляет ветку.
Для сканирования нужен подключённый Radar и лицензия, которая его открывает: Настройки Radar.
Слияние
Когда pull request или merge request слит, Core переносит уязвимости ветки-источника в целевую ветку. Для Azure Repos перенос не выполняется.
Pull request
Открытие и обновление pull request запускают действия quality gate: комментарий со сводкой и к строкам кода, закрытие pull request, статус коммита. Настройка и логика: Quality gate.
Импорт репозиториев
Кнопка "Импорт репозиториев" в ассетах продукта загружает список репозиториев из интеграции. Подробно: Продукты и ассеты.
- Список сгруппирован по организациям, группам или проектам системы.
- Уже заведённые репозитории отмечены продуктом, в котором они есть.
- Архивные репозитории отмечены.
- Репозитории заводятся ассетами "Репозиторий" с SSH-адресом.
- GitHub отдаёт репозитории организаций пользователя токена, GitLab - проекты групп. Личные репозитории в список не попадают.
Через API: GET /api/v1/version-control/<id>/import/.
Шаблоны ссылок
Шаблон ссылки превращает путь к файлу и строку из уязвимости в ссылку на код в веб-интерфейсе VCS. Раздел: "Глобальные настройки" → "Интеграции" → "Шаблоны ссылок". Нужна роль с "Продукты": "Изменение".
| Поле | Что задаёт | По умолчанию |
|---|---|---|
| "HTTP схема" | HTTP или HTTPS | HTTPS |
| "Шаблон" | адрес страницы файла с переменными | - |
| "Конфигурация по умолчанию" | шаблон для новых репозиториев без своего шаблона; только один | выключено |
Переменные шаблона: ветка, тег или SHA коммита, имя файла, путь к файлу, номер строки, имя продукта, подгруппа. Синтаксис переменных и стандартные шаблоны для GitHub, GitLab и Bitbucket форма показывает в блоках "Доступные переменные в шаблоне:" и "Стандартные шаблоны:".
Шаблон привязывается к ассету "Репозиторий". Новый репозиторий без явного шаблона получает шаблон по умолчанию.
Проверка
- Создайте интеграцию: ошибки при сохранении нет - токен принят.
- Добавьте вебхук в VCS и сделайте тестовый пуш.
- В Core в "Аудиты" появился аудит с хешем коммита, в Radar - пайплайн.
- При ошибке посмотрите журнал ошибок интеграции и ответ на доставку вебхука в VCS.
Ограничения
- Уязвимости и ассеты Core сопоставляет с репозиторием по точному SSH-адресу. Если в ассете адрес записан иначе, пуш создаст новый ассет в продукте по умолчанию.
- У интеграции не больше одного quality gate.
- Для Azure Repos нет переноса уязвимостей при слиянии и действий quality gate.