Отправка результатов анализа CodeQL в GitHub

Вы можете использовать CodeQL CLI для отправки результатов анализа CodeQL в GitHub.

Кто может использовать эту функцию?

GitHub CodeQL лицензируется на основе каждого пользователя при установке. Вы можете использовать CodeQL только для определенных задач в соответствии с ограничениями лицензии. Дополнительные сведения см. в разделе Сведения о интерфейсе командной строки CodeQL.

Если у вас есть лицензия GitHub Advanced Security, можно использовать CodeQL для автоматического анализа, непрерывной интеграции и непрерывной доставки. Дополнительные сведения см. в разделе Сведения о GitHub Advanced Security.

В этой статье

Сведения о выходных данных 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 с разрешением 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/managing-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-файлов из успешного анализа.