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.
Note
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 metrice@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.
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.
Como empacotar consultas QL personalizadas
Ao escrever as próprias consultas com a intenção de compartilhá-las com outras pessoas, você deve salvá-las em um pacote personalizado do CodeQL. Você pode publicar o pacote como um pacote do CodeQL no GitHub Packages – O Container registry do GitHub. Para saber mais, confira Como personalizar a análise com pacotes CodeQL.
Os pacotes do CodeQL organizam os arquivos usados na análise do CodeQL e podem armazenar consultas, arquivos de biblioteca, conjuntos de consultas e metadados importantes. O diretório raiz precisa conter um arquivo chamado qlpack.yml. As consultas personalizadas devem ser salvas na raiz do pacote do CodeQL ou nos respectivos subdiretórios.
Para cada pacote do CodeQL, o arquivo qlpack.yml inclui informações que dizem à CodeQL CLI como compilar as consultas, de quais outros pacotes e bibliotecas do CodeQL o pacote depende e onde encontrar as definições do conjunto de consultas. Para obter mais informações sobre o que incluir neste arquivo, confira Como personalizar a análise com pacotes CodeQL.
Como incluir a ajuda de consulta para consultas personalizadas do CodeQL em arquivos SARIF
Se você usar a CodeQL CLI para executar análises de verificação de código em sistemas de CI/CD de terceiros, poderá incluir a ajuda de consulta nas consultas personalizadas nos arquivos SARIF gerados durante uma análise. Depois de carregar o arquivo SARIF no GitHub, a ajuda de consulta será mostrada na interface do usuário de verificação de código para os alertas gerados pelas consultas personalizadas.
Da CodeQL CLI v2.7.1 em diante, você pode incluir a ajuda de consulta renderizada por markdown em arquivos SARIF fornecendo a opção --sarif-add-query-help ao executar codeql database analyze.
Você pode escrever uma ajuda de consulta para consultas personalizadas diretamente em um arquivo markdown e salvá-la junto com a consulta correspondente. Como alternativa, para consistência com as consultas padrão do CodeQL, você pode escrever a ajuda de consulta no formato .qhelp. A ajuda de consulta escrita em arquivos .qhelp não pode ser incluída em arquivos SARIF e não pode ser processada pela verificação de código, portanto, precisa ser convertida em markdown antes da execução da análise. Para obter mais informações, confira Arquivos de ajuda de consulta e Como testar arquivos de ajuda de consulta.
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.