Отправка файла SARIF в GitHub

Примечание.

Администратор сайта должен включить code scanning перед использованием этой функции. Дополнительные сведения см. в разделе Настройка сканирования кода для устройства.

Возможно, вы не сможете включить или отключить code scanning, если владелец предприятия установил политику GitHub Advanced Security на уровне предприятия. Дополнительные сведения см. в разделе Применение политик безопасности кода и анализа для вашего предприятия.

Если вы используете сторонний аналитический инструмент или систему CI/CD для поиска уязвимостей, вы можете сгенерировать SARIF-файл и загрузить его в GitHub. Лучший способ загрузки зависит от того, как вы генерируете SARIF-файл.

Например, если вы используете:

        GitHub Actions Для прохождения CodeQL действия не требуются дополнительные действия. Действие автоматически загружает файл SARIF после завершения CodeQL анализа.

        GitHub Actions чтобы запустить инструмент анализа, совместимый с SARIF, можно обновить рабочий процесс, включив финальный этап загрузки результатов. См. [Загрузка code scanning анализа с GitHub Actions](#uploading-a-code-scanning-analysis-with-github-actions).

Для CodeQL CLI запуска code scanning в вашей системе CI вы можете использовать CLI для загрузки результатов в GitHub. См . раздел AUTOTITLE.
Это инструмент, который генерирует результаты в виде артефакта вне вашего репозитория, и вы можете использовать code scanning API для загрузки файла. См . раздел AUTOTITLE.

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

Загрузка code scanning анализа с помощью GitHub Actions

Чтобы GitHub Actions загрузить сторонний SARIF-файл в репозиторий, вам понадобится рабочий процесс. Дополнительные сведения см. в разделе Написание рабочих процессов.

Для рабочего процесса необходимо действие upload-sarif, которое является частью репозитория github/codeql-action. Это включает в себя входные параметры, которые можно использовать для настройки отправки. Далее перечислены основные входные параметры, которые вы будете использовать:

        `sarif_file`, который обеспечивает настройку файла или каталога для отправляемых файлов SARIF. Путь к каталогу или файлу задается относительно корня репозитория.

        `category` (необязательный), который назначает категорию для результатов в файле SARIF. Это позволяет анализировать один и тот же коммит несколькими способами и просматривать результаты, используя представления code scanning в GitHub. Например, вы можете выполнить анализ с помощью нескольких инструментов, а в монорепозиториях проанализировать различные срезы на основе подмножества измененных файлов.

Дополнительные сведения см. в описании действия upload-sarif.

Вы можете настроить действие upload-sarif, которое будет выполняться при наступлении событий push и scheduled. Дополнительные сведения о событиях см. в GitHub Actions разделе События, инициирующие рабочие процессы.

Если файл SARIF не включает partialFingerprints, поле upload-sarif будет вычислено автоматически при выполнении действия partialFingerprints и будет предпринята попытка предотвратить дублирование оповещений. GitHub может создавать partialFingerprints только тогда, когда репозиторий содержит как файл SARIF, так и исходный код, используемый для статического анализа. Дополнительные сведения о предотвращении дублирования оповещений см. в разделе Поддержка SARIF для проверки кода.

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

Пример рабочего процесса для файлов SARIF, созданных за пределами репозитория

Вы можете создать новый рабочий процесс, который будет отправлять файлы SARIF после их фиксации в репозитории. Это удобно, если файл SARIF создается как артефакт за пределами репозитория.

В этом примере рабочий процесс выполняется при каждой отправке фиксаций в репозиторий. Действие использует свойство partialFingerprints, чтобы определить, произошли ли изменения. В дополнение к выполнению при отправке фиксаций запланировано выполнение рабочего процесса один раз в неделю. Дополнительные сведения см. в разделе События, инициирующие рабочие процессы.

Этот рабочий процесс отправляет файл results.sarif, расположенный в корне репозитория. Дополнительные сведения о создании файла рабочего процесса см. в разделе Написание рабочих процессов.

Кроме того, вы можете изменить этот рабочий процесс, чтобы отправлять каталог файлов SARIF. Например, можно поместить все файлы SARIF в каталог в корне репозитория с именем sarif-output и присвоить входному параметру действия sarif_file значение sarif-output. Обратите внимание, что при отправке каталога каждый файл SARIF должен содержать уникальный runAutomationDetails.id для определения категории результатов. Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

Пример рабочего процесса, выполняющего средство для анализа ESLint

Если вы создаете сторонний файл SARIF в рамках рабочего процесса непрерывной интеграции (CI), вы можете добавить действие upload-sarif в качестве шага после выполнения тестов CI. Если у вас ещё нет CI-рабочего процесса, вы можете создать его с помощью GitHub Actions шаблона. Дополнительные сведения см. в разделе AUTOTITLE.

Рабочий процесс демонстрирует пример выполнения средства для статического анализа ESLint в качестве шага в рабочем процессе. На шаге Run ESLint запускается средство ESLint и выводится файл results.sarif. Рабочий процесс затем загружает results.sarif файл с GitHub помощью действия upload-sarif . Дополнительные сведения о создании файла рабочего процесса см. в разделе Понимание GitHub Actions.

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Отправка нескольких ФАЙЛОВ SARIF для фиксации

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

При передаче нескольких файлов SARIF для фиксации необходимо указать категорию для каждого анализа. Способ указания категории зависит от метода анализа:

Используя CodeQL CLI direct, передайте --sarif-category аргумент codeql database analyze команде при генерации SARIF-файлов. Дополнительные сведения см. в разделе Сведения о интерфейсе командной строки CodeQL.
Используя GitHub Actions с codeql-action/analyze, категория автоматически устанавливается из имени рабочего процесса и любых матричных переменных (обычно, language). Это можно переопределить, указав входные category данные для действия, что полезно при анализе разных разделов monorepo в одном рабочем процессе.
При GitHub Actions загрузке результатов из других инструментов статического анализа необходимо указать category ввод, если вы загружаете более одного файла результатов для одного инструмента в одном рабочем процессе. Дополнительные сведения см. в разделе Отправка файла SARIF в GitHub.
Если вы не используете ни один из этих подходов, то вам необходимо указать уникальный runAutomationDetails.id в каждом файле SARIF для передачи. Дополнительные сведения об этом свойстве см runAutomationDetails . в разделе "Объект".

При передаче второго файла SARIF для фиксации с той же категорией и из того же средства более ранние результаты перезаписываются. Однако, если попытаться загрузить несколько SARIF-файлов для одного инструмента и категории в одном GitHub Actions рабочем процессе, ошибка будет обнаружена, и запуск провалится.

Дополнительные материалы

        [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)

        [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)

        [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)

        [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

        [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)

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

В этой статье

Загрузка code scanning анализа с помощью GitHub Actions

Пример рабочего процесса для файлов SARIF, созданных за пределами репозитория

Пример рабочего процесса, выполняющего средство для анализа ESLint

Отправка нескольких ФАЙЛОВ SARIF для фиксации

Дополнительные материалы