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

Примечание.

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

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

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

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

GitHub Actions: для выполнения действия CodeQL не требуется никаких дальнейших действий. Действие CodeQL автоматически отправляет файл SARIF после завершения анализа.
GitHub Actions Чтобы запустить совместимый с SARIF инструмент анализа, можно обновить рабочий процесс, включив последний шаг для загрузки результатов. См. Загрузка анализа code scanning с GitHub Actions.
CodeQL CLI для запуска code scanning в вашей системе CI, вы можете использовать CLI для загрузки результатов в GitHub. См . раздел AUTOTITLE.
Это инструмент, который генерирует результаты в виде артефакта вне вашего репозитория, вы можете использовать API code scanning для загрузки файла. См . раздел 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 напрямую, при создании файлов SARIF передайте аргумент --sarif-category для команды codeql database analyze. Дополнительные сведения см. в разделе Сведения о интерфейсе командной строки 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 для фиксации

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