Версия: v1.1.x

CI/CD

Шерлок поддерживает возможность загрузки результатов сканирования, получаемых из CI-конвейера. Для этого используется утилита sher-cli, образ с которой поставляется вместе с дистрибутивом.

Возможности `sher-cli`

CLI-утилита sher-cli позволяет загружать результаты сканирования в Шерлока и проверять сборку на соответствие требованиям Security Gate.

Команды и глобальные флаги

sher-cli поддерживает следующие команды и глобальные флаги:

upload — команда для отправки отчётов с результатами сканирований в Шерлока;
sg — команда для проверки соответствия требованиям Security Gate;
-h, --help — предоставление справки по любой команде;
--sherlock-url — URL сервера, на котором развёрнут Шерлок;
--sherlock-token — токен для аутентификации в Шерлоке;

к сведению
Процесс создания токена, используемого для аутентификации запросов из CI в Шерлоке, описан в соответствующем разделе.
--skip-ssl-verify - проверка SSL. По умолчанию установлено в значение 'false'.

Флаги команды `upload`

Команда shercli upload обладает следующими флагами:

--asset-id — уникальный идентификатор актива. Для репозиториев Шерлок попробует найти значение самостоятельно через SCM Project ID или SCM Project URL, если указанный параметр не задан явно. Для веб-сайтов - обязательный параметр;
--asset-name — наименование создаваемого актива. Необходимо использовать либо с --group-path, либо с --group-id. Обязательный параметр при использовании --create-asset. По умолчанию берётся имя репозитория в SCM-системе;
--branch— наименование ветки анализируемого репозитория. По умолчанию берётся одно из следующих значений: CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, CI_COMMIT_BRANCH, CI_COMMIT_REF_NAME, BRANCH_NAME;
--commit-author (опционально) — автор коммита, для которого проводилось сканирование. По умолчанию берётся одно из следующих значений: CI_COMMIT_AUTHOR, GIT_AUTHOR_NAME, GIT_COMMITTER_NAME, CHANGE_AUTHOR, BUILD_USER_ID, BUILD_USER;
--commit-author-email (опционально) — Email автора коммита, для которого проводилось сканирование. По умолчанию берётся значение: CI_COMMIT_USER_LOGIN, CI_COMMIT_AUTHOR_EMAIL, GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL, CHANGE_AUTHOR_EMAIL, BUILD_USER_EMAIL;
--commit-sha (опционально) — уникальный идентификатор коммита, для которого производилось сканирование. По умолчанию берётся одно из следующих значений: CI_COMMIT_SHA, GIT_COMMIT;
--commit-timestamp (опционально) — время создания коммита. По умолчанию берётся одной из следующих значений: CI_COMMIT_TIMESTAMP или текущая дата, если предыдущий вариант не найден;
--create-asset (опционально) — создать актив, если его ещё нет в Шерлоке. При использовании необходимо указать --scm-project-id (для репозиториев), --scm-project-url (для репозиториев), --asset-name и --group-path/--group-id;
--group-id — уникальный идентификатор группы, в которой надо создать актив. Имеет приоритет над --group-path. Обязательный параметр при использовании --create-asset;
--group-path — путь к группе, в которой надо создать актив. Обязательный параметр при использовании --create-asset. По умолчанию берётся путь до репозитория в SCM-системе;
--help — показать справку по команде upload;
--job-finished-at (опционально) — время завершения job в конвейере сборки. По умолчанию берётся текущая дата;
--job-started-at (опционально) — время запуска job в конвейере сборки. По умолчанию берётся одной из следующих значений: CI_JOB_STARTED_AT или текущая дата, если предыдущий вариант не найден;
--pipeline-id (опционально) — уникальный идентификатор конвейера сборки, в котором происходило сканирование. По умолчанию берётся одно из следующих значений: CI_PIPELINE_ID, BUILD_NUMBER;
--pipeline-url (опционально) — ссылка на конвейер сборки, в котором происходило сканирование. По умолчанию берётся одно из следующих значений: CI_PIPELINE_URL, BUILD_URL;
--report-file — путь к файлу с отчётом, который надо отправить в Шерлока;
--scan-end-date (опционально) — дата окончания сканирования. По умолчанию берётся текущая дата;
--scan-start-date (опционально) — дата начала сканирования. По умолчанию берётся текущая дата;
--scanner-code — код сканера, отчёт которого надо отправить в Шерлока. Возможные значения: [gitleaks, trufflehog, app_screener, pt_ai, svace, semgrep, sastav, code_scoring, kcs, trivy, kics]. Для сканеров, добавленных самостоятельно, код требуется узнавать через UI.

совет

В Шерлоке доступен альтернативный способ узнать код сканера. Для того, чтобы его уточнить необходимо:

Перейти в раздел Настройки системы -> Сканеры.
Найти нужный сканер в разделе Подключённые.
Нажать на Меню действий () и выбрать Копировать код сканера.

Указанный способ работает для всех типов сканеров: как для поддерживаемых "из коробки", так и для сканеров, добавленных самостоятельно.

--scm-project-id — уникальный идентификатор проекта в SCM-системе. По умолчанию берётся одно из следующих значений: CI_PROJECT_ID Обязательный параметр при использовании --create-asset (для репозиториев);
--scm-project-url — URL проекта в SCM-системе. По умолчанию берётся одно из следующих значений: CI_PROJECT_URL, GIT_URL. Обязательный параметр при использовании --create-asset (для репозиториев).

sher-cli сделана таким образом, чтобы брать большинство необходимых данных из переменных окружения конвейера сборки, из которого её вызывают.

Это позволяет сократить количество полей, которые надо явно указать пользователю и предоставляет дополнительные опции, упрощающие дальнейшую работу (например, возможность перехода из UI Шерлока в конкретный конвейер сборки, из которого были направлены отчёты).

к сведению

Различные комбинации по использованию sher-cli upload приведены в разделе Сценарии использования sher-cli upload.

Флаги команды `sg`

Команда shercli sg обладает следующими флагами:

--asset-id — уникальный идентификатор актива. Для репозиториев Шерлок попробует найти значение самостоятельно через SCM Project ID или SCM Project URL, если указанный параметр не задан явно. Для веб-сайтов - обязательный параметр;
--asset-name — наименование актива, для которого надо выполнить проверку соответствия требованиям Security Gate. Необходимо использовать либо с --group-path, либо с --group-id;
--branch — наименование ветки актива, для которого необходимо выполнить проверку соответствия требованиям Security Gate. По умолчанию берётся одно из следующих значений: CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, CI_COMMIT_BRANCH, CI_COMMIT_REF_NAME, BRANCH_NAME;
--group-id — Уникальный идентификатор группы, в которой находится актив, для которого необходимо выполнить проверку соответствия требованиям Security Gate. Обязательный параметр при использовании --asset-name;
--group-path — Путь к группе, в которой находится актив, для которого необходимо выполнить проверку соответствия требованиям Security Gate. Обязательный параметр при использовании --asset-name;
--help — показать справку по команде sg;
--pipeline-id — опционально Уникальный идентификатор конвейера сборки, в котором происходила проверка соответствия требованиям Security Gate. По умолчанию берётся одно из следующих значений: CI_PIPELINE_ID, BUILD_NUMBER;
--scm-project-id — уникальный идентификатор проекта в SCM-системе. По умолчанию берётся одно из следующих значений: CI_PROJECT_ID;
--scm-project-url — URL проекта в SCM-системе. По умолчанию берётся одно из следующих значений: CI_PROJECT_URL, GIT_URL.

Это позволяет сократить количество полей, которые надо явно указать пользователю.

к сведению

Различные комбинации по использованию sher-cli sg приведены в разделе Сценарии использования sher-cli sg.

Сценарии использования `sher-cli`

Сценарии использования `sher-cli upload`

Репозитории: отправка отчётов без создания актива в Шерлоке

Отправка отчётов без создания активов в Шерлоке с использованием sher-cli возможна несколькими способами:

Отправка отчёта сканера с использованием Идентификатора актива:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-id <ASSET_ID> 

Отправка отчёта сканера с использованием URL проекта в SCM-системе:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--scm-project-url <GITLAB_PROJECT_URL> # в CI — опционально, возьмём данные из `env`

Отправка отчёта сканера с использованием Имени актива и Пути до группы в Шерлоке:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-name <ASSET_NAME> \
--group-path <GROUP_PATH>

Отправка отчёта сканера с использованием Имени актива и Идентификатора группы в Шерлоке:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-name <ASSET_NAME> \
--group-id <GROUP_ID>

Репозитории: отправка отчётов с созданием актива в Шерлоке

к сведению

Если вы добавили токен, который обладает правами доступа к создаваемому репозиторию в SCM-системе, то Шерлок автоматически использует его для настройки интеграции создаваемого актива с репозиторием в SCM-системе.

Отправка отчётов с созданием активов в Шерлоке с использованием sher-cli возможна несколькими способами:

Отправка отчёта сканера с использованием Имени актива и URL проекта в SCM-системе и созданием репозитория:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--scanner-code SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--report-file <FILE_NAME> \
--create-asset \
--group-path <GROUP_PATH> \ # в CI — опционально, возьмём данные из `env`
--asset-name <ASSET_NAME> \ # в CI — опционально, возьмём данные из `env`
--scm-project-url <GITLAB_PROJECT_URL>

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

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--scanner-code SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--report-file <FILE_NAME> \
--create-asset \
--group-path <GROUP_PATH> \
--asset-name <ASSET_NAME> \
--scm-project-id <GITLAB_PROJECT_ID> \ # в CI — опционально, возьмём данные из `env`
--scm-project-url <GITLAB_PROJECT_URL> # в CI — опционально, возьмём данные из `env`

Отправка отчёта сканера с использованием Имени актива и Идентификатора группы в Шерлоке с созданием репозитория:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--scanner-code SCANNER_CODE> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--report-file <FILE_NAME> \
--create-asset \
--group-id <GROUP_ID> \
--asset-name <ASSET_NAME> \
--scm-project-id <GITLAB_PROJECT_ID> \ # в CI — опционально, возьмём данные из `env`
--scm-project-url <GITLAB_PROJECT_URL> # в CI — опционально, возьмём данные из `env`

к сведению

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

Веб-сайты: отправка отчётов без создания актива в Шерлоке

Отправка отчётов без создания активов в Шерлоке с использованием sher-cli возможна несколькими способами:

Отправка отчёта сканера с использованием идентификатора актива:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--asset-id <ASSET_ID>

Отправка отчёта сканера с использованием Имени актива и Пути до группы в Шерлоке:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--asset-name <ASSET_NAME> \
--group-path <GROUP_PATH>

Отправка отчёта сканера с использованием Имени актива и Идентификатора группы в Шерлоке:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--report-file <FILE_NAME> \
--scanner-code <SCANNER_CODE> \
--asset-name <ASSET_NAME> \
--group-id <GROUP_ID>

Веб-сайты: отправка отчётов с созданием актива в Шерлоке

Отправка отчётов с созданием активов в Шерлоке с использованием sher-cli возможна несколькими способами:

Отправка отчёта сканера с использованием Имени актива и Пути до группы в Шерлоке с созданием веб-сайта:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--scanner-code <SCANNER_CODE> \
--report-file <FILE_NAME> \
--create-asset \
--group-path <GROUP_PATH> \
--asset-name <ASSET_NAME>

Отправка отчёта сканера с использованием Имени актива и Идентификатора группы в Шерлоке с созданием веб-сайта:

./sher-cli upload \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--scanner-code <SCANNER_CODE> \
--report-file <FILE_NAME> \
--create-asset \
--group-ID <GROUP_ID> \
--asset-name <ASSET_NAME>

Сценарии использования `sher-cli sg`

Проверка выполнения условий SG с использованием sher-cli возможна несколькими способами:

Проверка выполнения условий SG с использованием Идентификатора актива:

./sher-cli sg \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-id <ASSET_NAME>

Проверка выполнения условий SG с использованием URL проекта в SCM-системе:

./sher-cli sg \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--scm-project-url <GITLAB_PROJECT_URL> \ # в CI — опционально, возьмём данные из `env`

Проверка выполнения условий SG с использованием Имени актива и Пути до группы в Шерлоке:

./sher-cli sg \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-name <ASSET_NAME> \
--group-path <GROUP_PATH>

Проверка выполнения условий SG с использованием Имени актива и Идентификатора группы в Шерлоке:

./sher-cli sg \
--sherlock-url https://sherlock.example.com \
--sherlock-token <SHERLOCK_TOKEN> \
--branch <BRANCH_NAME> \ # в CI — опционально, возьмём данные из `env`
--asset-name <ASSET_NAME> \
--group-id <GROUP_ID>

Создание CI-шаблонов

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

к сведению

Каждый CI-шаблон предполагает, что большинство данных будет извлечено из переменных окружения конвейера сборки, а потому содержит лишь минимально необходимое количество информации. Для более "тонкой" настройки можно воспользоваться флагами sher-cli, которые описаны в соответствующем разделе. Сценарии использования sher-cli с разными комбинациями флагов описаны в разделах: upload и sg.

Подготовительная работа

Перед тем, как осуществлять генерацию CI-шаблонов необходимо убедиться, что настроена системная интеграция между Шерлоком и нужными сканерами.

к сведению

Сканеры, не подключенные/не активированные на уровне Системы не будут доступны для выбора при генерации CI-шаблонов.

Генерация CI-шаблонов

Для генерации CI-шаблонов необходимо, находясь в активе (репозиторий или веб-сайт), нажать на Меню действий () и выбрать CI шаблоны.

Выбрать нужные сканеры, путём нажатия на них мышкой, для которых необходимо сгенерировать CI-шаблоны.

Нажать кнопку:
- Сгенерировать для GitLab: если необходимо сгенерировать CI-шаблоны для GitLab CI;
- Сгенерировать для Jenkins: если необходимо сгенерировать CI-шаблоны для Jenkins.
Скопировать сгенерированные шаблоны и адаптировать их под используемый CI-конвейер.
совет
Параметры:
- --sherlock-token
- --sherlock-url
Рекомендуется указать в переменных окружения GitLab CI (для проекта или для группы).
к сведению
В этом же разделе можно скопировать уникальный идентификатор актива - ProjectID - который можно передавать в качестве параметра --asset-id при использовании sher-cli.

Возможности sher-cli​

Команды и глобальные флаги​

Флаги команды upload​

Флаги команды sg​

Сценарии использования sher-cli​

Сценарии использования sher-cli upload​

Репозитории: отправка отчётов без создания актива в Шерлоке​

Репозитории: отправка отчётов с созданием актива в Шерлоке​

Веб-сайты: отправка отчётов без создания актива в Шерлоке​

Веб-сайты: отправка отчётов с созданием актива в Шерлоке​

Сценарии использования sher-cli sg​

Создание CI-шаблонов​

Подготовительная работа​

Генерация CI-шаблонов​

Возможности `sher-cli`

Команды и глобальные флаги

Флаги команды `upload`

Флаги команды `sg`

Сценарии использования `sher-cli`

Сценарии использования `sher-cli upload`

Репозитории: отправка отчётов без создания актива в Шерлоке

Репозитории: отправка отчётов с созданием актива в Шерлоке

Веб-сайты: отправка отчётов без создания актива в Шерлоке

Веб-сайты: отправка отчётов с созданием актива в Шерлоке

Сценарии использования `sher-cli sg`

Создание CI-шаблонов

Подготовительная работа

Генерация CI-шаблонов