# Consultas CodeQL personalizadas

As consultas personalizadas estendem a análise de segurança integrada do CodeQL para detectar vulnerabilidades e aplicar padrões de codificação específicos à sua base de código.

## O que são consultas personalizadas CodeQL ?

As consultas personalizadas estendem CodeQL a análise de segurança integrada para detectar vulnerabilidades, normas de codificação e padrões específicos da sua base de código.

> \[!NOTE]
> As consultas executadas com `database analyze` têm [requisitos estritos de metadados](https://codeql.github.com/docs/codeql-cli/using-custom-queries-with-the-codeql-cli/#including-query-metadata). Você também pode executar consultas usando os seguintes subcomandos no nível do plumbing:
>
> * [executar consultas no banco de dados](/pt/enterprise-server@3.19/code-security/codeql-cli/codeql-cli-manual/database-run-queries), que gera resultados não interpretados em um formato binário intermediário chamado [BQRS](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#bqrs-file).
> * [query run](/pt/enterprise-server@3.19/code-security/codeql-cli/codeql-cli-manual/query-run), que produzirá arquivos BQRS ou imprimirá tabelas de resultados diretamente na linha de comando. Pode ser útil ver os resultados diretamente na linha de comando no caso de desenvolvimento de consultas iterativas usando a CLI.
>
> As consultas executadas com esses comandos não têm os mesmos requisitos de metadados. No entanto, para salvar dados legíveis por humanos, você precisa processar cada arquivo de resultados BQRS usando o subcomando de conexão de [bqrs decode](/pt/enterprise-server@3.19/code-security/codeql-cli/codeql-cli-manual/bqrs-decode). Portanto, para a maioria dos casos de uso, é mais fácil usar a análise de banco de dados para gerar diretamente resultados interpretados.

## Quando usar consultas personalizadas

Use consultas personalizadas para:

* Detectar vulnerabilidades específicas à arquitetura ou às estruturas do aplicativo
* Impor padrões de codificação ou práticas recomendadas específicas da organização
* Localizar padrões não cobertos por pacotes de consulta padrão CodeQL
* Analisar CodeQL bancos de dados com o `database analyze` comando usando o CodeQL CLI para produzir resultados interpretados

## Estrutura da consulta

Consultas personalizadas são gravadas em arquivos de consulta, que são salvos com a `.ql` extensão. Esses arquivos também contêm metadados importantes que fornecem informações sobre a finalidade da consulta e informa como processar resultados CodeQL CLI . As propriedades necessárias incluem:

* **Identificador de consulta (`@id`)**: letras minúsculas ou dígitos, delimitados por `/` ou `-`
* **Tipo de consulta (`@kind`)**: um de:
  * `problem` - Alerta simples
  * `path-problem` - Alerta com sequência de código de localização
  * `diagnostic` - Solução de problemas do extrator
  * `metric` - Métrica resumida (requer `@tags summary`)

> \[!NOTE]
> Os requisitos de metadados poderão ser diferentes se você quiser usar a consulta com outros aplicativos. Para obter mais informações, consulte [Metadados para CodeQL consultas](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).

Para obter mais informações sobre metadados de consulta, consulte [Metadados para CodeQL consultas](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) e o [guia de estilo de metadados de consulta](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md).

## Documentação de consulta

A documentação da consulta ajuda os usuários a entender o que uma consulta detecta e como resolver problemas identificados. Você pode incluir a documentação para suas consultas personalizadas em dois formatos:

* **Arquivos Markdown**: são salvos junto com a consulta, podem ser incluídos em arquivos SARIF e exibidos na code scanning interface do usuário
* **`.qhelp` arquivos**: consistente com as consultas padrão CodeQL, mas devem ser convertidos em Markdown para uso com code scanning

Quando arquivos SARIF que contêm a ajuda da consulta são carregados em GitHub, a documentação aparece na interface de usuário de code scanning para todos os alertas gerados pela consulta.

Para obter mais informações, consulte [arquivos de ajuda de](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) consulta.

## Compartilhamento de consultas personalizadas

Você pode compartilhar consultas personalizadas com a comunidade publicando seus próprios pacotes de consulta. Consulte [Publicar e usar pacotes do CodeQL](/pt/enterprise-server@3.19/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs).

## Leitura adicional

* [Escrevendo consultas personalizadas para a CLI do CodeQL](/pt/enterprise-server@3.19/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)
* [
  CodeQL consultas](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)