Introdução à CLI do CodeQL

Introdução à CodeQL CLI

Para executar comandos do CodeQL, você precisa configurar a CLI para que ela possa acessar as ferramentas, as consultas e as bibliotecas necessárias para criar e analisar bancos de dados.

Como configurar a CodeQL CLI

A CodeQL CLI pode ser configurada para dar suporte a vários casos de uso e estruturas de diretório diferentes. Para começar rapidamente, recomendamos adotar uma configuração simples, conforme as etapas abaixo descrevem.

Se você usa Linux, Windows ou macOS versão 10.14 ("Mojave") ou anterior, basta seguir as etapas abaixo. Para macOS versão 10.15 ("Catalina") ou mais recente, há observações adicionais para algumas das etapas. Se você estiver usando o macOS no Apple Silicon (por exemplo, Apple M1), verifique se as Ferramentas para desenvolvedores de linha de comando do Xcode e o Rosetta 2 estão instalados.

Para obter informações de como instalar a CodeQL CLI em um sistema de CI para criar resultados a serem exibidos no GitHub como alertas de verificação de código, confira Como instalar a CodeQL CLI no sistema de CI.

1. Baixar o pacote zip da CodeQL CLI

O pacote de download do CodeQL CLI é um arquivo zip que contém ferramentas, scripts e vários arquivos específicos do CodeQL. Se você não tiver uma licença do GitHub Enterprise, baixando esse arquivo, você estará concordando com os termos e condições do GitHub CodeQL.

Se você usa o Linux, o Windows ou o macOS versão 10.14 ("Mojave") ou anterior, basta baixar o arquivo zip da versão necessária.

Se você quiser a CLI para uma plataforma específica, baixe o arquivo codeql-PLATFORM.zip apropriado. Como alternativa, você pode baixar codeql.zip, que contém a CLI para todas as plataformas compatíveis.

Informações de download para usuários do macOS "Catalina" (ou mais recente)

Se você usa o macOS versão 10.15 ("Catalina"), versão 11 ("Big Sur" ou a versão 12 futura ("Monterey"), verifique se o navegador da Web não extrai arquivos zip automaticamente. Se você usa o Safari, conclua as seguintes etapas antes de baixar o arquivo zip da CodeQL CLI:

1. Abra o Safari.
2. No menu do Safari, selecione Preferências… .
3. Clique na guia Geral.
4. Verifique se a caixa de seleção Abrir arquivos "seguros" após o download está desmarcada.

2. Extrair o arquivo zip

Para usuários do Linux, do Windows e do macOS (versão 10.14 "Mojave" e anteriores), basta extrair o arquivo zip.

Informações de extração para usuários do macOS "Catalina" (ou mais recente)

Os usuários do macOS "Catalina", "Big Sur" ou "Monterey" devem executar os seguintes comandos no Terminal, em que ${extraction-root} é o caminho para o diretório em que você extrairá o arquivo zip da CodeQL CLI:

1. mv ~/Downloads/codeql\*.zip ${extraction-root}
2. cd ${extraction-root}
3. /usr/bin/xattr -c codeql\*.zip
4. unzip codeql\*.zip

3. Iniciar o codeql

Após a extração, você poderá executar processos do CodeQL executando o executável codeql de algumas maneiras:

• Ao executar <extraction-root>/codeql/codeql, em que <extraction-root> é a pasta na qual você extraiu o pacote da CodeQL CLI.
• Adicione o <extraction-root>/codeql ao PATH, para que você possa executar o executável apenas como codeql.

Neste ponto, você pode executar comandos do CodeQL. Para obter uma lista completa dos comandos da CodeQL CLI, confira o "Manual da CodeQL CLI".

4. Verificar a configuração da CodeQL CLI

A CodeQL CLI tem subcomandos que você pode executar para verificar se está tudo configurado corretamente para a criação e análise de bancos de dados:

• Execute codeql resolve languages para mostrar quais linguagens estão disponíveis para a criação do banco de dados. Isso listará as linguagens com suporte por padrão no pacote da CodeQL CLI.

• (Opcional) Você pode baixar alguns "pacotes do CodeQL" que contêm as consultas pré-compiladas que deseja executar. Para fazer isso, execute codeql pack download <pack-name> [...pack-name], em que pack-name é o nome do pacote que você deseja baixar. Os pacotes de consultas principais são uma boa opção para começar. Eles são:

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

Como alternativa, você pode baixar pacotes de consultas durante a análise usando o sinalizador --download do comando codeql database analyze.

Como conferir o código-fonte do CodeQL diretamente

Alguns usuários preferem usar fontes de consulta do CodeQL diretamente para trabalhar com consultas compartilhadas de código aberto ou contribuir para elas. Para isso, são recomendadas as etapas a seguir. Observe que as instruções a seguir são uma alternativa um pouco mais complicada para trabalhar com pacotes do CodeQL, conforme a explicação acima.

1. Baixar o zip da CodeQL CLI

Siga a etapa 1 da seção anterior.

2. Criar um diretório do CodeQL

Crie um diretório no qual você pode colocar a CLI e todas as consultas e bibliotecas que deseja usar. Por exemplo, $HOME/codeql-home.

As operações de pesquisa internas da CLI procuram automaticamente em todos os diretórios irmãos os arquivos usados na criação e na análise do banco de dados. Com esses componentes no próprio diretório, a CLI não pesquisa diretórios irmãos não relacionados, garantindo que todos os arquivos estejam disponíveis sem especificar outras opções na linha de comando.

3. Obter uma cópia local das consultas do CodeQL

O repositório do CodeQL contém as consultas e as bibliotecas necessárias para que o CodeQL analise todas as linguagens com suporte. Clone uma cópia desse repositório em codeql-home.

Por padrão, a raiz do repositório clonado será chamada de codeql. Renomeie essa pasta codeql-repo para evitar conflitos com a CodeQL CLI que você extrairá na etapa 4. Se você usar o Git na linha de comando, poderá clonar e renomear o repositório em uma só etapa executando git clone git@github.com:github/codeql.git codeql-repo na pasta codeql-home.

Nesse repositório, as consultas e as bibliotecas são organizadas em pacotes do CodeQL. Junto com as consultas, os pacotes do CodeQL contêm metadados importantes que informam à CodeQL CLI como processar os arquivos de consulta. Para obter mais informações, confira "Sobre os pacotes do CodeQL".

4. Extrair o arquivo zip

Para usuários do Linux, Windows e macOS (versão 10.14 "Mojave" e anteriores), basta extrair o arquivo zip no diretório que você criou na etapa 2.

Por exemplo, se o caminho para a cópia do repositório do CodeQL for $HOME/codeql-home/codeql-repo, extraia a CLI para $HOME/codeql-home/.

5. Iniciar codeql

Confira a etapa 3 da seção anterior.

6. Verificar a configuração da CodeQL CLI

A CodeQL CLI tem subcomandos que você pode executar para verificar se está tudo configurado corretamente para a criação e análise de bancos de dados:

• Execute codeql resolve languages para mostrar quais linguagens estão disponíveis para a criação do banco de dados. Isso listará as linguagens com suporte por padrão no pacote da CodeQL CLI.
• Execute codeql resolve qlpacks para mostrar quais pacotes do CodeQL a CLI pode encontrar. Isso exibirá os nomes de todos os pacotes do CodeQL diretamente disponíveis para os dados da CodeQL CLI. Devem estar inclusos:
• Pacotes de consultas para cada linguagem com suporte, por exemplo, codeql/{language}-queries. Esses pacotes contêm as consultas padrão que serão executadas para cada análise.
• Pacotes de biblioteca para cada linguagem com suporte, por exemplo, codeql/{language}-all. Esses pacotes contêm bibliotecas de consulta, como fluxo de controle e bibliotecas de fluxo de dados, que podem ser úteis para quem escreve consultas.
• Pacotes de exemplo para cada linguagem com suporte, por exemplo, codeql/{language}-examples. Esses pacotes contêm snippets do CodeQL que podem ser úteis para quem escreve consultas.
• Pacotes herdados que garantem que consultas e bibliotecas criadas usando produtos mais antigos sejam compatíveis com a versão do CodeQL.

Como usar duas versões da CodeQL CLI

Se você quiser usar os recursos mais recentes do CodeQL para executar consultas ou testes do CodeQL, mas também quiser preparar bancos de dados compatíveis com uma versão específica da verificação de código do CodeQL no GitHub Enterprise Server, poderá ser necessário instalar duas versões da CLI. A configuração de diretório recomendada depende de quais versões você deseja instalar:

• Se as duas versões forem 2.0.2 (ou mais recentes), você poderá desempacotar os dois arquivos da CLI no mesmo diretório pai.
• Se pelo menos uma das versões for 2.0.1 (ou mais antiga), os arquivos da CLI não poderão estar no mesmo diretório pai, mas poderão compartilhar o mesmo diretório avô. Por exemplo, se você desempacotar a versão 2.0.2 em $HOME/codeql-home/codeql-cli, a versão mais antiga deverá ser descompactada em $HOME/codeql-older-version/old-codeql-cli. Aqui, o avô comum é o diretório $HOME.