Публикация и использование пакетов CodeQL

Настройка qlpack.yml файла перед публикацией

Перед публикацией можно проверить и изменить сведения о конфигурации пакета CodeQL. qlpack.yml Откройте файл в предпочитаемом текстовом редакторе.

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

• name: должен соответствовать формату / , где — GitHub, в которой будет опубликована организация, а — имя пакета.

• Допускается не более одного из значений default-suite или default-suite-file . Это два разных способа определения набора запросов по умолчанию для выполнения: первый — указание запросов непосредственно в файле qlpack.yml, а второй — указание набора запросов в пакете.

Работает codeql pack publish

Когда вы будете готовы опубликовать пакет в GitHub Container registry, можно выполнить следующую команду в корневом каталоге пакета:

codeql pack publish

Опубликованный пакет будет отображаться в разделе пакетов организации GitHub, указанной областью qlpack.yml в файле.

Работает codeql pack download <scope>/<pack>

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

codeql pack download <scope>/<pack>@x.x.x

• <scope>: имя организации GitHub, из которую вы будете скачивать данные.
• <pack>: имя пакета, который требуется скачать.
• @x.x.x: необязательный номер версии. Если этот параметр опущен, будет загружена последняя версия.

Эта команда принимает аргументы для нескольких пакетов.

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

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

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

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

• <database>: база данных CodeQL, для анализа.
• <scope>: имя организации GitHub, в которую публикуется пакет.
• <pack>: имя используемого пакета.
• @x.x.x: необязательный номер версии. Если этот параметр опущен, будет использоваться последняя версия.
• :<path>: необязательный путь к запросу, каталогу или набору запросов. Если этот параметр опущен, будет использоваться набор запросов пакета по умолчанию.

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

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>

Сведения о совместимости пакетов CodeQL

При публикации пакета запросов он включает предварительно скомпилированные представления всех запросов. Эти предварительно скомпилированные запросы обычно выполняются гораздо быстрее, чем компиляция источника QL с нуля во время анализа. Однако предварительно скомпилированные запросы также зависят от определенных внутренних компонентов средства оценки QL, поэтому, если версия CodeQL, выполняющая анализ, слишком отличается от версии, которая выполнялась codeql pack publish, во время анализа может потребоваться компилировать запросы из источника. Перекомпиляция выполняется автоматически и не влияет на результаты анализа, но может значительно замедлить анализ.

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

Можно также предположить, что пакет, опубликованный последним общедоступным выпуском CodeQL, будет использоваться версией CodeQL, используемой code scanning и GitHub Actions, хотя это часто немного более старый выпуск.

В качестве исключения из приведенного выше, пакеты, опубликованные с версиями CodeQL до 2.12.0 , несовместимы с более ранними или более поздними версиями. Эти старые версии не записывали предварительно скомпилированные запросы в формате, поддерживающем совместимость между выпусками. Пакеты, опубликованные этими версиями, по-прежнему могут использоваться более новыми версиями, но анализ будет выполняться медленнее, так как запросы необходимо сначала перекомпилировать.

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

[42/108] Loaded /long/path/to/query/Filename.qlx.

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

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

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

Если вы публикуете пакеты запросов в Container registry в GitHub.com для использования другими пользователями, рекомендуется использовать последний выпуск CodeQL для запуска codeql pack publishи опубликовать новую версию пакета с обновленной версией CodeQL до того, как используемая версия станет 6 месяцев. Таким образом, вы сможете гарантировать, что пользователи вашего пакета, которые хранят { % data variables.product.prodname_codeql %} в актуальном состоянии, получат преимущества от предварительно скомпилированных запросов в пакете.

Если вы публикуете пакеты запросов с намерением использовать их в установке GitHub Enterprise Server, которая использует пакетные двоичные файлы CodeQL, используйте ту же версию CodeQL для запуска codeql pack publish. Более новые версии могут создавать предварительно скомпилированные запросы, которые не распознаются в GitHub Enterprise Server. Администратор GitHub Enterprise Server может периодически обновляться до более новой версии CodeQL. Если да, следуйте их примеру.

Проверка подлинности в GitHub Container registries

Вы можете публиковать пакеты и скачивать частные пакеты, выполнив проверку подлинности в соответствующем GitHub Container registry.

Проверку подлинности в Container registry в GitHub.com можно выполнить двумя способами:

1. --github-auth-stdin Передайте параметр в CodeQL CLI, а затем предоставьте маркер GitHub Apps или personal access token через стандартные входные данные.
2. Задайте для переменной GITHUB_TOKEN среды маркер GitHub Apps или personal access token.