Сведения о выходных данных SARIF
GitHub создает предупреждения code scanning в репозитории с использованием сведений из файлов формата обмена результатами статического анализа (SARIF). SARIF предназначен для представления выходных данных широкого спектра статических средств анализа, и существует множество функций в спецификации SARIF, которые считаются "необязательными". Для результатов должен использоваться формат SARIF версии 2.1.0. Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.
После анализа базы данных CodeQL с помощью CodeQL CLIу вас будет ФАЙЛ SARIF, содержащий результаты. Дополнительные сведения см. в разделе Анализ кода с помощью запросов CodeQL. Затем можно использовать CodeQL CLI для отправки результатов в GitHub.
Если вы использовали метод, отличный от метода CodeQL CLI для создания результатов, можно использовать другие методы отправки. Дополнительные сведения см. в разделе Отправка файла SARIF в GitHub.
Примечание. Передача данных SARIF для отображения как code scanning приводит к тому, что GitHub поддерживается для репозиториев, принадлежащих организации, с включенными GitHub Advanced Security и для общедоступных репозиториев на GitHub.com. Дополнительные сведения см. в разделе Управление параметрами безопасности и анализа для репозитория.
Создание маркера для проверки подлинности с помощью GitHub
Прежде чем отправлять результаты в GitHub, сначала необходимо создать personal access token.
- Personal access token (classic) требуется "Code scanning оповещений" доступ на чтение и запись для необходимых репозиториев.
- Fine-grained personal access token требуется доступ к репозиторию security_events .
Дополнительные сведения см. в разделе Управление личными маркерами доступа.
Если вы установили CodeQL CLI в сторонней системе CI, чтобы создать результаты для отображения результатов в GitHub в качестве оповещений сканирования кода, можно использовать GitHub App или personal access token для отправки результатов в GitHub. Дополнительные сведения см. в разделе Использование сканирования кода с существующей системой CI.
Загрузка результатов в GitHub
Вы можете проверка, что свойства SARIF имеют поддерживаемый размер для отправки, и что файл совместим с сканированием кода. Дополнительные сведения см. в разделе "Поддержка SARIF для проверки кода".
Прежде чем отправлять результаты в GitHub, необходимо определить оптимальный способ передачи GitHub App или personal access token, созданных в предыдущем разделе в CodeQL CLI. Рекомендуется проанализировать руководство по использованию системы CI для безопасного использования хранилища секретов. CodeQL CLI поддерживает следующие действия:
- Взаимодействие с хранилищем секретов с помощью
--github-auth-stdin
параметра (рекомендуется). - Сохранение секрета в переменной среды
GITHUB_TOKEN
и запуск интерфейса командной строки без включения параметра--github-auth-stdin
. - Для тестирования можно передать
--github-auth-stdin
параметр командной строки и предоставить временный маркер с помощью стандартных входных данных.
Если вы решили использовать наиболее безопасный и надежный метод конфигурации, запустите codeql github upload-results
каждый файл результатов SARIF и включите --github-auth-stdin
, если маркер не доступен в переменной GITHUB_TOKEN
среды.
# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
--repository=<repository-name> \
--ref=<ref> --commit=<commit> \
--sarif=<file> --github-auth-stdin
# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
--repository=<repository-name> \
--ref=<ref> --commit=<commit> \
--sarif=<file>
Вариант | Обязательное поле | Использование |
---|---|---|
--repository | Укажите ВЛАДЕЛЬЦА/ИМЯ репозитория, в который будут отправлены данные. Владельцем должна быть организация в пределах предприятия, имеющая лицензию на GitHub Advanced Security. Вам необходимо включить GitHub Advanced Security для репозитория, если только репозиторий не является общедоступным. Дополнительные сведения см. в разделе Управление параметрами безопасности и анализа для репозитория. | |
--ref | Укажите имя извлеченного и проанализированного ref , чтобы результаты можно было сопоставить с правильным кодом. Для ветки используйте: refs/heads/BRANCH-NAME , для фиксации заголовка запроса на вытягивание используйте refs/pull/NUMBER/head или для созданной GitHub фиксации слияния запроса на вытягивание используйте refs/pull/NUMBER/merge . | |
--commit | Укажите полный SHA для проанализированной фиксации. | |
--sarif | Укажите файл SARIF для загрузки. | |
--github-auth-stdin | Передайте интерфейс командной строки GitHub App или personal access token, созданные для проверки подлинности с помощью REST API GitHubиз хранилища секретов с помощью стандартных входных данных. Это не требуется, если команда имеет доступ к переменной среды GITHUB_TOKEN , заданной с помощью этого маркера. |
Дополнительные сведения см. в разделе github upload-results.
Примечание. Если вы проанализировали несколько данных CodeQL базы данных для одной фиксации, необходимо указать категорию SARIF для каждого набора результатов, созданных этой командой. При отправке результатов в GitHub code scanning использует эту категорию для хранения результатов для каждого языка отдельно. Если вы забыли это сделать, то при каждой отправке будут перезаписаны предыдущие результаты. Дополнительные сведения см. в разделе Анализ кода с помощью запросов CodeQL.
Базовый пример отправки результатов в GitHub
В следующем примере передаются результаты из ФАЙЛА SARIF temp/example-repo-js.sarif
в репозиторий my-org/example-repo
. Для API code scanning сообщается, что результаты необходимы для фиксации deb275d2d5fe9a522a0b7bd8b6b6a1c939552718
в ветви main
. В примере предполагается, что GitHub App или personal access token, созданных для проверки подлинности с помощью REST API GitHub, использует GITHUB_TOKEN
переменную среды.
codeql github upload-results \
--repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=/temp/example-repo-js.sarif
Эта команда ничего не выводит, если загрузка не удалась. Командная строка возвращается после завершения загрузки и начала обработки данных. В небольших базах кода вскоре после этого вы сможете изучить оповещения code scanning в GitHub. Оповещения можно просмотреть непосредственно в запросе на вытягивание или на вкладке "Безопасность" для ветвей в зависимости от извлеченного кода. Дополнительные сведения см. в разделе "[AUTOTITLE" и "Рассмотрение оповещений проверки кода в запросах на вытягивание](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository)".
Отправка диагностических сведений в GitHub в случае сбоя анализа
Когда CodeQL CLI успешно завершает анализ базы данных, она собирает диагностические сведения, такие как покрытие файлов, предупреждения и ошибки, и включает его в ФАЙЛ SARIF с результатами. При отправке ФАЙЛА SARIF в GitHub диагностические сведения отображаются на code scanning Страница состояния средства для репозитория, чтобы сделать его простым, чтобы узнать, насколько хорошо CodeQL работает и отлаживать любые проблемы. Дополнительные сведения см. в разделе Сведения о странице состояния средства для сканирования кода.
Однако, если codeql database analyze
файл SARIF не удается отправить в GitHub и диагностические данные не отображаются на code scanning Страница состояния средства для репозитория. Это затрудняет для пользователей устранение неполадок, если у них нет доступа к файлам журналов в системе CI.
Рекомендуется настроить рабочий процесс CI для экспорта и отправки диагностических сведений в GitHub при сбое анализа. Это можно сделать с помощью следующих простых команд для экспорта диагностических сведений и отправки его в GitHub.
Экспорт диагностических сведений при сбое анализа
Вы можете создать ФАЙЛ SARIF для анализа неудачного анализа с помощью autoTITLE, например:
$ codeql database export-diagnostics codeql-dbs/example-repo \
--sarif-category=javascript-typescript --format=sarif-latest \
--output=/temp/example-repo-js.sarif
Этот ФАЙЛ SARIF будет содержать диагностические сведения для неудающегося анализа, включая сведения о охвате файлов, предупреждения и ошибки, созданные во время анализа.
Отправка диагностических сведений при сбое анализа
Эти диагностические сведения можно сделать доступными для Страница состояния средства путем отправки ФАЙЛА SARIF в GitHub с помощью autoTITLE, например:
codeql github upload-results \
--repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=/temp/example-repo-js.sarif
Это то же самое, что и процесс отправки SARIF-файлов из успешного анализа.