Проверка подлинности в GitHub Container registries
Вы можете публиковать пакеты и скачивать частные пакеты, проверяя подлинность в соответствующих GitHub Container registry.
Вы можете пройти проверку подлинности в Container registry двумя способами:
--github-auth-stdin
Передайте параметр CodeQL CLI, а затем укажите маркер GitHub Apps или personal access token через стандартные входные данные.- Задайте для переменной
GITHUB_TOKEN
среды значение GitHub Apps или personal access token.
qlpack.yml
Настройка файла перед публикацией
Вы можете проверить и изменить сведения о конфигурации пакета CodeQL перед публикацией. qlpack.yml
Откройте файл в предпочитаемом текстовом редакторе.
library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
defaultSuite: # optional, one or more queries in the pack to run by default
- query: <relative-path>/query-file>.ql
defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range
-
name:
должен соответствовать формату<scope>/<pack>
, где<scope>
находится организация GitHub , в которой будет публиковаться и<pack>
имя пакета. -
Допускается не более одного или
defaultSuite
defaultSuiteFile
одного из них. Это два разных способа определения набора запросов по умолчанию, первый путем указания запросов непосредственно в файле qlpack.yml и второй путем указания набора запросов в пакете.
Бег codeql pack publish
Когда вы будете готовы опубликовать пакет в GitHub Container registry, можно выполнить следующую команду в корневом каталоге пакета:
codeql pack publish
Опубликованный пакет будет отображаться в разделе пакетов GitHub организации, указанной областью в qlpack.yml
файле.
Note
Если вы публикуете пакеты моделей в GitHub Container registry для расширения охвата всех репозиториев в организации в рамках конфигурации настройки по умолчанию, необходимо убедиться, что репозитории, выполняющие сканирование кода, могут получить доступ к этим пакетам моделей. Дополнительные сведения см. в разделе [AUTOTITLE и Изменение конфигурации настройки по умолчанию](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).
Бег codeql pack download <scope>/<pack>
Чтобы запустить созданный пакет, необходимо сначала скачать его, выполнив следующую команду:
codeql pack download <scope>/<pack>@x.x.x
<scope>
: имя организации GitHub, из которую вы будете скачать.<pack>
: имя пакета, который требуется скачать.@x.x.x
: необязательный номер версии. Если опущено, будет загружена последняя версия.
Эта команда принимает аргументы для нескольких пакетов.
Если вы пишете скрипты, указывающие определенный номер версии пакета запросов для скачивания, помните, что при обновлении версии CodeQL на более новую, может потребоваться также переключиться на более новую версию пакета запросов. Более новые версии CodeQL могут обеспечить снижение производительности при использовании с пакетами запросов, закрепленными на очень старой версии. Дополнительные сведения см. в разделе о совместимости пакетов CodeQL.
Использование пакета данных CodeQL для анализа базы данных CodeQL
Чтобы проанализировать базу данных CodeQL с помощью пакета CodeQL выполните следующую команду:
codeql database analyze <database> <scope>/<pack>@x.x.x:<path>
<database>
: база данных CodeQL для анализа.<scope>
: имя организации GitHub, в которую публикуется пакет.<pack>
: имя используемого пакета.@x.x.x
: необязательный номер версии. Если опущено, будет использоваться последняя версия.:<path>
: необязательный путь к запросу, каталогу или набору запросов. Если опущено, будет использоваться набор запросов по умолчанию пакета.
Команда analyze
запустит набор данных по умолчанию для всех указанных пакетов CodeQL . Можно указать несколько пакетов данных CodeQL для анализа базы данных CodeQL . Например:
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
Note
Команда codeql pack download
сохраняет пакет, который он загружает в внутреннем расположении, которое не предназначено для локального изменения. Непредвиденное поведение (и трудно устранить неполадки) может привести к изменению пакета после скачивания. Дополнительные сведения о настройке пакетов см. в разделе Создание и работа с пакетами CodeQL.
Сведения о совместимости пакетов CodeQL
При публикации пакета запросов он включает предварительно скомпилированные представления всех запросов в нем. Эти предварительно скомпилированные запросы обычно гораздо быстрее выполняются, чем компиляция источника QL с нуля во время анализа. Однако предварительно скомпилированные запросы также зависят от определенных внутренних компонентов оценщика QL, поэтому если версия CodeQL выполняет анализ слишком отличается от запущенной версии codeql pack publish
, может потребоваться скомпилировать запросы из источника вместо анализа. Перекомпиляция происходит автоматически и не влияет на результаты анализа, но это может значительно замедлить анализ.
Как правило, можно предположить, что если пакет публикуется с одним выпуском CodeQL, предварительно скомпилированные запросы в нем можно использовать непосредственно в последующих выпусках CodeQL, если между датами выпуска не более 6 месяцев. Мы будем делать разумные усилия по поддержанию совместимости новых выпусков дольше, чем это, но никаких обещаний.
Также можно предположить, что пакет, опубликованный последним общедоступным выпуском CodeQL будет использоваться версией CodeQL, которая используется code scanning и GitHub Actions, хотя это часто является немного более старым выпуском.
В качестве пользователя опубликованного пакета запросов можно проверить, использует ли в нем предварительно скомпилированные запросы CodeQL путем проверки выходных данных терминала из выполнения анализа, использующего пакет запросов. Если он содержит строки, похожие на следующие, то предварительно скомпилированные запросы были успешно использованы:
[42/108] Loaded /long/path/to/query/Filename.qlx.
Однако если вместо этого они выглядят следующим образом, использование предварительно скомпилированных запросов завершилось ошибкой:
Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.
Результаты анализа по-прежнему будут хорошими в этом случае, но для получения оптимальной производительности может потребоваться обновить до более новой версии CodeQL CLI и /или пакета запросов.
Если вы публикуете пакеты запросов на Container registry на GitHub.com для других пользователей, рекомендуется использовать последний выпуск CodeQL для запуска codeql pack publish
, и опубликуйте новую версию пакета с обновленной версией CodeQL до того, как используется версия, используемая 6 месяцев. Таким образом вы можете убедиться, что пользователи пакета, которые сохраняют свои данные CodeQL в актуальном состоянии, будут использовать предварительно скомпилированные запросы в пакете.
Если вы публикуете пакеты запросов с намерением их использования в установке GitHub Enterprise Server, которая использует свои упакованные двоичные файлы CodeQL, используйте ту же версию CodeQL для запуска codeql pack publish
. Более новые версии могут создавать предварительно скомпилированные запросы, которые в GitHub Enterprise Server не распознаются. Администратор GitHub Enterprise Server может периодически обновляться до более новой версии CodeQL. Если да, следуйте их свинцу.
Сведения о файлах 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 зависит от любой версии зависимости в той же рабочей области. Дополнительные сведения см. в разделе Сведения о рабочих областях 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
- Необязательно для пакетов, определяющих наборы запросов. Это позволяет пользователям запускать наборы запросов, хранящиеся в указанном каталоге, указав имя пакета, не предоставляя полный путь.
- В настоящее время поддерживается только для стандартных пакетов запросов, включенных в пакет CLI CodeQL.
- Этот параметр не поддерживается для пакетов CodeQL, скачанных из реестра контейнеров GitHub .
tests
-
Необязательно для пакетов, содержащих тесты CodeQL. Игнорируется для пакетов без тестов.
-
Определяет путь к каталогу в пакете, который содержит тесты, определенный относительно каталога пакета. Используется
.
для указания всего пакета. Все запросы в этом каталоге выполняются в качестве тестов приtest run
выполнении с параметром--strict-test-discovery
. Эти запросы игнорируются определениями набора запросов, которые используютqueries
илиqlpack
инструкции для запроса всех запросов в определенном пакете. Если это свойство отсутствует,.
предполагается. Например:tests: .
extractor
-
Требуется для всех пакетов, содержащих тесты CodeQL.
-
Определяет средство извлечения данных CodeQL для использования при выполнении тестов CodeQL в пакете. Дополнительные сведения о тестировании запросов см. в разделе Тестирование пользовательских запросов. Например:
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
-
Необязательный, устаревший. Вместо него используйте свойство
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
если она еще не существует и должна быть добавлена в систему управления версиями. qlpack.yml
Раздел dependencies
файла содержит диапазоны версий, совместимые с пакетом. Файл 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
где 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
свойства. Это предотвращает случайное публикацию тестовых пакетов.