Примечание: Эта статья была перенесена с веб-сайта документации По CodeQL в январе 2023 г.
Сведения о пользовательских запросах и CodeQL CLI
Вы можете настроить анализ CodeQL, написав собственные запросы для выделения конкретных уязвимостей или ошибок.
В этом разделе конкретно описывается написание запросов для использования с командой анализа базы данных для получения интерпретируемых результатов.
Примечание: Запросы, выполняемые с database analyze использованием , имеют строгие требования к метаданным. Вы также можете выполнять запросы с помощью следующих подкоманд уровня сантехники:
- выполнение запросов базы данных, которое выводит не интерпретируемые результаты в промежуточном двоичном формате, называемом BQRS.
- выполните запрос, который выведет файлы BQRS или выведет таблицы результатов непосредственно в командную строку. Просмотр результатов непосредственно в командной строке может быть полезен для итеративной разработки запросов с помощью CLI.
Запросы, выполняемые с помощью этих команд, не имеют одинаковых требований к метаданным. Однако для сохранения доступных для чтения данных необходимо обрабатывать каждый файл результатов BQRS с помощью подкоманды bqrs decode plumbing. Поэтому в большинстве случаев проще всего использовать анализ базы данных для непосредственного создания интерпретированных результатов.
Написание допустимого запроса
Перед выполнением пользовательского анализа необходимо написать допустимый запрос и сохранить его в файле с расширением .ql . Существует обширная документация, помогая создавать запросы. Дополнительные сведения см. в разделе ЗапросыCodeQL.
Включение метаданных запроса
Метаданные запроса включаются в начало каждого файла запроса. Он предоставляет пользователям сведения о запросе и сообщает CodeQL CLI, как обрабатывать результаты запроса.
При выполнении запросов с database analyze помощью команды необходимо включить следующие два свойства, чтобы обеспечить правильную интерпретацию результатов:
-
Идентификатор запроса (
@id): последовательность слов, состоящих из строчных букв или цифр, разделенных/или-, идентифицирующих и классифицирующих запрос. -
Тип запроса (
@kind): определяет запрос как простое оповещение (@kind problem), оповещение, задокументированное последовательностью расположений кода (@kind path-problem), для устранения неполадок средства извлечения (@kind diagnostic) или сводной метрики (@kind metricи@tags summary).
Дополнительные сведения об этих свойствах метаданных см. в разделе Метаданные для запросов CodeQL и в руководстве по стилю метаданных запросов.
Примечание: Требования к метаданным могут отличаться, если вы хотите использовать запрос с другими приложениями. Дополнительные сведения см. в разделе Метаданные для запросов CodeQL.
Упаковка пользовательских запросов QL
Примечание: Функции управления пакетами CodeQL, включая пакеты CodeQL, в настоящее время доступны в виде бета-версии и могут быть изменены. Во время бета-версии пакеты CodeQL доступны только с помощью пакетов GitHub — Container registry. Чтобы использовать эту бета-версию, установите последнюю версию пакета CodeQL CLI из: https://github.com/github/codeql-action/releases.
При написании собственных запросов с намерением поделиться ими с другими пользователями следует сохранить их в пользовательском пакете CodeQL. Вы можете опубликовать пакет в виде пакета CodeQL в GitHub Packages — GitHub Container registry. Дополнительные сведения см. в разделе Сведения о пакетах CodeQL.
Пакеты CodeQL упорядочивают файлы, используемые в анализе CodeQL, и могут хранить запросы, файлы библиотеки, наборы запросов и важные метаданные. Их корневой каталог должен содержать файл с именем qlpack.yml. Пользовательские запросы должны быть сохранены в корневом каталоге пакета CodeQL или в его подкаталогах.
Для каждого пакета CodeQL файл содержит сведения, qlpack.yml которые сообщают CodeQL CLI, как компилировать запросы, от каких других пакетов и библиотек CodeQL зависит пакет, а также где найти определения наборов запросов. Дополнительные сведения о том, что следует включить в этот файл, см. в разделе Сведения о пакетах CodeQL.
Участие в работе с репозиторием CodeQL
Если вы хотите поделиться запросом с другими пользователями CodeQL, можно открыть запрос на вытягивание в репозитории CodeQL. Дополнительные сведения см. в статье Участие в разработке CodeQL.