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

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

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

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

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

В этой статье

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

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

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

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

Note

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

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

Прежде чем отправлять результаты в , сначала необходимо создать personal access token.

  • Personal access token (classic) требуется "Code scanning оповещений" доступ на чтение и запись для необходимых репозиториев.
  • Fine-grained personal access token требуется доступ к репозиторию security_events .

Дополнительные сведения см. в разделе Управление личными маркерами доступа.

Если вы установили CodeQL CLI в сторонней системе CI, чтобы создать результаты для отображения в в качестве оповещений сканирования кода, можно использовать App или personal access token для отправки результатов в . Дополнительные сведения см. в разделе Использование сканирования кода с существующей системой CI.

Отправка результатов в

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

Прежде чем отправлять результаты в , необходимо определить оптимальный способ передачи App или personal access token, созданных в предыдущем разделе в CodeQL CLI. Рекомендуется проанализировать руководство по использованию системы CI для безопасного использования хранилища секретов. CodeQL CLI поддерживает следующие действия:

  • Взаимодействие с хранилищем секретов с помощью ---auth-stdin параметра (рекомендуется).
  • Сохранение секрета в переменной среды _TOKEN и запуск интерфейса командной строки без включения параметра ---auth-stdin.
  • Для тестирования можно передать ---auth-stdin параметр командной строки и предоставить временный маркер с помощью стандартных входных данных.

Если вы решили использовать наиболее безопасный и надежный метод конфигурации, запустите codeql upload-results каждый файл результатов SARIF и включите ---auth-stdin , если маркер не доступен в переменной _TOKENсреды.

#  App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql  upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> ---auth-stdin

#  App or personal access token available in _TOKEN
codeql  upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>
ВариантОбязательное полеИспользование
--repositoryУкажите ВЛАДЕЛЬЦА/ИМЯ репозитория, в который будут отправлены данные. Владелец должен быть организацией внутри предприятия или на плане Team , с Code Security включен для репозитория, если репозиторий не является общедоступным. Дополнительные сведения см. в разделе Управление параметрами безопасности и анализа для репозитория.
--refУкажите имя извлеченного и проанализированного ref, чтобы результаты можно было сопоставить с правильным кодом. Для ветки используйте: refs/heads/BRANCH-NAME, для фиксации заголовка запроса на вытягивание используйте refs/pull/NUMBER/head или для созданной фиксации слияния запроса на вытягивание используйте refs/pull/NUMBER/merge.
--commitУкажите полный SHA для проанализированной фиксации.
--sarifУкажите файл SARIF для загрузки.
---auth-stdinПередайте интерфейс командной строки App или personal access token, созданные для проверки подлинности с помощью REST API из хранилища секретов с помощью стандартных входных данных. Это не требуется, если команда имеет доступ к переменной среды _TOKEN, заданной с помощью этого маркера.

Дополнительные сведения см. в разделе upload-results.

Note

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

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

В следующем примере передаются результаты из ФАЙЛА SARIF temp/example-repo-js.sarif в репозиторий my-org/example-repo. Для API code scanning сообщается, что результаты необходимы для фиксации deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 в ветви main. В примере предполагается, что App или personal access token, созданных для проверки подлинности с помощью REST API , использует _TOKEN переменную среды.

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

Эта команда ничего не выводит, если загрузка не удалась. Командная строка возвращается после завершения загрузки и начала обработки данных. В небольших базах кода вы сможете просматривать оповещения code scanning в вскоре после этого. Оповещения можно просмотреть непосредственно в запросе на вытягивание или на вкладке "Безопасность" для ветвей в зависимости от извлеченного кода. Дополнительные сведения см. в разделе [AUTOTITLE и Рассмотрение оповещений проверки кода в запросах на вытягивание](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository).

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

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

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

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

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

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

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

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

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

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

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

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