Настройка рабочего процесса проверки кода с помощью CodeQL. Часть 1

  • 10 мин

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

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

Вы можете выполнять дополнительные запросы, если они входят в пакет CodeQL (бета-версия), опубликованный в реестре контейнеров GitHub, или пакет QL, хранящийся в репозитории.

Существует два варианта указания запросов, которые необходимо выполнить с помощью проверки кода CodeQL:

  • Использование рабочего процесса проверки кода
  • Использование пользовательского файла конфигурации

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

Указание дополнительных запросов в файле рабочего процесса

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

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

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

Мы не рекомендуем ссылаться на наборы запросов непосредственно из репозитория github/codeql, например github/codeql/cpp/ql/src@main. Такие запросы могут не компилироваться с той же версией CodeQL, которая используется для других запросов, что может привести к ошибкам при анализе.

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

Примечание.

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

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

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

  • Последняя версия pack1 скачана, и выполняются все запросы по умолчанию.
  • Версия 1.2.3 pack2 загружена, и выполнены все запросы по умолчанию.
  • Последняя версия pack3 , совместимая с версией 3.2.1, загружается и выполняются все запросы.
  • Загружена версия 4.5.6 pack4, и выполняются только запросы, найденные в path/to/queries.
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Примечание.

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

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

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

- uses: github/codeql-action/init@v3
  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 }}

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

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

Пакет запросов Описание
security-extended Запросы из набора по умолчанию, а также запросы с более низкой степенью серьезности и точности
security-and-quality Запросы из security-extended, а также запросы касательно удобства обслуживания и надежности

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

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

Объединение запросов из файла рабочего процесса и пользовательского файла конфигурации

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

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

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries