# Consultas CodeQL personalizadas

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

## O que são consultas CodeQL personalizadas?

As consultas personalizadas expandem a análise de segurança interna do CodeQL para detectar vulnerabilidades, padrões de codificação e padrões específicos à 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-cloud@latest/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-cloud@latest/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-cloud@latest/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 que não são cobertos pelos pacotes de consulta padrão do CodeQL
* Analise bancos de dados CodeQL com o comando `database analyze` 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 ao CodeQL CLI como processar resultados. 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, confira [Metadados para consultas do CodeQL](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 os [Metadados para consultas CodeQL](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 de markdown**: salvos junto com a consulta, podem ser incluídos em arquivos SARIF e exibidos na interface do usuário code scanning
  ```
* ```
            Arquivos**`.qhelp`**: consistentes com as consultas padrão CodeQL, mas devem ser convertidos em markdown para uso com code scanning
  ```

Quando arquivos SARIF que contêm ajuda de consulta são carregados em GitHub, a documentação aparece na interface do usuário code scanning para quaisquer 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. Confira [Publicar e usar pacotes do CodeQL](/pt/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/publishing-and-using-codeql-packs).

## Leitura adicional

* ```
          [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/using-custom-queries-with-the-codeql-cli)
  ```
* ```
          [Consultas CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)
  ```