# Пользовательские запросы 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/code-security/codeql-cli/codeql-cli-manual/database-run-queries), который выводит не интерпретируемые результаты в промежуточном двоичном формате, называемом [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file).
> * [выполнение запроса](/ru/code-security/codeql-cli/codeql-cli-manual/query-run), который выводит файлы BQRS или печатает таблицы результатов непосредственно в командной строке. Просмотр результатов непосредственно в командной строке может оказаться полезным для итеративной разработки запросов с помощью интерфейса командной строки.
>
> Запросы, выполняемые с этими командами, не имеют одинаковых требований к метаданным. Однако для сохранения данных, доступных для чтения, необходимо обработать каждый файл результатов BQRS с помощью [подкоманда autoTITLE](/ru/code-security/codeql-cli/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` файлы**: В соответствии со стандартными запросами CodeQL, но должны быть преобразованы в Markdown для использования с code scanning
  ```

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

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

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

Вы можете делиться пользовательскими запросами с сообществом, публикуя собственные пакеты запросов. См [. раздел AUTOTITLE](/ru/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs).

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

* ```
          [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)
  ```