Skip to main content

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

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

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

People with write permissions to a repository can upload code scanning data generated outside GitHub.

Code scanning доступен для всех общедоступных репозиториев на GitHub.com. Чтобы использовать code scanning в частном репозитории, принадлежащем организации, необходима лицензия на GitHub Advanced Security. Дополнительные сведения см. в разделе Сведения о GitHub Advanced Security.

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

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

Файлы 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 Advanced Security. Если отображается ошибка Advanced Security must be enabled for this repository to use code scanning, убедитесь, что GitHub Advanced Security включен. Дополнительные сведения см. в разделе Управление параметрами безопасности и анализа для репозитория.

Отправка анализа code scanning с помощью GitHub Actions

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

Для рабочего процесса необходимо действие 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, расположенный в корне репозитория. Дополнительные сведения о создании файла рабочего процесса см. в разделе "Изучение GitHub Actions".

Кроме того, вы можете изменить этот рабочий процесс, чтобы отправлять каталог файлов 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

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