Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.
Sobre consultas personalizadas e a CodeQL CLI
Você pode personalizar as análises do CodeQL escrevendo as próprias consultas para realçar vulnerabilidades ou erros específicos.
Este tópico trata especificamente da criação de consultas a serem usadas com o comando database analyze para produzir os resultados interpretados.
Observação: as consultas executadas com database analyze
têm requisitos estritos de metadados. Você também pode executar consultas usando os seguintes subcomandos no nível do plumbing:
- database run-queries, que gera resultados não interpretados em um formato binário intermediário chamado BQRS.
- 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. Portanto, para a maioria dos casos de uso, é mais fácil usar a análise de banco de dados para gerar diretamente resultados interpretados.
Como gravar uma consulta válida
Antes de executar uma análise personalizada, você precisa escrever uma consulta válida e salvá-la em um arquivo com uma extensão .ql
. Há uma documentação abrangente disponível para ajudar você a escrever consultas. Para obter mais informações, confira "Consultas do CodeQL".
Como incluir metadados de consulta
Os metadados de consulta são incluídos na parte superior de cada arquivo de consulta. Ele fornece aos usuários informações sobre a consulta e informa à CodeQL CLI como processar os resultados da consulta.
Ao executar consultas com o comando database analyze
, você precisa incluir estas duas propriedades para garantir que os resultados sejam interpretados corretamente:
-
Identificador de consulta (
@id
): uma sequência de palavras composta por letras minúsculas ou dígitos, delimitadas por/
ou-
, identificando e classificando a consulta. -
Tipo de consulta (
@kind
): identifica a consulta como um alerta simples (@kind problem
), um alerta documentado por uma sequência de locais de código (@kind path-problem
), para solução de problemas do extrator (@kind diagnostic
) ou uma métrica de resumo (@kind metric
e@tags summary
).
Para obter mais informações sobre essas propriedades de metadados, confira "Metadados para consultas do CodeQL" e o Guia de estilo de metadados de consulta.
Observação: 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".
Como contribuir para o repositório do CodeQL
Se você quiser compartilhar a consulta com outros usuários do CodeQL, abra uma solicitação de pull no repositório do CodeQL. Para obter mais informações, confira Como contribuir para o CodeQL.