Esta versão do GitHub Enterprise Server foi descontinuada em 2023-09-12. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise Server. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Como usar consultas personalizadas com a CLI do CodeQL

Neste artigo

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

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.

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.

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:

  • 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 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.

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".

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.

Leitura adicional