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

Работа с CodeQL включёнными рюкзаками GitHub Enterprise Server

По умолчанию он CodeQL CLI ожидает скачивать CodeQL паки из и публиковать их на Container registryGitHub.com. Однако вы также можете работать с CodeQL паками в ON Container registryGitHub Enterprise Server , создав qlconfig.yml файл, который указывает CLI, какой Container registry использовать для каждого пака.

Создайте файл ~/.codeql/qlconfig.yml на Linux/MacOS или %HOMEPATH%\.codeql\qlconfig.yml на Windows с помощью предпочитаемого текстового редактора и добавьте записи, чтобы определить, какой реестр использовать для одного или нескольких шаблонов имён пакетов. Например, следующий qlconfig.yml файл связывает все пакеты с Container registry at https://GHE_HOSTNAME, кроме пакетов, совпадающих codeql/\* или организации other-org/* , которые связаны с Container registry на GitHub.com:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `https://GHE_HOSTNAME`
  url: https://containers.GHE_HOSTNAME/v2/

Они CodeQL CLI определяют, какой реестр использовать для заданного имени пакета, найдя первый элемент в registries списке с packages свойством, соответствующим именю этого пакета. Это означает, что сначала необходимо определить наиболее конкретные шаблоны имен пакета. Это packages свойство может быть одним именем пакета, шаблоном glOB-объектов или списком YAML имен пакетов и шаблонов глобов.

Список registries также можно поместить в codeql-workspace.yml файл. Это позволит вам определить реестры для использования в конкретном рабочем пространстве, чтобы их можно было делить между другими CodeQL пользователями. Список registries будет codeql-workspace.yml объединен и имеет приоритет над списком в глобальном qlconfig.ymlмасштабе. Дополнительные сведения см. в codeql-workspace.ymlразделе Сведения о рабочих областях CodeQL.

Теперь вы можете использовать codeql pack publish, , и codeql database analyze управлять пакетами на GitHub Enterprise Servercodeql pack download.

Аутентификация в GitHubContainer registries

Вы можете публиковать пакеты и скачать приватные пакеты, аутентифицировавшись по нужному GitHubContainer registry.

Аутентификация на Container registries on GitHub.com

Вы можете подтвердить Container registry подлинность двумя способами:

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

Аутентификация на Container registries on GitHub Enterprise Server

Аналогично, вы можете аутентифицироваться в a Container registry on GitHub Enterprise Server, или одновременно в нескольких реестрах (например, чтобы скачать или запустить приватные пакеты из нескольких реестров) двумя способами:

1. Передайте --registries-auth-stdin эту опцию в CodeQL CLI, затем введите строку аутентификации реестра через стандартный вход.
2. Задайте для переменной CODEQL_REGISTRIES_AUTH среды строку проверки подлинности реестра.

Строка аутентификации реестра — это список пар, разделённый <registry-url>=<token> по запятой, где registry-url — Container registry URL, например https://containers.GHE_HOSTNAME/v2/, а token — GitHub Apps токен, а personal access token для Container registryэтого . Это гарантирует, что каждый токен передаётся Container registry только указанному току.

Например, следующая строка аутентификации реестра указывает, что CodeQL CLI они должны аутентироваться следующим образом:

• Используйте токен <token1> для аутентификации на Container registry .GitHub.com
• Используйте токен <token2> для аутентификации для Container registry предприятия по адресу https://containers.GHE_HOSTNAME/v2/.

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>

Публикация вашего CodeQL пакета

Чтобы поделиться своим CodeQL пакетом с другими, вы можете опубликовать его на Container registry.

          `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>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: 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:` Следует следовать `<scope>/<pack>` формату, где `<scope>` находится GitHub организация, в которую вы будете публиковаться, и `<pack>` каково название пакета.
  

• Допускается не более одного или defaultSuite``defaultSuiteFile одного из них. Это два разных способа определения набора запросов по умолчанию, первый путем указания запросов непосредственно в файле qlpack.yml и второй путем указания набора запросов в пакете.

Бег codeql pack publish

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

codeql pack publish

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

Скачивание существующего CodeQL пака

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

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>