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

Вы можете отправлять файлы SARIF, созданные за пределами GitHub, и просматривать оповещения code scanning, полученные от сторонних инструментов в репозитории.

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

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

Репозитории, принадлежащие организации, с включенными GitHub Advanced Security

В этой статье

Note

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

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

Сведения об отправке файлов SARIF для code scanning

GitHub создает предупреждения code scanning в репозитории с использованием сведений из файлов формата обмена результатами статического анализа (SARIF). Файлы SARIF можно отправить в репозиторий с помощью API или GitHub Actions. Дополнительные сведения см. в разделе Использование сканирования кода с существующей системой CI.

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

Результаты можно отправить с помощью API GitHub Actions, API code scanning или CodeQL CLI. Выбор лучшего метода отправки будет зависеть от способа создания файла SARIF, например если вы используете:

  • GitHub Actions: для выполнения действия CodeQL не требуется никаких дальнейших действий. Действие CodeQL автоматически отправляет файл SARIF после завершения анализа.
  • GitHub Actions: для запуска средства для анализа, совместимого с SARIF, можно обновить рабочий процесс, чтобы включить последний шаг, на котором отправляются результаты (см. ниже).
  • CodeQL CLI для запуска code scanning в системе CI можно использовать CLI для отправки результатов в GitHub (дополнительные сведения см. в разделе "Использование сканирования кода с существующей системой CI").
  • Средство, которое создает результаты в качестве артефакта за пределами репозитория, можно использовать API code scanning для отправки файла (дополнительные сведения см. в разделе "Конечные точки REST API для сканирования кода").

Отправка анализа 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, поле partialFingerprints будет вычислено автоматически при выполнении действия upload-sarif и будет предпринята попытка предотвратить дублирование оповещений. 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@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif
        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. Дополнительные сведения см. в разделе "Краткое руководство по GitHub Actions".

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

Рабочий процесс демонстрирует пример выполнения средства для статического анализа 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@v4
      - 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
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

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