{"meta":{"title":"Ссылка на пакеты запросов CodeQL","intro":"Понять совместимость, содержимое и структуру пакетов CodeQL.","product":"Безопасность и качество кода","breadcrumbs":[{"href":"/ru/code-security","title":"Безопасность и качество кода"},{"href":"/ru/code-security/reference","title":"Reference"},{"href":"/ru/code-security/reference/code-scanning","title":"Проверка кода"},{"href":"/ru/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/ru/code-security/reference/code-scanning/codeql/codeql-cli","title":"CodeQL CLI"},{"href":"/ru/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs","title":"Пакеты запросов CodeQL"}],"documentType":"article"},"body":"# Ссылка на пакеты запросов CodeQL\n\nПонять совместимость, содержимое и структуру пакетов CodeQL.\n\n## CodeQL совместимость пакетов\n\nКогда пакет запросов публикуется, он включает заранее скомпилированные представления всех запросов в нём для увеличения скорости анализа. Однако если версия CodeQL, выполняющая анализ, более чем на 6 месяцев новее запущенной версии `codeql pack publish`, может потребоваться компилировать запросы из исходного кода во время анализа, что значительно замедляет процесс.\n\nПакет, опубликованный *в последнем* публичном выпуске CodeQL, будет использоваться версией CodeQL, используемой code scanning и GitHub Actions, хотя это часто немного более старый релиз.\n\nЕсли ваш анализ содержит следующие строки, то CodeQL успешно использует заранее скомпилированные запросы:\n\n```shell\n[42/108] Loaded /long/path/to/query/Filename.qlx.\n```\n\nЕсли ваш анализ содержит строки, выглядящие следующим образом, то CodeQL вручную перекомпилировал запросы из исходного источника:\n\n```shell\nCompiling query plan for /long/path/to/query/Filename.ql.\n[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.\n```\n\nЧтобы помочь пользователям вашего пакета запросов воспользоваться заранее скомпилированными запросами, мы рекомендуем использовать недавний релиз CodeQL для публикации ваших пакетов. Кроме того, каждые 6 месяцев публикуйте свежую версию вашего пака с обновлённой версией CodeQL.\n\nЕсли вы публикуете пакеты запросов с намерением их использования в установке GitHub Enterprise Server, которая использует свои упакованные двоичные файлы CodeQL, используйте ту же версию CodeQL для запуска `codeql pack publish`.\n\n## файлы `qlpack.yml`\n\nПри выполнении команд, связанных с запросами, CodeQL сначала ищет файлы в родственниках инсталляционного каталога (и их подкаталогах `qlpack.yml` ), затем проверяет кэш пакетов на наличие загруженных CodeQL пакетов. Это значит, что когда ваши локальные пакеты в каталоге установки переопределяют пакеты с тем же названием в кэше пакетов, вы можете протестировать локальные изменения.\n\nМетаданные в каждом `qlpack.yml` файле сообщают CodeQL, как скомпилировать все запросы в пакете, какие библиотеки зависят от пакета и где найти определения набора запросов.\n\nСодержимое пакета CodeQL (запросы или библиотеки, используемые в анализе CodeQL , включаются в тот же каталог, что `qlpack.yml`и вложенные каталоги.\n\nКаталог, `qlpack.yml` содержащий файл, служит корневым каталогом для содержимого пакета CodeQL . То есть для всех `.ql` и `.qll` файлов в пакете CodeQL разрешает все инструкции импорта относительно каталога, `qlpack.yml` содержащего файл в корневом каталоге пакета.\n\n### свойства `qlpack.yml`\n\nСледующие свойства поддерживаются в `qlpack.yml` файлах.\n\n#### `name`\n\n* Обязательный для всех пакетов.\n* Определяет область пакета, в которой публикуется пакет CodeQL и имя пакета, определенного с использованием буквенно-цифровых символов и дефисов. Он должен быть уникальным, так как CodeQL не может различать пакеты CodeQL с идентичными именами. Используйте имя пакета, чтобы указать запросы для выполнения и `database analyze` определения зависимостей между пакетами CodeQL (см. примеры ниже). Рассмотрим пример.\n\n  ```yaml\n  name: octo-org/security-queries\n  ```\n\n#### `version`\n\n* Требуется для всех опубликованных пакетов.\n* Определяет семантику версии этого пакета CodeQL, который должен соответствовать [спецификации](https://semver.org/spec/v2.0.0.html) SemVer версии 2.0.0. Рассмотрим пример.\n\n  ```yaml\n  version: 0.0.0\n  ```\n\n#### `dataExtensions`\n\n* Требуется пакетами моделей.\n* Принимает список шаблонов glOB-объектов, указывающих, где находятся файлы расширения данных относительно корневого каталога пакета запроса или пакета библиотеки.\n\n#### `dependencies`\n\n* Требуется для пакетов запросов и библиотек, определяющих зависимости пакетов CodeQL для других пакетов. Пакеты моделей не могут определять зависимости и использовать `extensionTargets` их.\n* Определяет карту из ссылок пакета на диапазон семантических версий, совместимый с этим пакетом. Поддерживается для версий CodeQL CLI версии 2.6.0 и более поздних версий. Рассмотрим пример.\n\n  ```yaml\n  dependencies:\n    codeql/cpp-all: ^0.0.2\n  ```\n\n  Если вы не уверены или не имеет значения, какую версию следует использовать, можно использовать `\"*\"`, что означает, что любая версия этой зависимости совместима с этим пакетом. На практике это обычно разрешается до самой высокой опубликованной версии зависимости.\n\n  Существует специальный заполнитель версии, `${workspace}`указывающий, что этот пакет CodeQL зависит от любой версии зависимости в той же рабочей области. Дополнительные сведения см. в разделе [Сведения о рабочих областях CodeQL](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#using-workspace-as-a-version-range-in-qlpackyml-files).\n\n#### `defaultSuiteFile`\n\n* Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.\n* Определяет путь к файлу набора запросов относительно корневого каталога пакета, содержащий все запросы, выполняемые по умолчанию при передаче этого пакета команде `codeql database analyze` . Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из `defaultSuiteFile``defaultSuite` них. Рассмотрим пример.\n\n  ```yaml\n  defaultSuiteFile: cpp-code-scanning.qls\n  ```\n\n#### `defaultSuite`\n\n* Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.\n* Определяет встроенный набор запросов, содержащий все запросы, выполняемые по умолчанию при передаче `codeql database analyze` этого пакета в команду. Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из `defaultSuiteFile``defaultSuite` них. Рассмотрим пример.\n\n  ```yaml\n  defaultSuite:\n    queries: .\n    exclude:\n      precision: medium\n  ```\n\n#### `extensionTargets`\n\n* Требуется пакетами моделей.\n* Объявляет, к каким пакетам запросов применяются расширения в пакете модели. Пакет расширений внедряет его расширения данных в каждый пакет, который называется в `extensionTargets` словаре, если пакет попадает в указанный диапазон версий и используется в оценке.\n\n#### `groups`\n\n* Необязательно.\n* Определяет логические группировки пакетов в рабочей области CodeQL. Использование групп — это способ применения операций пакетов к подмножествам пакетов в рабочей области. Например, следующий пакет определяется как часть `java` и `experimental` группы:\n\n  ```yaml\n  groups:\n    - java\n    - experimental\n  ```\n\n  При выполнении `codeql pack publish --groups java,-experimental` будут опубликованы все пакеты в `java` группе, *кроме*`experimental` пакетов. Вы можете выполнить `codeql pack ls --groups [-]<group>[,[-]<group>...]` команду, чтобы вывести список пакетов в рабочей области, которая соответствует указанному набору групп.\n\n  Пакет CodeQL в данной рабочей области включается в список, если:\n\n  * Он находится по крайней мере в одной из групп, перечисленных без знака минуса (это условие автоматически удовлетворяется, если нет групп, перечисленных без знака минуса), и\n  * Он не находится в какой-либо группе, указанной со знаком минуса.\n\n#### `library`\n\n* Требуется пакетами библиотеки.\n* Определяет логическое значение, указывающее, является ли этот пакет пакетом библиотеки. Пакеты библиотек не содержат запросы и не компилируются. Пакеты запросов могут игнорировать это поле или явно задать для него значение `false`. Рассмотрим пример.\n\n  ```yaml\n  library: true\n  ```\n\n#### `suites`\n\n* Необязательно для пакетов, определяющих наборы запросов. Это позволяет пользователям запускать наборы запросов, хранящиеся в указанном каталоге, указав имя пакета, не предоставляя полный путь.\n* В настоящее время поддерживается только для стандартных пакетов запросов, включенных в пакет CLI CodeQL.\n* Этот параметр не поддерживается для пакетов CodeQL, скачанных из реестра контейнеров GitHub .\n\n#### `tests`\n\n* Необязательно для пакетов, содержащих тесты CodeQL. Игнорируется для пакетов без тестов.\n* Определяет путь к каталогу в пакете, который содержит тесты, определенный относительно каталога пакета. Используется `.` для указания всего пакета. Все запросы в этом каталоге выполняются в качестве тестов при `test run` выполнении с параметром `--strict-test-discovery` . Эти запросы игнорируются определениями набора запросов, которые используют `queries` или `qlpack` инструкции для запроса всех запросов в определенном пакете. Если это свойство отсутствует, `.` предполагается. Рассмотрим пример.\n\n  ```yaml\n  tests: .\n  ```\n\n#### `extractor`\n\n* Требуется для всех пакетов, содержащих тесты CodeQL.\n* Определяет средство извлечения данных CodeQL для использования при выполнении тестов CodeQL в пакете. Дополнительные сведения о тестировании запросов см. в разделе [Тестирование пользовательских запросов](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). Рассмотрим пример.\n\n  ```yaml\n  extractor: javascript-typescript\n  ```\n\n#### `authors`\n\n* Необязательно.\n* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Рассмотрим пример.\n\n  ```yaml\n  authors: author1@github.com,author2@github.com\n  ```\n\n#### `license`\n\n* Необязательно.\n* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Список разрешенных лицензий см [. в списке](https://spdx.org/licenses/) лицензий SPDX в спецификации SPDX. Рассмотрим пример.\n\n  ```yaml\n  license: MIT\n  ```\n\n#### `description`\n\n* Необязательно.\n* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Рассмотрим пример.\n\n  ```yaml\n  description: Human-readable description of the contents of the CodeQL pack.\n  ```\n\n#### `libraryPathDependencies`\n\n* Необязательный, закрытие. Вместо него используйте свойство `dependencies`.\n* Ранее использовалось для определения имен всех пакетов CodeQL, от которые зависит этот пакет CodeQL в виде массива. Это дает пакету доступ к любым библиотекам, схеме базы данных и наборам запросов, определенным в зависимости. Рассмотрим пример.\n\n  ```yaml\n  libraryPathDependencies: codeql/javascript-all\n  ```\n\n#### `dbscheme`\n\n* Требуется только для основных языковых пакетов.\n* Определяет путь к схеме [](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) базы данных для всех библиотек и запросов, написанных для этого языка CodeQL (см. пример ниже). Рассмотрим пример.\n\n  ```yaml\n  dbscheme: semmlecode.python.dbscheme\n  ```\n\n#### `upgrades`\n\n* Требуется только для основных языковых пакетов.\n* Определяет путь к каталогу в пакете, который содержит скрипты обновления базы данных, определенный относительно каталога пакета. Обновления базы данных используются внутренне для обеспечения совместимости базы данных с другой версией CodeQL CLI с текущей версией ИНТЕРФЕЙСА командной строки. Рассмотрим пример.\n\n  ```yaml\n  upgrades: .\n  ```\n\n#### `warnOnImplicitThis`\n\n* Необязательно. Значение по умолчанию, `false` если `warnOnImplicitThis` свойство не определено.\n* Определяет логическое значение, указывающее, должен ли компилятор выдавать предупреждения о вызовах предиката члена с неявными `this` приемниками вызовов, то есть без явного приемника. Доступно с CodeQL CLI версии 2.13.2. Рассмотрим пример.\n\n  ```yaml\n  warnOnImplicitThis: true\n  ```\n\n## файлы `codeql-pack.lock.yml`\n\n```\n          `codeql-pack.lock.yml` файлы хранят версии разрешенных транзитивных зависимостей пакета CodeQL. Этот файл создается командой, `codeql pack install` если она еще не существует и должна быть добавлена в систему управления версиями. \n          `dependencies` Раздел `qlpack.yml` файла содержит диапазоны версий, совместимые с пакетом. Файл `codeql-pack.lock.yml` блокирует версии с точными зависимостями. Это гарантирует, что выполнение `codeql pack install` этого пакета всегда будет получать те же версии зависимостей, даже если существуют более новые совместимые версии.\n```\n\nНапример, если `qlpack.yml` файл содержит следующие зависимости:\n\n```yaml\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-user/my-lib: ^0.2.3\n  other-dependency/from-source: \"*\"\n```\n\nФайл `codeql-pack.lock.yml` будет содержать примерно следующее:\n\n```yaml\ndependencies:\n  codeql/cpp-all:\n    version: 0.1.4\n  my-user/my-lib:\n    version: 0.2.4\n  my-user/transitive-dependency:\n    version: 1.2.4\n```\n\nЗависимость `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](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces).\n\nВ большинстве случаев файл относится только к пакетам запросов, `codeql-pack.lock.yml` так как пакеты библиотек не являются исполняемыми и обычно не нуждаются в их транзитивных зависимостях для исправления. Исключением из этого является пакет библиотек, содержащий тесты. В этом случае файл используется для обеспечения того, `codeql-pack.lock.yml` чтобы тесты всегда выполнялись с одинаковыми версиями зависимостей, чтобы избежать сбой в случае несоответствия зависимостей.\n\n## Пример пользовательских CodeQL пакетов\n\nВам следует сохранять файлы для пользовательских запросов и тестов в отдельных пакетах, а также организовывать их в отдельные папки для каждого целевой языка.\n\n### Пакеты CodeQL для пользовательских библиотек\n\nПользовательский пакет данных CodeQL, содержащий пользовательские библиотеки C++ без запросов или тестов, может содержать `qlpack.yml` файл:\n\n```yaml\nname: my-github-user/my-custom-libraries\nversion: 1.2.3\nlibrary: true\ndependencies:\n  codeql/cpp-all: ^0.1.2\n```\n\nгде `codeql/cpp-all` имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон `^0.1.2` версий указывает, что этот пакет совместим со всеми версиями `codeql/cpp-all` , превышающими или равными `0.1.2` и меньше `0.2.0`. Любой файл библиотеки CodeQL (файл с `.qll` расширением), определенный в этом пакете, будет доступен для запросов, определенных в любом пакете запросов, который включает этот пакет в блок зависимостей.\n\nСвойство `library` указывает, что этот пакет является пакетом библиотеки и не содержит никаких запросов.\n\n### Пакеты CodeQL для пользовательских запросов\n\nПользовательский пакет данных CodeQL с пользовательскими запросами и библиотеками C++ может содержать `qlpack.yml` файл:\n\n```yaml\nname: my-github-user/my-custom-queries\nversion: 1.2.3\ndependencies:\n  codeql/cpp-all: ^0.1.2\n  my-github-user/my-custom-libraries: ^1.2.3\n```\n\nгде `codeql/cpp-all` имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон `^0.1.2` версий указывает, что этот пакет совместим со всеми версиями `codeql/cpp-all` , превышающими или равными `0.1.2` и меньше `0.2.0`.\n`my-github-user/my-custom-libraries` — это имя пакета CodeQL с пользовательскими библиотеками CodeQL для C++. Любой файл библиотеки CodeQL (файл с `.qll` расширением), определенный в этом пакете, будет доступен для запросов в пакете `my-github-user/my-custom-queries` .\n\n### Пакеты CodeQL для пользовательских тестов\n\nДля пользовательских пакетов CodeQL, содержащих тестовые файлы, необходимо также включить `extractor` свойство, чтобы команда знала, `test run` как создавать тестовые базы данных. Вы также можете указать `tests` свойство.\n\n`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` свойства. Это предотвращает случайное их публикацию.\n\n```yaml\nname: my-github-user/my-query-tests\ndependencies:\n  my-github-user/my-custom-queries: ^1.2.3\nextractor: java-kotlin\ntests: .\n```\n\nДополнительные сведения о выполнении тестов см. в разделе [Тестирование пользовательских запросов](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries).\n\n## Пример CodeQL упаковывается в репозитории CodeQL\n\nКаждый из языков в репозитории CodeQL содержит четыре основных пакета CodeQL:\n\n* Основной пакет библиотеки для языка с схемой базы данных, используемой языком, и библиотеками CodeQL и запросами по адресу `<language>/ql/lib`\n\n* Основной пакет запросов для языка, который включает запросы по умолчанию для языка, а также их наборы запросов в `<language>/ql/src`\n\n* Тесты для основных языковых библиотек и запросов по адресу `<language>/ql/test`\n\n* Примеры запросов для языка на `<language>/ql/examples`\n\n### Пакет основной библиотеки\n\nНиже приведен пример `qlpack.yml` файла для [основных языковых](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) пакетов библиотек анализа C/C++:\n\n```yaml\nname: codeql/cpp-all\nversion: x.y.z-dev\ndbscheme: semmlecode.cpp.dbscheme\nlibrary: true\nupgrades: upgrades\n```\n\nНекоторые дополнительные заметки о следующих свойствах:\n\n* `library`: указывает, что это пакет библиотеки без исполняемых запросов. Оно предназначено только для использования в качестве зависимости для других пакетов.\n\n* `dbscheme` и `upgrades`: эти свойства являются внутренними для CodeQL CLI и должны быть определены только в основном пакете запросов CodeQL для языка.\n\n### Основной пакет запросов\n\nНиже приведен пример `qlpack.yml` файла для запросов[ анализа C/C++ для ](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml)основного пакета запросов:\n\n```yaml\nname: codeql/cpp-queries\nversion: x.y.z-dev\ndependencies:\n    codeql/cpp-all: \"*\"\n    codeql/suite-helpers: \"*\"\nsuites: codeql-suites\ndefaultSuiteFile: codeql-suites/cpp-code-scanning.qls\n```\n\nНекоторые дополнительные заметки о следующих свойствах:\n\n* `dependencies`: этот пакет запросов зависит от `codeql/cpp-all` и `codeql/suite-helpers`. Так как эти зависимости разрешаются из источника, не имеет значения, с какой версией пакета CodeQL они совместимы. Дополнительные сведения о разрешении зависимостей из источника см. в разделе [\"Зависимости](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies) источника\".\n\n* `suites`: указывает каталог, содержащий \"известные\" наборы запросов.\n\n* `defaultSuiteFile`: имя файла набора запросов по умолчанию, используемого при отсутствии набора запросов.\n\n### Тесты для основного пакета данных CodeQL\n\nНиже приведен пример `qlpack.yml` файла для тестов[ анализа C/C++:](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml)\n\n```yaml\nname: codeql/cpp-tests\ndependencies:\n  codeql/cpp-all: \"*\"\n  codeql/cpp-queries: \"*\"\nextractor: cpp\ntests: .\n```\n\nНекоторые дополнительные заметки о следующих свойствах:\n\n* `dependencies`: этот пакет зависит от основных пакетов данных CodeQL запросов и пакетов библиотеки для C++.\n\n* `extractor`: указывает, что все тесты будут использовать один и тот же средство извлечения C++ для создания базы данных для тестов.\n\n* `tests`: указывает расположение тестов. В этом случае тесты находятся в корневой папке (и всех вложенных папках) пакета.\n\n* `version`: для пакета тестов нет `version` свойства. Это предотвращает случайное публикацию тестовых пакетов."}