Ссылка на пакеты запросов CodeQL

CodeQL Совместимость пакетов

Когда пакет запросов публикуется, он включает заранее скомпилированные представления всех запросов в нём для увеличения скорости анализа. Однако если версия, выполняющая анализ, превышает 6 месяцев, чем запущенная codeql pack publishверсияCodeQL, может потребоваться скомпилировать запросы из источника во время анализа, значительно замедляя процесс.

Пакет, опубликованный последним общедоступным выпуском CodeQL , будет использоваться версией CodeQL , которая используется code scanning и GitHub Actions, несмотря на то, что это часто немного более старый выпуск.

Если анализ содержит такие строки, как показано ниже, CodeQL то успешно используется предварительно компилированные запросы:

[42/108] Loaded /long/path/to/query/Filename.qlx.

Если вместо этого анализ содержит строки, которые выглядят следующим образом, то CodeQL вручную перекомпилировали запросы из источника:

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

Чтобы помочь пользователям пакета запросов воспользоваться предварительно скомпилированных запросов, рекомендуется использовать последний выпуск CodeQL для публикации пакетов. Кроме того, следует публиковать новую версию пакета с обновленной CodeQL версией каждые 6 месяцев.

Если вы публикуете пакеты запросов с намерением их использования в GitHub Enterprise Server установке, которая использует свои упакованные CodeQL двоичные файлы, используйте ту же CodeQL версию для запуска codeql pack publish.

файлы `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
```

`dataExtensions`

Требуется пакетами моделей.
Принимает список шаблонов glOB-объектов, указывающих, где находятся файлы расширения данных относительно корневого каталога пакета запроса или пакета библиотеки.

`dependencies`

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

Существует специальный заполнитель версии, ${workspace}указывающий, что этот CodeQL пакет зависит от любой версии зависимости в той же рабочей области. Дополнительные сведения см. в разделе Workspaces CodeQL.

`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
```

`extensionTargets`

Требуется пакетами моделей.
Объявляет, к каким пакетам запросов применяются расширения в пакете модели. Пакет расширений внедряет его расширения данных в каждый пакет, который называется в extensionTargets словаре, если пакет попадает в указанный диапазон версий и используется в оценке.

`groups`

Необязательно.
Определяет логические группировки пакетов в CodeQL рабочей области. Использование групп — это способ применения операций пакетов к подмножествам пакетов в рабочей области. Например, следующий пакет определяется как часть java и experimental группы:
```
groups:
  - java
  - experimental
```
При выполнении codeql pack publish --groups java,-experimental будут опубликованы все пакеты в java группе, кромеexperimental пакетов. Вы можете выполнить codeql pack ls --groups [-]<group>[,[-]<group>...] команду, чтобы вывести список пакетов в рабочей области, которая соответствует указанному набору групп.

Если CodeQL пакет в данной рабочей области включен в список:
- Он находится по крайней мере в одной из групп, перечисленных без знака минуса (это условие автоматически удовлетворяется, если нет групп, перечисленных без знака минуса), и
- Он не находится в какой-либо группе, указанной со знаком минуса.

`library`

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

`suites`

Необязательно для пакетов, определяющих наборы запросов. Это позволяет пользователям запускать наборы запросов, хранящиеся в указанном каталоге, указав имя пакета, не предоставляя полный путь.
В настоящее время поддерживается только для стандартных пакетов запросов, включенных в CodeQL пакет CLI.
Этот параметр не поддерживается для пакетов, CodeQL скачанных из GitHub реестра контейнеров.

`tests`

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

`extractor`

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

`authors`

Необязательно.
Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, CodeQL в которую публикуется пакет. Рассмотрим пример.
```
authors: [email protected],[email protected]
```

`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.4. Объект my-user/transitive-dependency, который является транзитивной зависимостью и не указан в qlpack.yml файле, заблокирован на версию 1.2.4. Файл other-dependency/from-source блокировки отсутствует, так как он разрешается из источника. Эта зависимость должна быть доступна в той же CodeQL рабочей области, что и пакет. Дополнительные сведения о CodeQL рабочих областях и разрешении зависимостей из источника см. в разделе Workspaces CodeQL.

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

Примеры пользовательских 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

где 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 .

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-kotlin
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 и должны быть определены только в основном CodeQL пакете запросов для языка.

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

Ниже приведен пример 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 Совместимость пакетов

файлы `qlpack.yml`

свойства `qlpack.yml`

`name`

`version`

`dataExtensions`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`extensionTargets`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

файлы `codeql-pack.lock.yml`

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

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

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

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

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

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

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

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