Como executar consultas do CodeQL

Sobre a execução de CodeQL consultas

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 CodeQL banco de dados extraído do código, portanto, você precisará selecionar um banco de dados com o qual trabalhar na extensão. Você pode selecionar um banco de dados localmente (em um arquivo zip ou uma pasta não pesquisada), em uma URL pública ou na URL de um projeto.GitHub.com Para obter mais informações, consulte 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 CodeQL extensão 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 na exibição "Resultados da CodeQL Consulta".

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: Executar Consultas em Arquivos Selecionados.

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: Consulta Rápida no VS Code Command Palette, e em seguida, para executar a consulta, use CodeQL: Executar Consulta no Banco de Dados Selecionado.

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.

Depois de ficar satisfeito com sua consulta rápida, você deve salvá-la em um CodeQL pacote para poder acessá-la mais tarde. Para obter mais informações, consulte 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: Executar Consulta no Banco de Dados Selecionado para executar toda a consulta (a cláusula select e quaisquer predicados de consulta), você pode usar CodeQL: Avaliação Rápida para executar uma parte específica de um .ql ou .qll arquivo.

          **
          CodeQL: a Avaliação Rápida** avalia um snippet de código que você selecionou, em vez de toda a consulta, 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:

• Selecionando o nome de uma CodeQL entidade (como uma classe ou 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: Executar Consulta em Vários Bancos de Dados.

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 mais informações, consulte CodeQL consultas.

2. Utilize o menu suspenso na visualização "Resultados" para escolher os resultados a serem exibidos e em qual formato apresentá-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 CodeQL consulta 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 log for muito grande para a extensão abri-lo em VS Code, o arquivo será exibido no seu 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 CodeQL Servidor de Consultas. Para obter mais informações, consulte Acessando logs em CodeQL em Visual Studio Code.

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, consulte Configurações personalizadas.

Você pode usar o CodeQLcomando : Reiniciar o Servidor de Consultas para reiniciar o servidor de consulta. Isso reinicia o servidor sem afetar o histórico CodeQL da sessão. É 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 CodeQL que está aberto em VS Code. Além de problemas no log, você também poderá ver: erros no destaque de código, totais de resultados incorretos ou notificações duplicadas de execução de uma consulta.

Próximas Etapas 

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

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