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

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

Кто может использовать эту функцию?

CodeQL доступен для следующих типов репозитория:

В этой статье

Что такое пользовательские CodeQL запросы?

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

Примечание.

Запросы выполняются с database analyze строгими требованиями к метаданным. Вы также можете выполнять запросы с помощью следующих подкомандах уровня сантехники:

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

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

Когда использовать пользовательские запросы

Используйте пользовательские запросы, чтобы:

  • Выявляйте уязвимости, специфичные для архитектуры или фреймворков вашего приложения
  • Обеспечивать соблюдение специфических стандартов или лучших практик кодирования, специфичных для организации
  • Найти шаблоны, не охватываемые стандартными CodeQL пакетами запросов
  • Анализировать CodeQL базы данных с database analyze помощью команды CodeQL CLI для получения интерпретируемых результатов

Структура запроса

Пользовательские запросы пишутся в файлах запросов, которые сохраняются вместе с расширением .ql . Эти файлы также содержат важные метаданные, предоставляющие информацию о назначении запроса и сообщающие CodeQL CLI, как обрабатывать результаты. Обязательные объекты включают:

  •         **Идентификатор запроса (`@id`)**: строчные буквы или цифры, ограниченные или `/``-`

  •         **Тип запроса (`@kind`)**: Один из:
    * problem - Простое оповещение * path-problem - Оповещение с последовательностью местоположения кода * diagnostic - Устранение неисправностей экстрактора * metric - Суммарная метрика (требуется @tags summary)

Примечание.

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

Для получения дополнительной информации о метаданных запросов см. раздел Метаданные для запросов CodeQL и руководство по стилю метаданных запросов.

Документация запросов

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

  •         **Файлы Markdown**: Сохраняются вместе с запросом, могут быть включены в файлы SARIF и отображаются в интерфейсе code scanning

  •         **
        `.qhelp` файлы**: В соответствии со стандартными запросами CodeQL, но должны быть преобразованы в Markdown для использования с code scanning

Когда файлы SARIF с помощью по запросу загружаются в GitHub, документация отображается в интерфейсе code scanning для любых оповещений, сгенерированных запросом.

Для получения дополнительной информации смотрите в разделе «Запрос в файлы справки».

Обмен пользовательскими запросами

Вы можете делиться пользовательскими запросами с сообществом, публикуя собственные пакеты запросов. См . раздел AUTOTITLE.

Дополнительные материалы

  •         [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)

  •         [Запросы CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)