Настройка анализа с помощью пакетов CodeQL

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

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

Прежде чем использовать CodeQL пакет запросов для анализа базы данных, необходимо скачать все необходимые пакеты из GitHubContainer registry. Это можно сделать с помощью флага --download``codeql database analyze в рамках команды или запуска codeql pack download. Если пакет не является публично доступным, для аутентификации потребуется использовать OR GitHub Apppersonal access token . Дополнительные сведения и пример см. в разделе Загрузка результатов анализа CodeQL на GitHub.

Option	Обязательный	Использование
`<scope/name@version:path>`		Укажите область и название одного или нескольких CodeQL пакетов запросов для скачивания с помощью списка, разделённого запятой. При необходимости включите версию для скачивания и распаковки. По умолчанию скачивается последняя версия пакета. При необходимости добавьте путь к запросу, каталогу или набору запросов для выполнения. Если путь не включен, выполните запросы этого пакета по умолчанию.
`--github-auth-stdin`		Передайте CLI GitHub App или personal access token созданную для аутентификации с GitHubпомощью REST API из вашего секретного хранилища через стандартный вход. Это не требуется, если команда имеет доступ к переменной среды `GITHUB_TOKEN`, заданной с помощью этого маркера.

Примечание.

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

Дополнительные сведения о совместимости пакетов см. в разделе Ссылка на пакеты запросов CodeQL.

Базовый пример загрузки и использования пакетов запросов

В этом примере выполняется команда codeql database analyze с параметром --download, чтобы:

Скачать последнюю версию пакета octo-org/security-queries.
Скачать версию octo-org/optional-security-queries пакета, которая была бы совместима с версией 1.0.1 (в данном случае это версия 1.0.2). Дополнительные сведения о совместимости SemVer см. в документации по семантическому диапазону версий npm.
Выполните все запросы по умолчанию в octo-org/security-queries.
Выполнение только запроса queries/csrf.ql из octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Прямое скачивание CodeQL пакетов

Если хотите скачать CodeQL пакет без запуска сразу, то можете использовать команду codeql pack download . Это полезно, если вы хотите избежать доступа в интернет при выполнении CodeQL запросов. При запуске CodeQL анализа вы можете указывать пакеты, версии и пути так же, как в предыдущем примере:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Скачивание CodeQL пакетов из нескольких GitHub реестров контейнеров

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

Указание, какие запросы выполнять в пакете CodeQL

Описатели запросов используются codeql database analyze и другими командами, которые работают с набором запросов. Полная форма описателя запроса:scope/name@range:path

scope/name — это квалифицированное название CodeQL стаи.
range — это диапазон semver.
path — это путь к одному запросу, каталогу с запросами или файлу набора запросов.

При указании scope/nameзначения range и path необязательными. Если опущена range последняя версия указанного пакета, используется. Если не указано, path используется набор запросов по умолчанию указанного пакета.

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

Если указать и то scope/name , и pathдругое path не может быть абсолютным. Он рассматривается относительно корня из CodeQL Стая.

Примеры описателей запросов

codeql/python-queries — Все запросы в наборе запросов по умолчанию последней codeql/python-queries версии пакета.
codeql/python-queries@1.2.3 — Все запросы в наборе запросов по умолчанию версии 1.2.3``codeql/python-queries пакета.
codeql/python-queries@~1.2.3 — Все запросы в наборе запросов по умолчанию последней версии codeql/python-queries пакета, >= 1.2.3 и < 1.3.0.
codeql/python-queries:Functions — Все запросы в каталоге в Functions последней codeql/python-queries версии пакета.
codeql/python-queries@1.2.3:Functions — Все запросы в каталоге Functions в версии 1.2.3 codeql/python-queries пакета.
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls — Все запросы в каталоге codeql-suites/python-code-scanning.qls в версии 1.2.3 codeql/python-queries пакета.
suites/my-suite.qls — все запросы в suites/my-suite.qls файле относительно текущего рабочего каталога.

Совет

Стандартный набор запросов CodeQL стандартных пакетов запросов — codeql-suites/<lang>-code-scanning.qls. Несколько других полезных наборов запросов также можно найти в каталоге codeql-suites каждого пакета. Например, codeql/cpp-queries пакет содержит следующие наборы запросов:

cpp-code-scanning.qls — Запросы сканирования стандартного кода для C++. Набор запросов по умолчанию для этого пакета.

* cpp-security-extended.qls — Запросы из набора по умолчанию cpp-code-scanning.qls для C++, а также запросы с более низкой степенью серьезности и точностью. * cpp-security-and-quality.qls — запросы из cpp-security-extended.qls, а также возможности обслуживания и запросов надежности.

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

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

Вы можете включить опубликованные наборы моделей в code scanning анализ с этой --model-packs опцией. Рассмотрим пример.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries

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

В анализе можно указать несколько опубликованных пакетов модели.

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

Сведения о опубликованных пакетах

При публикации пакета для использования в анализе codeql pack create или codeql pack publish команда проверяет, завершен ли содержимое, а также добавляет в него дополнительные фрагменты содержимого:

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

Большинство этих данных находятся в каталоге с именем .codeql в опубликованном пакете, но предварительно скомпилированные запросы находятся в файлах с суффиксом .qlx рядом с .ql источником для каждого запроса. При анализе базы данных с запросом из опубликованного пака загружаются CodeQL эти файлы вместо .ql исходного кода. Если необходимо изменить содержимое опубликованного __ пакета, обязательно удалите все .qlx файлы, так как они могут предотвратить изменения в .ql файлах.