Consultas CodeQL personalizadas

As consultas personalizadas estendem a análise de segurança integrada do CodeQL para detectar vulnerabilidades e aplicar 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 CodeQL a análise de segurança integrada para detectar vulnerabilidades, normas de codificação e padrões específicos da 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 não cobertos por pacotes de consulta padrão 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 como processar resultados CodeQL CLI . 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, consulte Metadados para CodeQL consultas.

Para obter mais informações sobre metadados de consulta, consulte Metadados para CodeQL consultas 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: são salvos junto com a consulta, podem ser incluídos em arquivos SARIF e exibidos na code scanning interface do usuário
  • .qhelp arquivos: consistente com as consultas padrão CodeQL, mas devem ser convertidos em Markdown para uso com code scanning

Quando arquivos SARIF que contêm a ajuda da consulta são carregados em GitHub, a documentação aparece na interface de usuário de code scanning para todos os 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. Consulte Publicar e usar pacotes do CodeQL.

Leitura adicional