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

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

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

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 Enterprise Cloud поддерживается для репозиториев, принадлежащих организации, с включенными GitHub Advanced Security и для общедоступных репозиториев на GitHub.com. Дополнительные сведения см. в разделе Управление параметрами безопасности и анализа для репозитория.

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

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

Примечание. Если вы проанализировали несколько данных 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/managing-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 для анализа неудачного анализа с помощью 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 Enterprise Cloud с помощью autoTITLE, например:

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

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