Escrever e compartilhar 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.

Empacotando consultas personalizadas

Ao escrever consultas para compartilhar com outras pessoas, salve-as em um pacote personalizado CodeQL.

Para empacotar suas consultas personalizadas:

  1. Crie um pacote CodeQL com um arquivo qlpack.yml no diretório raiz.
  2. Salve suas consultas personalizadas (arquivos .ql) na raiz do pacote ou em seus subdiretórios.
  3. Configure o qlpack.yml arquivo para especificar:
    • Como compilar as consultas
    • Dependências de outros pacotes e bibliotecas CodeQL
    • Definições do conjunto de consultas Para obter mais informações sobre qlpack.yml propriedades, consulte Como personalizar a análise com pacotes CodeQL.
  4. Publique seu pacote no GitHub Packages, o GitHub Container registry. Para saber mais, confira Como personalizar a análise com pacotes CodeQL.

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)

    •           Arquivo **              `.qhelp`**: escreva a ajuda de consulta no formato `.qhelp` e converta-a em markdown antes de executar a análise. Para obter mais informações, confira [Arquivos de ajuda de consulta](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) e [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files).

  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 opção --sarif-add-query-help está disponível em CodeQL CLI v2.7.1 em diante.

  3. Carregue o arquivo SARIF no .

Leitura adicional

  •         [Consultas CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)