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.

Quem pode usar esse recurso?

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

Neste artigo

O que são consultas personalizadas CodeQL ?

As consultas personalizadas estendem a análise de segurança incorporada do CodeQL para detectar vulnerabilidades, padrões de codificação e características específicas à sua base de código.

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:

  • executar consultas no banco de dados, 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.

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
  • Analisar CodeQL bancos de dados com o database analyze comando 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)

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.

Para obter mais informações sobre metadados de consulta, consulte os Metadados para consultas CodeQL e o Guia de Estilo de Metadados de Consulta.

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 markdown**: salvos junto com a consulta, podem ser incluídos em arquivos SARIF e exibidos na interface do usuário code scanning

  •         **
        `.qhelp` arquivos**: Consistente com as consultas padrão CodeQL, mas deve ser convertido 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 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.

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)