Como executar consultas do CodeQL

Sobre executar consultas do CodeQL

O repositório github/codeql contém um número grande de consultas de exemplo. Você pode acessar qualquer consulta existente em seu espaço de trabalho pelo modo de exibição "Consultas".

Pré-requisitos

Para analisar uma base de código, execute consultas em um banco de dados do CodeQL extraído do código, dessa forma, você precisará selecionar um banco de dados para trabalhar com a extensão. Você pode selecionar um banco de dados localmente (de um arquivo ZIP ou de uma pasta não arquivada), de uma URL pública ou da URL de um projeto em GitHub.com. Para obter mais informações, confira "Como gerenciar bancos de dados do CodeQL".

Como executar uma só consulta

1. Na barra lateral, abra o modo de exibição "Consultas".

2. Para executar uma consulta no banco de dados selecionado, passe o mouse sobre a consulta desejada e clique no ícone de Executar consulta local.

A extensão do CodeQL executa a consulta no banco de dados atual e relata o progresso no canto inferior direito do aplicativo. Quando os resultados estiverem prontos, eles serão exibidos no modo exibição "Resultados da Consulta" do CodeQL.

Se houver algum problema ao executar uma consulta, uma notificação será exibida no canto inferior direito do aplicativo. Além da mensagem de erro, a notificação inclui detalhes de como corrigir o problema.

Como executar todas as consultas em um diretório

Você pode executar todas as consultas em um diretório.

1. Na barra lateral, abra o modo de exibição "Consultas".

2. Passe o mouse sobre o diretório desejado de consultas e clique no ícone de Executar consultas locais.

Executar uma seleção de consultas

Você pode executar várias consultas com um único comando.

1. Acesse o Explorador de Arquivos.

2. Selecione vários arquivos ou pastas que contenham consultas.

3. Clique com o botão direito do mouse e selecione CodeQL: Run Queries in Selected Files.

Executar uma consulta sem qualquer configuração

Ao trabalhar em uma nova consulta, você pode abrir uma guia "Consulta Rápida" para executar facilmente seu código e visualizar os resultados, sem precisar salvar um arquivo .ql em seu espaço de trabalho. Selecione CodeQL: Quick Query no VS Code Command Palette e, para então executar a consulta, use CodeQL: Run Query on Selected Database.

Você pode ver todas as consultas rápidas executadas na sessão atual no modo de exibição "Histórico de Consultas". Clique em uma entrada para ver o texto exato da consulta rápida que produziu os resultados. Para obter mais informações, confira "Exibir seu histórico de consultas".

Quando estiver satisfeito com sua consulta rápida, salve-a em um pacote do CodeQL para poder acessá-la mais tarde. Para obter mais informações, confira "Como personalizar a análise com pacotes CodeQL".

Executar uma parte específica de uma consulta ou biblioteca

Isso poderá ser útil caso esteja depurando uma consulta ou biblioteca e queira localizar a parte que está errada.

Em vez de usar CodeQL: Run Query on Selected Database para executar a consulta toda (a cláusula select e quaisquer predicados de consulta), você pode usar CodeQL: Quick Evaluation para executar uma parte específica de um arquivo .ql ou .qll.

CodeQL: Quick Evaluation avalia um snippet de código selecionado, em vez da consulta toda, e exibe os resultados dessa seleção no modo de exibição "Resultados".

Os possíveis propósitos para uma avaliação rápida incluem:

• Selecionar o nome de uma entidade do CodeQL (como uma classe ou um predicado) para avaliar essa entidade.

• Selecionar uma fórmula ou expressão com variáveis livres para avaliar essa fórmula ou expressão.

Por exemplo, no snippet a seguir, você pode selecionar o nome do predicado foo ou a fórmula s = "bar" para uma avaliação rápida:

predicate foo(string s) { s = "bar" }

Executar uma consulta em vários bancos de dados

Isso poderá ser útil se você quiser testar sua consulta em várias bases de código ou quiser encontrar uma vulnerabilidade em vários projetos.

1. Abra um arquivo de consulta (.ql).

2. Clique com o botão direito do mouse e selecione CodeQL: Run Query on Multiple Databases.

3. No menu suspenso, selecione o banco de dados no qual deseja executar a consulta.

Exibir seu histórico de consultas

Para ver as consultas executadas na sessão atual, abra o modo de exibição "Histórico de Consultas".

O modo de exibição "Histórico de Consultas" contém informações, incluindo a data e a hora em que a consulta foi executada, o nome da consulta, o banco de dados no qual ela foi executada e quanto tempo levou para executar a consulta:

• Para personalizar as informações exibidas, clique com o botão direito do mouse em uma entrada e selecione Renomear.

• Opcionalmente, filtre a exibição por linguagem usando o seletor de linguagem. Para obter mais informações, confira "Filtrar bancos de dados e consultas por linguagem".

• Clique em uma entrada para exibir os resultados correspondentes e clique duas vezes para exibir a própria consulta no editor (ou clique com o botão direito do mouse e selecione Exibir Consulta).

• Para exibir o texto exato que produziu os resultados de uma entrada específica, clique com o botão direito do mouse nele e selecione Exibir Texto da Consulta. Isso pode ser diferente de Exibir Consulta, pois o arquivo de consulta pode ter sido modificado desde a última vez que você o executou.

• Para remover consultas do modo de exibição, selecione todas as consultas que deseja remover, clique com o botão direito do mouse e selecione Excluir.

Compreender os resultados das consultas

1. Clique em uma consulta no modo de exibição "Histórico de Consultas" para exibir os resultados no modo de exibição "Resultados".

   Observação: dependendo da consulta, você também pode escolher diferentes modos de exibição, como CSV, Saída SARIF da CLI do CodeQL ou formato DIL. Por exemplo, para exibir o formato DIL, clique com o botão direito do mouse em um resultado e selecione Modo de exibição DIL. Os modos de exibição de saída disponíveis são determinadas pelo formato e pelos metadados da consulta. Para obter mais informações, confira "Consultas do CodeQL".

2. Use o menu suspenso no modo de exibição "Resultados" para escolher quais resultados exibir e de que forma exibi-los, como uma mensagem de alerta formatada ou uma tabela de resultados brutos.

3. Para classificar os resultados pelas entradas em uma coluna específica, clique no cabeçalho da coluna.

Se um resultado for vinculado a um elemento do código-fonte, você poderá clicar nele para exibi-lo na origem.

Para usar os recursos de navegação de código padrão no código-fonte, você pode clicar com o botão direito do mouse em um elemento e usar os comandos Go to Definition ou Go to References. Isso executa uma consulta do CodeQL no arquivo ativo, o que pode levar alguns segundos. Essa consulta precisa ser executada uma vez para cada arquivo, portanto, quaisquer referências adicionais do mesmo arquivo serão rápidas.

Comparar resultados de consultas

Quando você está escrevendo ou depurando uma consulta, é útil ver como suas alterações afetam os resultados. Você pode comparar dois conjuntos de resultados para ver exatamente o que mudou. Para comparar os resultados, as duas consultas devem ser executadas no mesmo banco de dados.

1. Clique com o botão direito do mouse em uma consulta no modo de exibição "Histórico de Consultas" e selecione Comparar Resultados.

2. Um menu de Escolha Rápida mostra todas as consultas válidas com as quais comparar. Selecione uma consulta.

3. O modo de exibição "Comparar" mostra as diferenças nos resultados das duas consultas.

Solução de problemas

Para ver os logs da execução de uma consulta específica, clique com o botão direito do mouse na consulta no modo de exibição "Histórico de Consultas" e selecione Mostrar Log de Consultas. Se o arquivo de registro for muito grande para que a extensão seja aberta no VS Code, o arquivo será exibido no explorador de arquivos para que você possa abri-lo com um programa externo.

Para obter detalhes sobre como compilar e executar consultas, bem como informações sobre atualizações de banco de dados, verifique o log do servidor de consulta do CodeQL. Para obter mais informações, confira "Acessando os logs".

Por padrão, a extensão exclui logs após cada sessão do espaço de trabalho. Para substituir esse comportamento, você pode especificar um diretório personalizado para logs do servidor de consulta. Para obter mais informações, confira "Configurações personalizadas".

Você pode usar o comando CodeQL: Restart Query Server para reiniciar o servidor de consulta. Isso reinicia o servidor sem afetar o histórico de sessão do CodeQL. É mais provável que você precise reiniciar o servidor de consulta se fizer alterações externas nos arquivos que a extensão está usando. Por exemplo, regenerar um banco de dados do CodeQL aberto no VS Code. Além de problemas no log, você também poderá ver: erros no realce de código, totais de resultados incorretos ou notificações duplicadas de uma consulta que está sendo executada.

Próximas etapas

Opcionalmente, você pode usar a extensão para criar suas próprias consultas personalizadas. Para obter mais informações, confira "Criar uma consulta personalizada".

Para obter informações sobre como executar análises em escala em muitos bancos de dados do CodeQL, confira "Executar consultas do CodeQL em escala com análise de variantes de vários repositórios".