Включение проверки кода с помощью средств сторонних разработчиков

4 мин

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

В этом уроке вы узнаете, как включить сканирование кода с помощью сторонних средств и как использовать и отправлять ФАЙЛЫ SARIF.

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

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

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

API сканирования кода

API сканирования кода позволяет получить информацию о сканировании кода оповещений, анализа, баз данных и конфигурации настройки по умолчанию из репозитория. Кроме того, можно обновить оповещения проверки кода и конфигурацию установки по умолчанию. Конечные точки можно использовать для создания автоматических отчетов для оповещений сканирования кода в организации или отправки результатов анализа, созданных с помощью средств автономного сканирования кода.

Вы можете получить доступ к API GitHub по протоколу HTTPS.https://api.github.com Все данные отправляются и получаются в формате JSON. API использует пользовательские типы мультимедиа, чтобы потребители могли выбирать формат данных, которые они хотят получить. Типы мультимедиа связаны с конкретными ресурсами, что позволяет изменять их независимо друг от друга и обеспечить поддержку форматов, которые не поддерживают другие ресурсы.

Существует один поддерживаемый пользовательский тип носителя для REST API сканирования кода application/sarif+json.

Этот тип мультимедиа можно использовать с запросами GET, отправленными в конечную точку /analyses/{analysis_id}. При использовании этого типа мультимедиа с данной операцией ответ включает подмножество фактических данных, отправленных для указанного анализа, а не сводку анализа, возвращаемою при использовании типа мультимедиа по умолчанию. Ответ также содержит дополнительные данные, например свойства github/alertNumber и github/alertUrl. Для данных применяется формат SARIF версии 2.1.0.

Ниже приведен пример команды cURL с помощью API для перечисления оповещений сканирования кода для организации:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/code-scanning/alerts

Дополнительные сведения об использовании API сканирования кода см. в документации по REST API GitHub .

CodeQL CLI

CodeQL CLI — это отдельный продукт, который можно использовать для анализа кода. Его основная задача — создание представления базы данных для базы кода (базы данных CodeQL). Когда база данных будет готова, вы можете выполнить интерактивный запрос или запустить набор запросов, чтобы создать набор результатов в формате SARIF и отправить результаты в GitHub.com. CLI CodeQL бесплатно для использования в общедоступных репозиториях, размещенных на GitHub.com, и он доступен для использования в частных репозиториях, находящихся в собственности пользователя, при наличии лицензии Advanced Security. Скачайте пакет CodeQL из https://github.com/github/codeql-action/releases.

Содержимое пакета:

продукт CodeQL CLI;
совместимая версия запросов и библиотек из https://github.com/github/codeql;
предварительно скомпилированные версии всех запросов, включенных в пакет.

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

Анализ сканирования кода с помощью GitHub Actions

Чтобы использовать GitHub Actions для отправки стороннего файла SARIF в репозиторий, необходим рабочий процесс GitHub Actions. Рабочий процесс GitHub Actions — это автоматизированный процесс, состоящий из одного или нескольких заданий, настроенных в виде файла .yml. Рабочие процессы хранятся в каталоге .github/workflows для вашего репозитория.

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

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

При этом можно настроить действие upload-sarif, которое будет выполняться при наступлении событий push и scheduled.

В этом примере описываются элементы upload-sarif файла yml действия:

name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
  sarif_file:
    description: |
      The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
      See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
      uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
      for information on the maximum number of results and maximum file size supported by code scanning.
    required: false
    default: '../results'
  checkout_path:
    description: "The path at which the analyzed repository was checked out. 
    Used to relativize any absolute paths in the uploaded SARIF file."
    required: false
    default: ${{ github.workspace }}
  token:
    default: ${{ github.token }}
  matrix:
    default: ${{ toJson(matrix) }}
  category:
    description: String used by Code Scanning for matching the analyses
    required: false
  wait-for-processing:
    description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
    required: true
    default: "false"
runs:
  using: 'node12'
  main: '../lib/upload-sarif-action.js'

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

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

Загрузка SARIF поддерживает максимум 5 000 результатов за один раз. Все результаты, превышающие это ограничение, игнорируются. Если средство создает слишком много результатов, следует обновить конфигурацию и сосредоточиться на результатах для наиболее важных правил или запросов.

Максимальный размер файла SARIF в архиве GZIP, поддерживаемый для каждой передачи, — 10 МБ. Любые отправки свыше этого ограничения будут отклонены. Если файл SARIF слишком большой, так как он содержит слишком много результатов, необходимо обновить конфигурацию, чтобы сосредоточиться на результатах для наиболее важных правил или запросов.

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

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

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

В дополнение к выполнению при отправке фиксаций запланировано выполнение рабочего процесса один раз в неделю. Этот рабочий процесс отправляет файл results.sarif, расположенный в корне репозитория. Вы также можете изменить этот рабочий процесс, чтобы передать каталог файлов SARIF. Например, можно поместить все файлы SARIF в каталог в корне репозитория с именем sarif-output и присвоить входному параметру действия sarif_file значение sarif-output.

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:
      security-events: write
  steps:
    # This step checks out a copy of your repository.
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        # Path to SARIF file relative to the root of the repository
        sarif_file: results.sarif

Отправка файлов SARIF, созданных в рамках рабочего процесса CI

Если вы создаете сторонний файл SARIF в рамках рабочего процесса непрерывной интеграции (CI), вы можете добавить действие upload-sarif в качестве шага после выполнения тестов CI. Если у вас еще нет рабочего процесса CI, его можно создать с помощью начального рабочего процесса в репозитории https://github.com/actions/starter-workflows.

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

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

  ```
  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:
      security-events: write
    steps:
      - uses: actions/checkout@v2
      - 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@v1
        with:
          // Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
  ```

Обратная связь

Были ли сведения на этой странице полезными?