Сведения о пакетах 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`

Required by packs that export a set of default queries to run.
Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the codeql database analyze command. Supported from CLI version v2.6.0 and onwards. Only one of defaultSuiteFile or defaultSuite can be defined. For example:
```
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: .
```

Сведения о `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.4. , 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. Он также объявляет, что интерфейс командной строки должен использовать 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 содержит четыре основных пакета 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

In this article