Примечание: Эта статья была перенесена с веб-сайта документации По CodeQL в январе 2023 г.
Сведения о пользовательских запросах и CodeQL CLI
Вы можете настроить анализ CodeQL, написав собственные запросы, чтобы выделить определенные уязвимости или ошибки.
В этом разделе описывается, в частности, написание запросов для использования с командой анализа базы данных для получения интерпретируемых результатов.
Примечание: Запросы, выполняемые с database analyze использованием строгих требований к метаданным. Вы также можете выполнять запросы, используя следующие подкоманды уровня сантехники:
- run-queries, который выводит не интерпретируемые результаты в промежуточном двоичном формате, называемом BQRS.
- выполните запрос, который выведет BQRS-файлы или выведет таблицы результатов непосредственно в командную строку. Просмотр результатов непосредственно в командной строке может быть полезен для итеративной разработки запросов с помощью CLI.
Запросы, выполняемые с помощью этих команд, не имеют одинаковых требований к метаданным. Однако для сохранения доступных для чтения данных необходимо обработать каждый файл результатов BQRS с помощью подкоманды декодирования bqrs . Поэтому в большинстве случаев проще всего использовать анализ базы данных для непосредственного создания интерпретированных результатов.
Написание допустимого запроса
Перед выполнением пользовательского анализа необходимо написать допустимый запрос и сохранить его в файле с расширением .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.