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

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

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

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

> \[!NOTE]
> Запросы выполняются с `database analyze` строгими [требованиями](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#including-query-metadata) к метаданным. Вы также можете выполнять запросы с помощью следующих подкомандах уровня сантехники:
>
> *

[запросы запуска базы данных](/ru/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-run-queries), который выводит не интерпретируемые результаты в промежуточном двоичном формате, называемом [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file).

> \*
> [выполнение запроса](/ru/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/query-run), который выводит файлы BQRS или печатает таблицы результатов непосредственно в командной строке. Просмотр результатов непосредственно в командной строке может оказаться полезным для итеративной разработки запросов с помощью интерфейса командной строки.
>
> Запросы, выполняемые с этими командами, не имеют одинаковых требований к метаданным. Однако для сохранения данных, доступных для чтения, необходимо обработать каждый файл результатов BQRS с помощью [подкоманда autoTITLE](/ru/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-decode) сантехники. Поэтому для большинства вариантов использования проще всего использовать анализ базы данных для непосредственного создания интерпретированных результатов.

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

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

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

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

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

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

> \[!NOTE]
> Требования к метаданным могут отличаться, если вы хотите использовать запрос с другими приложениями. Для получения дополнительной информации смотрите [раздел Метаданные для CodeQL запросов](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).

Для получения дополнительной информации о метаданных запросов смотрите [раздел «Метаданные» для CodeQL запросов](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) и [руководство по стилю метаданных запросов](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md).

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

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

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

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

Для получения дополнительной информации смотрите [в разделе «Запрос в файлы справки](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files)».

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

Вы можете делиться пользовательскими запросами с сообществом, публикуя собственные пакеты запросов. См [. раздел AUTOTITLE](/ru/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/publish-and-use-packs).

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

* [Написание пользовательских запросов для CodeQL CLI](/ru/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/write-custom-queries)
* [
  CodeQL Запросов](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)