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

Примечание: Эта статья была перенесена с веб-сайта документации CodeQL в январе 2023 г.

Примечание: Функции управления пакетами CodeQL, включая пакеты CodeQL, в настоящее время доступны в виде бета-версии и могут быть изменены. Во время бета-версии пакеты CodeQL доступны только с помощью пакетов GitHub — Container registry. Чтобы использовать эту бета-версию, установите последнюю версию пакета CodeQL CLI из: https://github.com/github/codeql-action/releases.

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

Существует два типа пакетов CodeQL: пакеты запросов и пакеты библиотек.

Пакеты запросов предназначены для выполнения. При публикации пакета запросов пакет включает все транзитивные зависимости и предварительно скомпилированные представления , а также источники запросов. Это обеспечивает согласованное и эффективное выполнение запросов в пакете.
Пакеты библиотек предназначены для использования пакетами запросов (или другими пакетами библиотек) и не содержат сами запросы. Библиотеки не компилируются отдельно.

Команды управления пакетами в CodeQL CLI можно использовать для создания пакетов CodeQL, добавления зависимостей в пакеты, а также установки или обновления зависимостей. Дополнительные сведения см. в разделе Создание пакетов CodeQL и работа с ними. Вы также можете публиковать и скачивать пакеты CodeQL с помощью CodeQL CLI. Дополнительные сведения см. в разделе Публикация и использование пакетов CodeQL.

Стандартные пакеты CodeQL для всех поддерживаемых языков публикуются в Container registry. Репозиторий CodeQL содержит исходные файлы стандартных пакетов CodeQL для всех поддерживаемых языков.

Структура пакета CodeQL

Пакет CodeQL должен содержать файл с именем qlpack.yml в корневом каталоге. qlpack.yml В файле поле должно иметь значение в name: формате <scope>/<pack>, где <scope> — это GitHub организации или учетной записи пользователя, в которой будет опубликован пакет, а <pack> — имя пакета. Кроме того, пакеты запросов и пакеты библиотек с тестами CodeQL содержат codeql-pack.lock.yml файл, содержащий разрешенные зависимости пакета. Этот файл создается во время вызова codeql pack install команды, не предназначен для редактирования вручную и должен быть добавлен в систему управления версиями.

Другие файлы и каталоги в пакете должны быть логически упорядочены. Например, обычно:

Запросы упорядочены в каталоги для конкретных категорий.
Запросы для конкретных продуктов, библиотек и платформ упорядочены в собственные каталоги верхнего уровня.

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

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

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

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

Сведения о `qlpack.yml` файлах

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

Метаданные в каждом qlpack.yml файле сообщают CodeQL о том, как скомпилировать все запросы в пакете, от каких библиотек зависит пакет и где найти определения наборов запросов.

Содержимое пакета CodeQL (запросы или библиотеки, используемые в анализе CodeQL) включается в тот же каталог, что qlpack.ymlи , или его подкаталоги.

Каталог, содержащий файл, qlpack.yml служит корневым каталогом для содержимого пакета CodeQL. То есть для всех .ql файлов и .qll в пакете CodeQL разрешает все инструкции импорта относительно каталога, содержащего qlpack.yml файл в корневом каталоге пакета.

`qlpack.yml` Вариантов размещения

В файлах поддерживаются qlpack.yml следующие свойства.

`name`

Требуется для всех пакетов.
Определяет область пакета, в котором публикуется пакет CodeQL, и имя пакета, определенное с помощью буквенно-цифровых символов и дефисов. Он должен быть уникальным, так как CodeQL не может различать пакеты CodeQL с одинаковыми именами. Используйте имя пакета, чтобы указать запросы для выполнения с помощью database analyze и определить зависимости между пакетами CodeQL (см. примеры ниже). Пример:
```
name: octo-org/security-queries
```

`version`

Требуется для всех опубликованных пакетов.
Определяет семантику версии для этого пакета CodeQL, которая должна соответствовать спецификации SemVer версии 2.0.0. Пример:
```
version: 0.0.0
```

`dependencies`

Требуется для пакетов, определяющих зависимости пакета CodeQL от других пакетов.
Определяет сопоставление ссылок на пакеты с семантического диапазона версий, совместимого с этим пакетом. Поддерживается для CodeQL CLI версии 2.6.0 и более поздних версий. Пример:
```
dependencies:
  codeql/cpp-all: ^0.0.2
```

`defaultSuiteFile`

Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.
Определяет путь к файлу набора запросов относительно корневого каталога пакета, содержащего все запросы, которые выполняются по умолчанию при передаче этого пакета в codeql database analyze команду . Поддерживается в CLI версии 2.6.0 и более поздних версий. Можно определить только одно из значений defaultSuiteFile или defaultSuite . Пример:
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.
Определяет встроенный набор запросов, содержащий все запросы, которые выполняются по умолчанию при передаче этого пакета в codeql database analyze команду. Поддерживается в CLI версии 2.6.0 и более поздних версий. Можно определить только одно из значений defaultSuiteFile или defaultSuite . Пример:
```
defaultSuite:
  queries: .
  exclude:
    precision: medium
```

`library`

Требуется для пакетов библиотеки.
Определяет логическое значение, указывающее, является ли этот пакет пакетом библиотеки. Пакеты библиотек не содержат запросов и не компилируются. Пакеты запросов могут игнорировать это поле или явно задать для него значение false. Пример:
```
library: true
```

`suites`

Необязательно для пакетов, определяющих наборы запросов.
Определяет путь к каталогу в пакете, который содержит наборы запросов, которые необходимо сделать известными CodeQL CLI, определенному относительно каталога пакета. Пользователи пакета CodeQL могут запускать "хорошо известные" наборы, хранящиеся в этом каталоге, указав имя пакета, не указывая полный путь. Это не поддерживается для пакетов CodeQL, скачанных из реестра контейнеров. Дополнительные сведения о наборах запросов см. в разделе Создание наборов запросов CodeQL. Пример:
```
suites: octo-org-query-suites
```

`tests`

Необязательно для пакетов, содержащих тесты CodeQL. Игнорируется для пакетов без тестов.
Определяет путь к каталогу в пакете, который содержит тесты, определенный относительно каталога пакета. Используйте . , чтобы указать весь пакет. Все запросы в этом каталоге выполняются как тесты при test run выполнении с параметром --strict-test-discovery . Эти запросы игнорируются определениями наборов запросов, которые используют queries или qlpack инструкции для запроса всех запросов в определенном пакете. Если это свойство отсутствует, то . предполагается. Пример:
```
tests: .
```

`extractor`

Требуется для всех пакетов, содержащих тесты CodeQL.
Определяет средство извлечения языка CodeQL, используемое при выполнении тестов CodeQL в пакете. Дополнительные сведения о тестировании запросов см. в разделе Тестирование пользовательских запросов. Пример:
```
extractor: javascript
```

`authors`

Необязательный элемент.
Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL. Пример:
```
authors: author1@github.com,author2@github.com 
```

`license`

Необязательный элемент.
Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL. Список разрешенных лицензий см. в разделе Список лицензий SPDX в спецификации SPDX. Пример:
```
license: MIT
```

`description`

Необязательный элемент.
Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL. Пример:
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

Необязательный, нерекомендуемый. Вместо этого следует использовать свойство dependencies.
Ранее использовался для определения имен любых пакетов CodeQL, от которые зависит этот пакет CodeQL, в виде массива. Это предоставляет пакету доступ к любым библиотекам, схемам базы данных и наборам запросов, определенным в зависимости. Пример:
```
libraryPathDependencies: codeql/javascript-all 
```

`dbscheme`

Требуется только для основных языковых пакетов.
Определяет путь к схеме базы данных для всех библиотек и запросов, написанных для этого языка CodeQL (см. пример ниже). Пример:
```
dbscheme: semmlecode.python.dbscheme
```

`upgrades`

Требуется только для основных языковых пакетов.
Определяет путь к каталогу в пакете, который содержит скрипты обновления базы данных, определенный относительно каталога пакета. Обновления базы данных используются для обеспечения совместимости базы данных, созданной с другой версией CodeQL CLI, с текущей версией интерфейса командной строки. Пример:
```
upgrades: .
```

`warnOnImplicitThis`

Необязательный элемент. По умолчанию имеет значение , false если warnOnImplicitThis свойство не определено.
Определяет логическое значение, указывающее, должен ли компилятор выдавать предупреждения о вызовах предиката членов с неявными this приемниками вызовов, то есть без явного получателя. Поддерживается с CodeQL CLI версии 2.13.2 и более поздних версий. Пример:
```
warnOnImplicitThis: true
```

Сведения о `codeql-pack.lock.yml` файлах

codeql-pack.lock.yml в файлах хранятся версии разрешенных транзитивных зависимостей пакета CodeQL. Этот файл создается командой , codeql pack install если он еще не существует и должен быть добавлен в систему управления версиями. Раздел dependencies qlpack.yml файла содержит диапазоны версий, совместимые с пакетом. Файл codeql-pack.lock.yml блокирует версии для точных зависимостей. Это гарантирует, что при выполнении codeql pack install этого пакета всегда будут извлекаться одни и те же версии зависимостей, даже если существуют более новые совместимые версии.

Например, если qlpack.yml файл содержит следующие зависимости:

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

Файл codeql-pack.lock.yml будет содержать примерно следующее:

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

Зависимость codeql/cpp-all заблокирована до версии 0.1.4. Зависимость my-user/my-lib заблокирована до версии 0.2.1. , my-user/transitive-dependencyкоторый является транзитивной зависимостью и не указан в qlpack.yml файле, заблокирован до версии 1.2.4. отсутствует other-dependency/from-source в файле блокировки, так как он разрешается из источника. Эта зависимость должна быть доступна в той же рабочей области CodeQL, что и пакет. Дополнительные сведения о рабочих областях CodeQL и разрешении зависимостей из источника см. в разделе Сведения о рабочих областях CodeQL.

В большинстве случаев файл относится только к пакетам запросов, codeql-pack.lock.yml так как пакеты библиотек не являются исполняемыми и обычно не нуждаются в исправлении их транзитивных зависимостей. Исключением являются пакеты библиотек, содержащие тесты. В этом случае файл используется для проверки того, codeql-pack.lock.yml что тесты всегда выполняются с одинаковыми версиями зависимостей, чтобы избежать ложных сбоев при наличии несовпадения зависимостей.

Примеры пользовательских пакетов CodeQL

При написании пользовательских запросов или тестов их следует сохранять в пользовательских пакетах CodeQL. Для простоты попробуйте логически упорядочить каждый пакет. Дополнительные сведения см. в разделе Структура пакета CodeQL. Сохраняйте файлы для запросов и тестов в отдельных пакетах и, по возможности, упорядочивайте пользовательские пакеты в определенные папки для каждого целевого языка. Это особенно полезно, если вы планируете опубликовать пакеты CodeQL, чтобы их можно было поделиться с другими пользователями или использовать при сканировании кода. Дополнительные сведения см. в разделе О проверке кода с помощью CodeQL.

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

Пользовательский пакет CodeQL, содержащий пользовательские библиотеки C++ без запросов или тестов, может содержать файл, qlpack.yml содержащий:

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

где codeql/cpp-all — имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон ^0.1.2 версий указывает, что этот пакет совместим со всеми версиями codeql/cpp-all , которые больше или равны 0.1.2 и меньше 0.2.0. Любой файл библиотеки CodeQL (файл с расширением .qll ), определенный в этом пакете, будет доступен для запросов, определенных в любом пакете запросов, который включает этот пакет в блок зависимостей.

Свойство library указывает, что этот пакет является пакетом библиотеки и не содержит никаких запросов.

Пакеты CodeQL для пользовательских запросов

Пользовательский пакет CodeQL, содержащий пользовательские запросы и библиотеки C++, может содержать файл, qlpack.yml содержащий:

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3
suites: my-custom-suites

где codeql/cpp-all — имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон ^0.1.2 версий указывает, что этот пакет совместим со всеми версиями codeql/cpp-all , которые больше или равны 0.1.2 и меньше 0.2.0. my-github-user/my-custom-libraries — это имя пакета CodeQL, содержащего пользовательские библиотеки CodeQL для C++. Любой файл библиотеки CodeQL (файл с расширением), определенный .qll в этом пакете, будет доступен для запросов в пакете my-github-user/my-custom-queries .

Свойство suites указывает каталог, в котором можно найти "хорошо известные" наборы запросов. Эти наборы можно использовать в командной строке, ссылаясь только на их имя, а не на полный путь. Дополнительные сведения о наборах запросов см. в разделе Создание наборов запросов CodeQL.

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

Для пользовательских пакетов CodeQL, содержащих тестовые файлы, необходимо также включить extractor свойство , чтобы команда знала test run , как создавать тестовые базы данных. Вы также можете указать tests свойство .

В следующем qlpack.yml файле указано, что my-github-user/my-query-tests зависит my-github-user/my-custom-queries от версии, больше или равной 1.2.3 и меньше 2.0.0. Он также объявляет, что CLI должен использовать Java extractor при создании тестовых баз данных. В строке tests: . объявляется, что все .ql файлы в пакете должны выполняться как тесты при codeql test run выполнении с параметром --strict-test-discovery . Как правило, тестовые пакеты не содержат version свойства . Это не позволит вам случайно опубликовать их.

name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java
tests: .

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

Примеры пакетов CodeQL в репозитории CodeQL

Каждый из языков в репозитории CodeQL содержит четыре пакета main CodeQL:

Пакет основной библиотеки для языка со схемой базы данных, используемой языком, и библиотеки CodeQL и запросы по адресу <language>/ql/lib
Основной пакет запросов для языка, который включает запросы по умолчанию для языка, а также их наборы запросов в <language>/ql/src
Тесты для основных языковых библиотек и запросов по адресу <language>/ql/test
Примеры запросов для языка в <language>/ql/examples

Пакет основной библиотеки

Ниже приведен пример qlpack.yml файла для основного языкового пакета библиотек анализа C/C++ :

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

Дополнительные примечания о следующих свойствах:

library: указывает, что это пакет библиотеки без исполняемых запросов. Он предназначен только для использования в качестве зависимости для других пакетов.
dbscheme и upgrades: эти свойства являются внутренними для CodeQL CLI и должны определяться только в основном пакете QL для языка.

Основной пакет запросов

Ниже приведен пример qlpack.yml файла для пакета основных запросов анализа C/C++ :

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

Дополнительные примечания о следующих свойствах:

dependencies: этот пакет запроса зависит от codeql/cpp-all и codeql/suite-helpers. Так как эти зависимости разрешаются из источника, не имеет значения, с какой версией пакета CodeQL они совместимы. Дополнительные сведения об устранении зависимостей от источника см. в разделе Исходные зависимости.
suites: указывает каталог, содержащий "хорошо известные" наборы запросов.
defaultSuiteFile: имя файла набора запросов по умолчанию, используемого, если набор запросов не указан.

Тесты для основного пакета CodeQL

Ниже приведен пример qlpack.yml файла для базового пакета тестов анализа C/C++ :

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

Дополнительные примечания о следующих свойствах:

dependencies: этот пакет зависит от основных запросов CodeQL и пакетов библиотек для C++.
extractor: указывает, что все тесты будут использовать один и тот же средство извлечения C++ для создания базы данных для тестов.
tests: указывает расположение тестов. В этом случае тесты находятся в корневой папке (и во всех вложенных папках) пакета.
version: отсутствует version свойство для пакета тестов. Это предотвращает случайную публикацию тестовых пакетов.

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

В этой статье