Escrevendo consultas personalizadas para a CLI do CodeQL

Você pode escrever as próprias consultas do CodeQL para encontrar vulnerabilidades e erros específicos.

Quem pode usar esse recurso?

O CodeQL está disponível para os seguintes tipos de repositórios:

Neste artigo

Este artigo é especificamente sobre como escrever consultas a serem usadas com o comando análise de banco de dados para produzir resultados interpretados. Para obter informações conceituais sobre consultas personalizadas, consulte Consultas CodeQL personalizadas.

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

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.

Como incluir a ajuda de consulta para consultas personalizadas do CodeQL em arquivos SARIF

Para obter informações sobre a ajuda de consulta e os formatos de documentação, consulte Consultas CodeQL personalizadas.

Para incluir a ajuda de consulta em arquivos SARIF ao executar análises de verificação de código:

  1. Escreva a ajuda de consulta em um dos seguintes formatos: * Arquivo markdown: salvar um arquivo Markdown junto com sua consulta com o mesmo nome (por exemplo, my-query.md para my-query.ql) * ** .qhelp arquivo**: escreva a ajuda de consulta no formato e converta-a em .qhelp Markdown antes de executar a análise. Para obter mais informações, confira Arquivos de ajuda de consulta e Como testar arquivos de ajuda de consulta.

  2. Execute codeql database analyze com a opção --sarif-add-query-help :

    codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

    Observação

    A --sarif-add-query-help opção está disponível em CodeQL CLI v2.7.1 em diante.

  3. Carregue o arquivo SARIF no .

Próximas Etapas 

Para compartilhar e usar suas consultas personalizadas, consulte Publicar e usar pacotes do CodeQL.