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

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

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

Пользователи с доступом на запись

CodeQL доступен для следующих типов репозитория:

В этой статье

Сведения о выходных данных SARIF

GitHub создает предупреждения code scanning в репозитории с использованием сведений из файлов формата обмена результатами статического анализа (SARIF). SARIF предназначен для представления выходных данных широкого спектра статических средств анализа, и существует множество функций в спецификации SARIF, которые считаются "необязательными". Для результатов должен использоваться формат SARIF версии 2.1.0. Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.

После анализа базы данных CodeQL с помощью CodeQL CLIу вас будет ФАЙЛ SARIF, содержащий результаты. Дополнительные сведения см. в разделе Анализ кода с помощью запросов CodeQL. Затем можно использовать CodeQL CLI для отправки результатов в GitHub.

Если вы использовали метод, отличный от метода CodeQL CLI для создания результатов, можно использовать другие методы отправки. Дополнительные сведения см. в разделе Отправка файла SARIF в GitHub.

Note

Отправка данных SARIF для отображения как code scanning приводит к поддержке GitHub Enterprise Cloud для репозиториев, принадлежащих организации, с GitHub Advanced Security включено, а также общедоступные репозитории для GitHub.com. Дополнительные сведения см. в разделе «Управление параметрами безопасности и анализа для репозитория».

Создание маркера для проверки подлинности с помощью GitHub Enterprise Cloud

Прежде чем отправлять результаты в GitHub Enterprise Cloud, сначала необходимо создать 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 Enterprise Cloud. Дополнительные сведения см. в разделе Использование сканирования кода с существующей системой CI.

Загрузка результатов в GitHub Enterprise Cloud

Вы можете проверка, что свойства SARIF имеют поддерживаемый размер для отправки, и что файл совместим с сканированием кода. Дополнительные сведения см. в разделе "Поддержка SARIF для проверки кода".

Прежде чем отправлять результаты в GitHub Enterprise Cloud, необходимо определить оптимальный способ передачи 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.

Note

Если вы проанализировали несколько данных CodeQL базы данных для одной фиксации, необходимо указать категорию SARIF для каждого набора результатов, созданных этой командой. При отправке результатов в GitHub Enterprise Cloud code scanning использует эту категорию для хранения результатов для каждого языка отдельно. Если вы забыли это сделать, то при каждой отправке будут перезаписаны предыдущие результаты. Дополнительные сведения см. в разделе Анализ кода с помощью запросов CodeQL.

Базовый пример отправки результатов в GitHub Enterprise Cloud

В следующем примере передаются результаты из ФАЙЛА 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 Enterprise Cloud. Оповещения можно просмотреть непосредственно в запросе на вытягивание или на вкладке "Безопасность" для ветвей в зависимости от извлеченного кода. Дополнительные сведения см. в разделе [AUTOTITLE и Рассмотрение оповещений проверки кода в запросах на вытягивание](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository).

Отправка диагностических сведений в GitHub Enterprise Cloud в случае сбоя анализа

Когда CodeQL CLI успешно завершает анализ базы данных, она собирает диагностические сведения, такие как покрытие файлов, предупреждения и ошибки, и включает его в ФАЙЛ SARIF с результатами. При отправке ФАЙЛА SARIF в GitHub диагностические сведения отображаются на code scanning Страница состояния средства для репозитория, чтобы сделать его простым, чтобы узнать, насколько хорошо CodeQL работает и отлаживать любые проблемы. Дополнительные сведения см. в разделе Сведения о странице состояния средства для сканирования кода.

Однако, если codeql database analyze файл SARIF не удается отправить в GitHub и диагностические данные не отображаются на code scanning Страница состояния средства для репозитория. Это затрудняет для пользователей устранение неполадок, если у них нет доступа к файлам журналов в системе CI.

Рекомендуется настроить рабочий процесс CI для экспорта и отправки диагностических сведений в GitHub Enterprise Cloud при сбое анализа. Это можно сделать с помощью следующих простых команд для экспорта диагностических сведений и отправки его в GitHub.

Экспорт диагностических сведений при сбое анализа

Вы можете создать ФАЙЛ SARIF для неработоспособных анализов с помощью диагностика экспорта базы данных, например:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Этот ФАЙЛ SARIF будет содержать диагностические сведения для неудающегося анализа, включая сведения о охвате файлов, предупреждения и ошибки, созданные во время анализа.

Отправка диагностических сведений при сбое анализа

Эти диагностические сведения можно сделать доступными для Страница состояния средства путем отправки ФАЙЛА SARIF в GitHub Enterprise Cloud с помощью github upload-results, например:

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

Это то же самое, что и процесс отправки SARIF-файлов из успешного анализа.