Увімкнення сканування коду за допомогою засобів сторонніх постачальників

4 хв.

Замість сканування коду в GitHub ви можете виконати аналіз в іншому місці, а потім передати результати. Оповіщення про сканування коду, які ви запускаєте зовнішньо, відображаються так само, як і ті, які ви запускаєте в GitHub. Ви можете передавати файли формату змінних результатів статичного аналізу (SARIF), створені за межами GitHub, або за допомогою дій GitHub, щоб переглядати оповіщення про сканування коду зі сторонніх інструментів у сховищі.

У цій одиниці ви дізнаєтеся, як увімкнути сканування коду за допомогою засобів сторонніх постачальників і як використовувати та передавати файли SARIF.

Про передавання файлів SARIF для сканування коду

GitHub створює оповіщення про сканування коду у сховищі за допомогою інформації з файлів SARIF. Файли SARIF можна створювати за допомогою багатьох засобів перевірки статичного аналізу, зокрема CodeQL. Результати мають використовувати SARIF версії 2.1.0.

Результати можна передати за допомогою API сканування коду, CLI 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

CLI CodeQL – це автономний продукт, який можна використовувати для аналізу коду. Його основна мета – створити представлення бази даних кодової бази даних – бази даних CodeQL. Коли база даних буде готова, її можна надіслати в інтерактивному режимі або запустити набір запитів, щоб створити набір результатів у форматі SARIF і передати результати до GitHub.com. CLI CodeQL можна використовувати на загальнодоступних репозиторіях, які підтримуються в GitHub.com, і його можна використовувати для приватних сховищ, що належать клієнту, з ліцензією на розширену безпеку. Завантажте пакет CodeQL з https://github.com/github/codeql-action/releases.

Набір містить:

Продукт CLI codeQL
Сумісна версія запитів і бібліотек із https://github.com/github/codeql
Попередньо скомпільовані версії всіх запитів, включених до набору

Слід завжди використовувати набір CodeQL, оскільки це забезпечує сумісність, а також забезпечує набагато кращу продуктивність, ніж окреме завантаження CLI CodeQL і взяття на редагування запитів CodeQL.

Аналіз сканування коду за допомогою дій GitHub

Щоб передати сторонній файл SARIF до сховища за допомогою дій GitHub, знадобиться робочий цикл Дій GitHub. Робочий цикл Дій GitHub – це автоматизований процес, який складається з одного або кількох завдань, налаштованих як файл .yml. Робочі цикли зберігаються в каталозі .github/workflows для вашого сховища.

У робочому циклі використовується дія upload-sarif, яка входить до сховища github/codeql-action. Цей робочий цикл містить параметри вводу, які можна використовувати для настроювання передавання.

Основний параметр вводу – це sarif-file, який налаштовує файл або каталог файлів SARIF, які потрібно передати. Шлях до каталогу або файлу відносно кореня сховища.

Дію upload-sarif можна настроїти на запуск, коли відбувається подія push та scheduled.

У цьому прикладі описано елементи файлу yml upload-sarif дії:

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 підтримує не більше 5000 результатів для кожного завантаження. Будь-які результати, які перевищують це обмеження, ігноруються. Якщо засіб створює забагато результатів, слід оновити конфігурацію, щоб зосередитися на результатах для найважливіших правил або запитів.

Для кожного завантаження програма SARIF підтримує максимальний розмір 10 МБ для стиснутого файлу SARIF із gzip. Усі передавання через це обмеження буде відхилено. Якщо файл 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
  ```

Зворотний зв’язок

Чи була ця сторінка корисна?