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 Enterprise Server. Для этой функции требуется лицензия на GitHub Advanced Security. Дополнительные сведения см. в разделе Сведения о GitHub Advanced Security.

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

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

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

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

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

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

Отправка анализа 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 для определения категории результатов. Дополнительные сведения см. в статье runAutomationDetails Объект.

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@v3
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v2
        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@v3
      - 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@v2
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

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