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

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

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

Пакет, опубликованный в последнем публичном выпуске 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 для публикации ваших пакетов. Кроме того, каждые 6 месяцев публикуйте свежую версию вашего пака с обновлённой версией CodeQL.

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

файлы

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

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

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

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

свойства

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

name

• Обязательный для всех пакетов.

• Определяет область пакета, в которой публикуется пакет CodeQL и имя пакета, определенного с использованием буквенно-цифровых символов и дефисов. Он должен быть уникальным, так как CodeQL не может различать пакеты CodeQL с идентичными именами. Используйте имя пакета, чтобы указать запросы для выполнения и определения зависимостей между пакетами CodeQL (см. примеры ниже). Рассмотрим пример.

  name: octo-org/security-queries
  

version

• Требуется для всех опубликованных пакетов.

• Определяет семантику версии этого пакета CodeQL, который должен соответствовать спецификации SemVer версии 2.0.0. Рассмотрим пример.

  version: 0.0.0
  

dataExtensions

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

dependencies

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

• Определяет карту из ссылок пакета на диапазон семантических версий, совместимый с этим пакетом. Поддерживается для версий CodeQL CLI версии 2.6.0 и более поздних версий. Рассмотрим пример.

  dependencies:
    codeql/cpp-all: ^0.0.2
  

  Если вы не уверены или не имеет значения, какую версию следует использовать, можно использовать , что означает, что любая версия этой зависимости совместима с этим пакетом. На практике это обычно разрешается до самой высокой опубликованной версии зависимости.

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

defaultSuiteFile

• Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.

• Определяет путь к файлу набора запросов относительно корневого каталога пакета, содержащий все запросы, выполняемые по умолчанию при передаче этого пакета команде . Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из них. Рассмотрим пример.

  defaultSuiteFile: cpp-code-scanning.qls
  

defaultSuite

• Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.

• Определяет встроенный набор запросов, содержащий все запросы, выполняемые по умолчанию при передаче этого пакета в команду. Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из них. Рассмотрим пример.

  defaultSuite:
    queries: .
    exclude:
      precision: medium
  

extensionTargets

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

groups

• Необязательно.

• Определяет логические группировки пакетов в рабочей области CodeQL. Использование групп — это способ применения операций пакетов к подмножествам пакетов в рабочей области. Например, следующий пакет определяется как часть и группы:

  groups:
    - java
    - experimental
  

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

  Пакет CodeQL в данной рабочей области включается в список, если:

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

library

• Требуется пакетами библиотеки.

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

  library: true
  

suites

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

tests

• Необязательно для пакетов, содержащих тесты CodeQL. Игнорируется для пакетов без тестов.

• Определяет путь к каталогу в пакете, который содержит тесты, определенный относительно каталога пакета. Используется для указания всего пакета. Все запросы в этом каталоге выполняются в качестве тестов при выполнении с параметром . Эти запросы игнорируются определениями набора запросов, которые используют или инструкции для запроса всех запросов в определенном пакете. Если это свойство отсутствует, предполагается. Рассмотрим пример.

  tests: .
  

extractor

• Требуется для всех пакетов, содержащих тесты CodeQL.

• Определяет средство извлечения данных CodeQL для использования при выполнении тестов CodeQL в пакете. Дополнительные сведения о тестировании запросов см. в разделе AUTOTITLE. Рассмотрим пример.

  extractor: javascript-typescript
  

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

• Необязательный, закрытие. Вместо него используйте свойство .

• Ранее использовалось для определения имен всех пакетов CodeQL, от которые зависит этот пакет CodeQL в виде массива. Это дает пакету доступ к любым библиотекам, схеме базы данных и наборам запросов, определенным в зависимости. Рассмотрим пример.

  libraryPathDependencies: codeql/javascript-all
  

dbscheme

• Требуется только для основных языковых пакетов.

• Определяет путь к схеме базы данных для всех библиотек и запросов, написанных для этого языка CodeQL (см. пример ниже). Рассмотрим пример.

  dbscheme: semmlecode.python.dbscheme
  

upgrades

• Требуется только для основных языковых пакетов.

• Определяет путь к каталогу в пакете, который содержит скрипты обновления базы данных, определенный относительно каталога пакета. Обновления базы данных используются внутренне для обеспечения совместимости базы данных с другой версией CodeQL CLI с текущей версией ИНТЕРФЕЙСА командной строки. Рассмотрим пример.

  upgrades: .
  

warnOnImplicitThis

• Необязательно. Значение по умолчанию, если свойство не определено.

• Определяет логическое значение, указывающее, должен ли компилятор выдавать предупреждения о вызовах предиката члена с неявными приемниками вызовов, то есть без явного приемника. Доступно с CodeQL CLI версии 2.13.2. Рассмотрим пример.

  warnOnImplicitThis: true
  

файлы

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

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

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

Файл будет содержать примерно следующее:

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

Зависимость заблокирована до версии 0.1.4. Зависимость заблокирована до версии 0.2.4. Объект , который является транзитивной зависимостью и не указан в файле, заблокирован на версию 1.2.4. Файл блокировки отсутствует, так как он разрешается из источника. Эта зависимость должна быть доступна в той же рабочей области CodeQL, что и пакет. Дополнительные сведения о рабочих областях CodeQL и разрешении зависимостей из источника см. в разделе AUTOTITLE.

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

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

Вам следует сохранять файлы для пользовательских запросов и тестов в отдельных пакетах, а также организовывать их в отдельные папки для каждого целевой языка.

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

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

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

где имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон версий указывает, что этот пакет совместим со всеми версиями , превышающими или равными и меньше . Любой файл библиотеки CodeQL (файл с расширением), определенный в этом пакете, будет доступен для запросов, определенных в любом пакете запросов, который включает этот пакет в блок зависимостей.

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

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

Пользовательский пакет данных CodeQL с пользовательскими запросами и библиотеками C++ может содержать файл:

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 для анализа C/C++, включенного в репозиторий CodeQL. Диапазон версий указывает, что этот пакет совместим со всеми версиями , превышающими или равными и меньше . — это имя пакета CodeQL с пользовательскими библиотеками CodeQL для C++. Любой файл библиотеки CodeQL (файл с расширением), определенный в этом пакете, будет доступен для запросов в пакете .

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

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

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: .

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

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

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

• Основной пакет библиотеки для языка с схемой базы данных, используемой языком, и библиотеками CodeQL и запросами по адресу

• Основной пакет запросов для языка, который включает запросы по умолчанию для языка, а также их наборы запросов в

• Тесты для основных языковых библиотек и запросов по адресу

• Примеры запросов для языка на

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

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

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

Некоторые дополнительные заметки о следующих свойствах:

• : указывает, что это пакет библиотеки без исполняемых запросов. Оно предназначено только для использования в качестве зависимости для других пакетов.

• и : эти свойства являются внутренними для CodeQL CLI и должны быть определены только в основном пакете запросов CodeQL для языка.

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

Ниже приведен пример файла для запросов анализа 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

Некоторые дополнительные заметки о следующих свойствах:

• : этот пакет запросов зависит от и . Так как эти зависимости разрешаются из источника, не имеет значения, с какой версией пакета CodeQL они совместимы. Дополнительные сведения о разрешении зависимостей из источника см. в разделе "Зависимости источника".

• : указывает каталог, содержащий "известные" наборы запросов.

• : имя файла набора запросов по умолчанию, используемого при отсутствии набора запросов.

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

Ниже приведен пример файла для тестов анализа C/C++:

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

Некоторые дополнительные заметки о следующих свойствах:

• : этот пакет зависит от основных пакетов данных CodeQL запросов и пакетов библиотеки для C++.

• : указывает, что все тесты будут использовать один и тот же средство извлечения C++ для создания базы данных для тестов.

• : указывает расположение тестов. В этом случае тесты находятся в корневой папке (и всех вложенных папках) пакета.

• : для пакета тестов нет свойства. Это предотвращает случайное публикацию тестовых пакетов.