О пакетах CodeQL и CodeQL CLI
Примечание. В этой статье описываются функции, доступные в пакете CodeQL CLI 2.13.5 в первоначальном выпуске GitHub Enterprise Server 3.10.
Если администратор сайта обновил версию CodeQL CLI до более новой версии, ознакомьтесь с версией GitHub Enterprise Cloud этой статьи, чтобы узнать о последних функциях.
Пакеты CodeQL используются для создания, совместного использования, зависимости и запуска CodeQL запросов и библиотек. Пакеты CodeQL содержат запросы, файлы библиотеки, наборы запросов и метаданные. С помощью пакетов CodeQL и команд управления пакетами в CodeQL CLIможно опубликовать пользовательские запросы и интегрировать их в анализ базы кода.
Существуют два типа пакетов CodeQL пакетов: пакетов запросов и пакетов библиотек.
-
Пакеты запросов предназначены для запуска. При публикации пакета запросов пакет включает все транзитивные зависимости и предварительно скомпилированные представления каждого запроса в дополнение к источникам запросов. Это обеспечивает согласованное и эффективное выполнение запросов в пакете.
-
Пакеты библиотек предназначены для использования пакетами запросов (или другими пакетами библиотек) и не содержат сами запросы. Библиотеки не компилируются отдельно.
Команду в CodeQL CLI можно использовать pack
для создания пакетов CodeQL и добавления зависимостей в пакеты и установки или обновления зависимостей. Вы также можете публиковать и скачивать пакеты CodeQL с помощью pack
команды. Дополнительные сведения см. в разделе Публикация и использование пакетов CodeQL.
Дополнительные сведения о совместимости между опубликованными пакетами запросов и различными выпусками CodeQL см. в разделе "Публикация и использование пакетов CodeQL".
Стандартные пакеты данных CodeQL для всех поддерживаемых языков публикуются в Container registry. Репозиторий CodeQL содержит исходные файлы для стандартных пакетов CodeQL для всех поддерживаемых языков. Основные пакеты запросов, включенные в пакет CLI CodeQL, но в противном случае можно скачать:
codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
Структура пакета CodeQL
Пакет CodeQL должен содержать файл, который вызывается qlpack.yml
в корневом каталоге. qlpack.yml
В файле name:
поле должно иметь значение, которое соответствует формату <scope>/<pack>
, где <scope>
находится организация GitHub или учетная запись пользователя, в которую будет опубликован пакет, и <pack>
имя пакета. Кроме того, пакеты запросов и пакеты библиотек с тестами CodeQL содержат codeql-pack.lock.yml
файл, содержащий разрешенные зависимости пакета. Этот файл создается во время вызова codeql pack install
команды, не предназначен для редактирования вручную и должен быть добавлен в систему управления версиями.
Другие файлы и каталоги в пакете должны быть логически упорядочены. Например, обычно:
-
Запросы упорядочены в каталоги для конкретных категорий.
-
Запросы для конкретных продуктов, библиотек и платформ упорядочены в собственные каталоги верхнего уровня.
Создание пакета данных CodeQL
Вы можете создать пакет CodeQL, выполнив следующую команду из корневого каталога проекта:
codeql pack init <scope>/<pack>
Необходимо указать следующие данные:
-
<scope>
: имя организации или учетной записи пользователя GitHub, в которую вы будете публиковаться. -
<pack>
: имя создаваемого пакета.
Команда codeql pack init
создает файлы структуры каталогов и конфигурации для пакета CodeQL. По умолчанию команда создает пакет запросов. Если вы хотите создать пакет библиотеки, необходимо изменить qlpack.yml
файл, чтобы явно объявить файл как пакет библиотеки, включив library:true
свойство.
Добавление и установка зависимостей в пакете CodeQL
Примечание. Это поддерживается только для пакетов запросов и библиотек CodeQL.
Можно добавить зависимости от пакетов CodeQL с помощью команды codeql pack add
. Необходимо указать область, имя и (необязательно) совместимый диапазон версий.
codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>
Если диапазон версий не указан, будет добавлена последняя версия. В противном случае будет добавлена последняя версия, которая удовлетворяет запрошенному диапазону.
Эта команда обновляет qlpack.yml
файл с запрошенными зависимостями и загружает их в кэш пакетов. Обратите внимание, что эта команда будет переформатировать файл и удалить все примечания.
Вы также можете вручную изменить qlpack.yml
файл, чтобы включить зависимости и установить зависимости с помощью команды:
codeql pack install
Эта команда скачивает все зависимости в общий кэш на локальном диске.
Примечания:
-
codeql pack add
Выполнение командcodeql pack install
приведет к созданию или обновлениюcodeql-pack.lock.yml
файла. Этот файл должен быть установлен на элемент управления версиями. Файлcodeql-pack.lock.yml
содержит точные номера версий, используемые пакетом. Дополнительные сведения см. в разделе "Сведения о файлах codeql-pack.lock.yml". -
По умолчанию
codeql pack install
будут установлены зависимости от Container registry для GitHub.com. Зависимости можно установить из GitHub Enterprise Server Container registry путем созданияqlconfig.yml
файла. Дополнительные сведения см. в разделе "Публикация и использование пакетов CodeQL" в документации по GitHub Enterprise Server.
Настройка скачанных пакетов CodeQL
Рекомендуемый способ экспериментировать с изменениями в пакете — клонировать репозиторий, содержащий исходный код.
Если исходный репозиторий недоступен, и вам нужно создать изменения в пакете, скачанном из Container registry, помните, что эти пакеты не предназначены для изменения или настройки после скачивания, и их формат может измениться в будущем без большого уведомления. Рекомендуется выполнить следующие действия после скачивания пакета, если необходимо изменить содержимое:
-
Измените имя_ пакета_,
qlpack.yml
чтобы избежать путаницы с результатами из немодифицированного пакета. -
Удалите все файлы с именем
*.qlx
в любом месте в распаковке структуры каталогов. Эти файлы содержат предварительно скомпилированные версии запросов, а в некоторых ситуациях CodeQL будет использовать их в предпочтениях в источнике QL, который вы изменили.