Параметры настройки рабочих процессов для сканирования кода

Необходимые условия

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

Примеры, приведённые в этой статье, относятся к файлу Рабочий процесс анализа CodeQL . По умолчанию этот файл определяется в .github/workflows/codeql-analysis.yml.

Частота сканирования

Вы можете настроить Рабочий процесс анализа CodeQL код для сканирования по расписанию или когда происходят определённые события в репозитории.

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

Проверка при принудительной отправке

По умолчанию Рабочий процесс анализа CodeQL он использует on:push это событие для запуска сканирования кода при каждом push-запросе на стандартную ветку репозитория и любые защищённые ветки. Чтобы code scanning процесс был активирован на определённой ветке, рабочий процесс должен существовать именно в этой ветке. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Если вы сканируете при push, результаты появляются во Security вкладке вашего репозитория. Дополнительные сведения см. в разделе Оценка оповещений сканирования кода для репозитория.

Кроме того, когда on:push проверка возвращает результаты, которые можно сопоставить с открытым запросом на вытягивание, эти оповещения будут автоматически отображаться в запросе на вытягивание в том же месте, что и другие оповещения о запросе на вытягивание. Оповещения определяются путем сравнения имеющихся результатов анализа заголовка ветви с результатами анализа целевой ветви. Для получения дополнительной информации о code scanning оповещениях в pull requests см. Рассмотрение оповещений проверки кода в запросах на вытягивание.

Сканирование запросов на вытягивание

По умолчанию Рабочий процесс анализа CodeQL это pull_request событие использует для запуска сканирования кода на pull request, направленных на стандартную ветку. Событие pull_request не запускается, если pull request был открыт из приватного форка.

Дополнительные сведения о событии pull_request см. в разделе События, инициирующие рабочие процессы.

При проверке запросов на вытягивание результаты отображаются в виде оповещений в результатах проверки запроса на вытягивание. Дополнительные сведения см. в разделе Рассмотрение оповещений проверки кода в запросах на вытягивание.

С помощью триггера pull_request , настроенного для проверки фиксации слияния запроса на вытягивание, а не головной фиксации, будут создаваться более эффективные и точные результаты, чем сканирование головы ветви на каждой отправке. Однако, если вы используете CI/CD-систему, которую нельзя настроить для запуска на pull request, вы всё равно можете использовать on:push триггер и code scanning назначить результаты на открытые pull requests на ветке и добавить оповещения в виде аннотаций в pull request. Дополнительные сведения см. в разделе "Сканирование при отправке".

Отключение ненужных сканирований запросов на вытягивание

Активацию проверки кода можно отключить для определенных запросов на вытягивание, предназначенных для ветви по умолчанию, независимо от того, какие файлы были изменены. Вы можете настроить это, указав on:pull_request:paths-ignore или on:pull_request:paths в рабочем code scanning процессе. Например, если единственными изменениями в запросе на вытягивание являются файлы с расширениями .md или .txt, можно использовать следующий массив paths-ignore.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

          `on:pull_request:paths-ignore` и `on:pull_request:paths` задают условия, определяющие, будут ли действия в рабочем процессе выполняться при запросе на вытягивание. Они не определяют, какие файлы будут анализироваться при _выполнении_ действий. Если запрос на вытягивание содержит все файлы, которые не соответствуют `on:pull_request:paths-ignore` или `on:pull_request:paths`, рабочий процесс выполняет действия и сканирует все файлы, измененные в запросе на вытягивание, включая те, которые совпадают с `on:pull_request:paths-ignore` или `on:pull_request:paths`, если файлы не были исключены. Сведения об исключении файлов из анализа см. в разделе ["Указание каталогов для сканирования](#specifying-directories-to-scan)".

Дополнительные сведения об использовании on:pull_request:paths-ignore и on:pull_request:paths определении того, когда рабочий процесс будет выполняться для запроса на вытягивание, см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Сканирование по расписанию

Если вы используете стандартную Рабочий процесс анализа CodeQLверсию, рабочий процесс будет сканировать код в вашем репозитории раз в неделю, помимо сканов, запускаемых событиями. Чтобы изменить это расписание, измените cron значение события on.schedule в рабочем процессе. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.

Пример

Следующий пример показывает a Рабочий процесс анализа CodeQL для конкретного репозитория, где по умолчанию вызывается ветка main и одна защищённая ветка под названием protected.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

Этот рабочий процесс проверяет:

• каждую отправку в ветвь по умолчанию и защищенную ветвь;
• каждый запрос на вытягивание в ветвь по умолчанию;
• ветвь по умолчанию каждый понедельник в 14:20 UTC.

Операционная система

• Code scanning кода Swift не поддерживается для runners, которые являются частью Actions Runner Controller (ARC), так как для выполнения ARC используется только Linux и Swift, требуются средства выполнения macOS. Тем не менее, вы можете иметь смесь как runners ARC, так и локальных модулей macOS runners. Дополнительные сведения см. в разделе Контроллер runner действий.

Если вашему коду требуется конкретная операционная система для компиляции, вы можете настроить её в Рабочий процесс анализа CodeQL. Отредактируйте значение, jobs.analyze.runs-on чтобы указать операционную систему для машины, на которой выполняются ваши code scanning действия. Операционную систему указывают, используя соответствующую метку как второй элемент в двухэлементном массиве после self-hosted.

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

          CodeQL
          code scanning поддерживает последние версии Ubuntu, Windows и macOS. Поэтому типичные значения для этого параметра: `ubuntu-latest`, `windows-latest` и `macos-latest`. Дополнительные сведения см. в разделе [AUTOTITLE и [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job)](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners).

          Вы должны убедиться, что Git находится в переменной PATH на ваших самохостированных раннерах. Дополнительные сведения см. в разделе [AUTOTITLE и [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).

Рекомендуемые спецификации (оперативная память, ядра процессора и диск) для анализа CodeQL см. Рекомендуемое оборудование для запуска CodeQL.

          CodeQL Расположение базы данных

В целом, вам не нужно беспокоиться о том, где находятся Рабочий процесс анализа CodeQLCodeQL базы данных, так как последующие шаги автоматически найдут базы, созданные предыдущими шагами. Однако, если вы пишете кастомный этап рабочего процесса, требующий размещения CodeQL базы данных в определённом месте диска, например, для загрузки базы данных как артефакта рабочего процесса, вы можете указать это место, используя db-location параметр под действием init .

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

Они Рабочий процесс анализа CodeQL ожидают, что указанный db-location путь будет записываемым, и либо не существует, либо будет пустой каталогом. При использовании этого параметра в задании, выполняющемся в локальном средстве выполнения или с помощью контейнера Docker, пользователь должен убедиться, что выбранный каталог очищается между запусками или что базы данных удаляются после того, как они больше не нужны. Это не обязательно для заданий, работающих на GitHub-hosted runners, которые каждый раз получают новый экземпляр и чистую файловую систему. Дополнительные сведения см. в разделе Средства выполнения тестов, размещенные в GitHub.

Если этот параметр не используется, база Рабочий процесс анализа CodeQL данных создаст в временном месте по своему выбору. В настоящее время значение по умолчанию — ${{ github.runner_temp }}/codeql_databases.

Языки, подлежащие анализу

          CodeQL
          code scanning Поддерживает код, написанный на следующих языках:

• C/C++
• C#
• Go
• Java и Kotlin
• JavaScript/TypeScript
• Python
• Ruby
• Rust (общедоступная предварительная версия)
• Swift

Дополнительные сведения см. в документации на веб-сайте CodeQL: поддерживаемые языки и платформы.

          CodeQL использует следующие языковые идентификаторы:

          `c` или `cpp` |

| C# | csharp | | | Go | go | | Java и Kotlin | java-kotlin | java или kotlin | | JavaScript/TypeScript | javascript-typescript | javascript или typescript | | Python | python | | Ruby | ruby | | | Rust (общедоступная предварительная версия) | rust | | | Swift | swift |

Эти идентификаторы языка можно использовать в качестве аргументов languages для ввода init действия. Рекомендуется предоставить только один язык в качестве аргумента:

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

Файл по умолчанию Рабочий процесс анализа CodeQL , созданный после настройки расширенной настройки для сканирования кода с помощью CodeQL , определяет матрицу с свойством, language которое перечисляет языки в вашем репозитории, которые будут анализироваться. Эта матрица автоматически заполняется поддерживаемыми языками, обнаруженными в репозитории. Использование матрицы language позволяет CodeQL выполнять анализ каждого языка параллельно и настраивать анализ под каждый язык. В отдельном анализе имя языка из матрицы предоставляется init действию в качестве аргумента входных languages данных. Рекомендуется использовать эту конфигурацию для всех рабочих процессов. Дополнительные сведения о матрицах см. в разделе Выполнение вариантов заданий в рабочем процессе.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

Если ваш рабочий процесс использует матрицу language , CodeQL то я анализирую только языки в матрице. Чтобы изменить языки, которые нужно проанализировать, измените конфигурацию матрицы. Вы можете удалить язык, чтобы предотвратить его анализ. Существует несколько причин, по которым может возникнуть желание запретить анализ языка. Например, проект может иметь зависимости на другом языке, чем основной код, и вы, возможно, предпочтете не видеть оповещения для этих зависимостей. Вы также можете добавить язык, который не был в репозитории при code scanning конфигурировании. Например, если репозиторий изначально содержал JavaScript только при code scanning конфигурировании, а позже вы добавили код на Python, вам придётся добавить python его в матрицу.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

Для скомпилированных языков матрицу можно также использовать для настройки режима сборки, который следует использовать для анализа, изменив значение build-mode свойства. Дополнительные сведения о режимах сборки см. в разделе Сканирование кода CodeQL для скомпилированных языков.

Если ваш рабочий процесс не даёт аргумента для languages ввода init действия, то CodeQL он настроен на последовательное выполнение анализов. В этом случае CodeQL автоматически обнаруживает и пытается проанализировать любые поддерживаемые языки в репозитории. В зависимости от размера репозитория и количества языков это может занять много времени. Если анализ для одного языка завершается сбоем в этом режиме, анализ для всех языков завершается ошибкой. Поэтому не рекомендуется использовать эту конфигурацию.

Степени оповещений о сбоях чеков

Вы можете использовать наборы правил, чтобы предотвратить объединение запросов на вытягивание при выполнении одного из следующих условий:

• Требуемый инструмент находит code scanning оповещение о тяжести, определённой в наборе правил.
• Анализ необходимого инструмента всё ещё продолжается.
• Требуемый инструмент не настроен для репозитория.

Дополнительные сведения см. в разделе Настройка защиты от сканирования кода слиянием. Дополнительные сведения о наборах правил см. в разделе Сведения о наборе правил.

Категория анализа

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

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

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

Если вы не укажете параметр category в вашем рабочем процессе, GitHub он сгенерирует для вас название категории на основе имени файла рабочего процесса, который запускает действие, имени действия и любых матричных переменных. Рассмотрим пример.

• Рабочий процесс .github/workflows/codeql-analysis.yml и действие analyze создают категорию .github/workflows/codeql.yml:analyze.
• Рабочий процесс .github/workflows/codeql-analysis.yml, действие analyze и переменные матрицы {language: javascript-typescript, os: linux} создают категорию .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux.

Значение category будет отображаться как свойство <run>.automationDetails.id в SARIF версии 2.1.0. Дополнительные сведения см. в разделе Поддержка SARIF для проверки кода.

Указанная категория не перезаписывает сведения об объекте runAutomationDetails в файле SARIF, если они включены.

          CodeQL Наборы моделей

Если ваша кодовая база зависит от библиотеки или фреймворка, которые не распознаются стандартными запросами в CodeQL, вы можете расширить CodeQL охват code scanning рабочего процесса, указав опубликованные CodeQL пакеты моделей. Дополнительные сведения о создании собственных пакетов моделей см. в разделе Создание и работа с пакетами CodeQL.

Использование CodeQL моделей пакетов

Чтобы добавить один или несколько опубликованных CodeQL наборов моделей, укажите их внутри with: packs: записи в uses: github/codeql-action/init@v4 разделе рабочего процесса. В packs укажите один или несколько пакетов для использования и (необязательно) версию для загрузки. Если не указать версию, загружается последняя версия. Если вы хотите использовать пакеты, которые не являются общедоступными, необходимо задать для переменной среды GITHUB_TOKEN секрет, имеющий доступ к пакетам. Дополнительные сведения см. в разделе [AUTOTITLE и Использование GITHUB_TOKEN для проверки подлинности в рабочих процессах](/actions/security-guides/encrypted-secrets).

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

В этом примере по умолчанию будут выполняться запросы для Java, а также запросы из версии, превышающей или равную 7.8.9 и меньше 7.9.0 пакета запросов my-company/my-java-queries. Зависимости, моделиированные в последней версии пакета my-repo/my-java-model-pack модели, будут доступны как для запросов по умолчанию, так и для тех, в которых они есть my-company/my-java-queries.

Нестандартные запросы

При использовании CodeQL для проверки кода подсистема анализа CodeQL создает базу данных из кода и выполняет запросы к нему. Анализ CodeQL использует набор запросов по умолчанию, но в дополнение к ним можно указать дополнительные запросы для выполнения.

Можно выполнять дополнительные запросы, если они являются частью пакета CodeQL, опубликованного в пакете GitHub Container registry или пакет CodeQL , хранящийся в репозитории. Дополнительные сведения см. в разделе О проверке кода с помощью CodeQL.

Параметры, которые можно использовать для указания дополнительных запросов:

• packs чтобы установить один или несколько пакетов запросов CodeQL и запустить набор запросов по умолчанию или запросы для этих пакетов.
• queries для указания одного файла .ql, каталога, содержащего несколько файлов .ql, файла определения набора запросов .qls или любого их сочетания. Дополнительные сведения об определениях набора запросов см. в статье "Создание наборов запросов CodeQL наборов запросов.

В одном рабочем процессе можно использовать как packs, так и queries.

Использование пакетов запросов

Чтобы добавить один или несколько CodeQL пакетов запросов, добавьте with: packs: запись в uses: github/codeql-action/init@v4 разделе рабочего процесса. В packs укажите один или несколько пакетов для использования и (необязательно) версию для загрузки. Если не указать версию, загружается последняя версия. Если вы хотите использовать пакеты, которые не являются общедоступными, необходимо задать для переменной среды GITHUB_TOKEN секрет, имеющий доступ к пакетам. Дополнительные сведения см. в разделе [AUTOTITLE и Использование GITHUB_TOKEN для проверки подлинности в рабочих процессах](/actions/security-guides/encrypted-secrets).

В указанном ниже примере scope является организация или личная учетная запись, которая опубликовала пакет. Когда рабочий процесс запускается, из которых загружаются четыре CodeQL пакета GitHub запросов, и выполняется стандартный набор запросов или набор запросов для каждого пакета:

• Будет скачана последняя версия pack1 с выполнением всех запросов по умолчанию.
• Будет скачана версия 1.2.3 для pack2 с выполнением всех запросов по умолчанию.
• Будет скачана последняя версия pack3, которая совместима с версией 3.2.1, с выполнением всех запросов.
• Будет скачана версия 4.5.6 для pack4 с выполнением только тех запросов, которые обнаружены в path/to/queries.

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/[email protected],scope/pack3@~3.2.1,scope/[email protected]:path/to/queries

Скачивание CodeQL паков из GitHub Enterprise Server

Если ваш рабочий процесс использует паки, опубликованные на GitHub Enterprise Server установке, вам нужно указать процессу, где их найти. Это можно сделать, используя registries ввод github/codeql-action/init@v4 действия. Этот вход принимает список urlсвойств packages, token как показано ниже.

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

Шаблоны пакетов в списке реестров проверяются по порядку, поэтому обычно следует сначала разместить наиболее конкретные шаблоны пакетов. Значения должны token быть personal access token (classic) сгенерированы экземпляром GitHub, с которого вы скачиваете с разрешением read:packages .

Обратите внимание на имя |``registries свойства. Это важно, поскольку GitHub Actions входы могут принимать только строки. Использование | этого преобразует следующий текст в строку, которая позже анализируется действием github/codeql-action/init@v4 .

Использование запросов в пакетах QL

Чтобы добавить один или несколько запросов, добавьте запись with: queries: в раздел uses: github/codeql-action/init@v4 рабочего процесса. Если запросы находятся в частном репозитории, используйте параметр external-repository-token, чтобы указать маркер, имеющий доступ для извлечения частного репозитория.

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

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Следующие наборы запросов встроены в CodeQL code scanning и доступны для использования.

Дополнительные сведения см. в статье AUTOTITLE.

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

При указании набора запросов обработчик анализа CodeQL будет выполнять набор запросов по умолчанию и все дополнительные запросы, определенные в дополнительном наборе запросов.

Работа с пользовательскими файлами конфигурации

При использовании файла конфигурации для пользовательских параметров применяются любые дополнительные пакеты или запросы, указанные в рабочем процессе, вместо запросов, указанных в файле конфигурации. Если вы хотите запустить объединенный набор дополнительных пакетов или запросов, префиксировать значение packs или queries в рабочем процессе с помощью символа + . Для получения дополнительной информации см. раздел «Пользовательские конфигурационные файлы».

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

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/[email protected],scope/[email protected]:path/to/queries

Пользовательские конфигурационные файлы

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

Используйте в файле рабочего процесса параметр config-file действия init, чтобы указать путь к файлу конфигурации, который необходимо использовать. В этом примере загружается файл конфигурации ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml

Файл конфигурации может находиться в репозитории, который вы анализируете, или во внешнем репозитории. Использование внешнего репозитория позволяет задавать параметры конфигурации для нескольких репозиториев в одном месте. При ссылке на файл конфигурации, расположенный во внешнем репозитории, можно использовать синтаксис OWNER/REPOSITORY/FILENAME@BRANCH. Например, octo-org/shared/codeql-config.yml@main.

Если файл конфигурации находится во внешнем частном репозитории, используйте параметр external-repository-token действия init, чтобы указать маркер, имеющий доступ к частному репозиторию.

- uses: github/codeql-action/init@v4
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Параметры в файле конфигурации записываются в формате YAML.

Определение CodeQL пакетов запросов

Вы задаёте CodeQL пакеты запросов в массиве. Обратите внимание, что формат отличается от формата, используемого файлом рабочего процесса.

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/[email protected]
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

Полный формат для указания пакета запросов:scope/name[@version][:path]. version и path являются необязательными. version — это диапазон версий SemVer. Если он отсутствует, используется последняя версия. Дополнительные сведения о диапазонах SemVer см. в документации SemVer по npm.

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

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/[email protected]

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/[email protected]

Расширение CodeQL покрытия с помощью моделей угроз

Модель угроз по умолчанию включает удаленные источники ненадежных данных. Вы можете расширить CodeQL модель угроз, включив локальные источники ненадёжных данных (например: аргументы командной строки, переменные среды, файловые системы и базы данных), указав threat-models: local это в пользовательском конфигурационном файле. При расширении модели угроз также будет использоваться модель угроз по умолчанию.

Указание дополнительных запросов

Дополнительные запросы задаются в массиве queries. Каждый элемент массива содержит параметр uses, имеющий значение, определяющее отдельный файл запроса, каталог, содержащий файлы запросов, или файл определения набора запросов.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

При необходимости можно присвоить каждому элементу массива имя, как показано в примере файлов конфигурации ниже. Для получения дополнительной информации о дополнительных запросах см. выше раздел «Нестандартные запросы ».

Отключение запросов по умолчанию

Если требуется выполнить только пользовательские запросы, можно отключить запросы безопасности по умолчанию с помощью disable-default-queries: true.

Исключение конкретных запросов из анализа

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

Это полезно, если вы хотите исключить, например:

• Конкретные запросы из наборов по умолчанию (security, security-extended иsecurity-and-quality).
• Конкретные запросы, результаты которых вас не интересуют.
• Все запросы, которые создают предупреждения и рекомендации.

Вы можете использовать фильтры exclude, как в приведенном ниже файле конфигурации, чтобы исключить запросы, которые требуется удалить из анализа по умолчанию. В приведенном ниже примере файла конфигурации запросы js/redundant-assignment и js/useless-assignment-to-local исключаются из анализа.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Чтобы найти идентификатор запроса, можно нажать на уведомление в списке оповещений на вкладке Security . Это открывает страницу с деталями оповещения. Поле Rule ID содержит идентификатор запроса. Дополнительные сведения о странице сведений об оповещении см. в разделе О предупреждениях о сканировании кода.

В разделе "Примеры файлов конфигурации" можно найти еще один пример использования этих фильтров.

Дополнительные сведения об использовании exclude и include фильтрации в пользовательском файле конфигурации см. в разделе Создание наборов запросов CodeQL. Сведения о метаданных запроса, которые можно отфильтровать, см. в разделе Метаданные запросов CodeQL.

Указание каталогов для сканирования

Когда кодовые базы анализируются без создания кода, можно ограничить code scanning их файлами в определённых каталогах, добавив paths массив в конфигурационный файл. Вы также можете исключить файлы в определенных каталогах из анализа, добавив paths-ignore массив. Эту опцию можно использовать при запуске CodeQL действий на интерпретируемом языке (Python, Ruby, JavaScript/TypeScript) или при анализе скомпилированного языка без создания кода (в настоящее время поддерживается для Java).

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Для анализа, где строится код, если вы хотите ограничиться code scanning конкретными каталогами в проекте, необходимо указать соответствующие этапы сборки в рабочем процессе. Команды, которые необходимо использовать для исключения каталога из сборки, зависят от системы сборки. Дополнительные сведения см. в разделе Сканирование кода CodeQL для скомпилированных языков.

При изменении кода в конкретных каталогах можно быстро анализировать небольшие части монорепозитория. Необходимо исключить каталоги на этапах сборки, а также использовать ключевые слова paths-ignore и paths для on.<push|pull_request> в рабочем процессе.

Примеры файлов конфигурации

Этот файл конфигурации добавляет набор запросов security-and-quality в список запросов, выполняемых CodeQL при сканировании кода. Для получения дополнительной информации о доступных наборах запросов см. раздел «Нестандартные запросы».

name: "My CodeQL config"

queries:
  - uses: security-and-quality

Следующий файл конфигурации отключает запросы по умолчанию и задает набор пользовательских запросов для выполнения. Он также настраивает CodeQL на сканирование файлов в каталоге src (относительно корневого каталога), кроме каталога src/node_modules и кроме файлов, имя которых заканчивается на .test.js. Поэтому файлы в папке src/node_modules и файлы с именами, заканчивающимися на .test.js, исключаются из анализа.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Следующий файл конфигурации выполняет только запросы, которые создают оповещения об ошибке. Сначала конфигурация выбирает все запросы по умолчанию, все запросы в ./my-queries и набор по умолчанию в codeql/java-queries, а затем исключает все запросы, которые создают предупреждения или рекомендации.

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Детали конфигурации

Если вы хотите указать дополнительные детали конфигурации в файле рабочего процесса, вы можете использовать config ввод init команды действия CodeQL . Значение этого входа должно быть строкой YAML, соответствующей формату конфигурационного файла, указанному в разделе Пользовательские конфигурационные файлы выше.

Пример конфигурации

Этот шаг в GitHub Actions файле рабочего процесса использует config вход для отключения стандартных запросов, добавления security-extended набора запросов и исключения запросов с тегом cwe-020.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

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

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

Компилированные языки

Для скомпилированных языков можно решить, как CodeQL действие создаёт CodeQL базу данных для анализа. Сведения о доступных параметрах сборки см. в разделе Сканирование кода CodeQL для скомпилированных языков.

Отправка данных

          GitHub может отображать данные анализа кода, созданные внешне сторонним инструментом. Вы можете загрузить данные анализа кода с помощью действия `upload-sarif`. Дополнительные сведения см. в разделе [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).