Создание и работа с пакетами CodeQL

О пакетах CodeQL и CodeQL CLI

Пакеты 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 pack add. Необходимо указать область, имя и (необязательно) совместимый диапазон версий.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Если диапазон версий не указан, будет добавлена последняя версия. В противном случае будет добавлена последняя версия, которая удовлетворяет запрошенному диапазону.

Эта команда обновляет qlpack.yml файл с запрошенными зависимостями и загружает их в кэш пакетов. Обратите внимание, что эта команда будет переформатировать файл и удалить все примечания.

Вы также можете вручную изменить qlpack.yml файл, чтобы включить зависимости и установить зависимости с помощью команды:

codeql pack install

Эта команда скачивает все зависимости в общий кэш на локальном диске.

Настройка скачанных пакетов CodeQL

Рекомендуемый способ экспериментировать с изменениями в пакете — клонировать репозиторий, содержащий исходный код.

Если исходный репозиторий недоступен, и вам нужно создать изменения в пакете, скачанном из Container registry, помните, что эти пакеты не предназначены для изменения или настройки после скачивания, и их формат может измениться в будущем без большого уведомления. Рекомендуется выполнить следующие действия после скачивания пакета, если необходимо изменить содержимое:

• Измените имя_ пакета_, qlpack.yml чтобы избежать путаницы с результатами из немодифицированного пакета.

• Удалите все файлы с именем *.qlx в любом месте в распаковке структуры каталогов. Эти файлы содержат предварительно скомпилированные версии запросов, а в некоторых ситуациях CodeQL будет использовать их в предпочтениях в источнике QL, который вы изменили.