Como configurar a CLI do CodeQL

Neste artigo

Para começar a usar a CodeQL CLI, você precisa baixá-la e configurá-la para que ela possa acessar as ferramentas e as bibliotecas necessárias para criar e analisar bancos de dados.

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

Como configurar a 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.

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 o Linux, o Windows ou o macOS versão 10.14 ("Mojave") ou anterior, basta seguir as etapas abaixo. Para o 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.

Observação: no momento, a CodeQL CLI não é compatível com distribuições Linux que não são glibc, como o Alpine Linux (baseado em muslc).

Para obter informações sobre como instalar a CodeQL CLI em um sistema de CI para criar resultados a serem exibidos no GitHub como alertas da verificação de código, confira "Instalando CodeQL CLI no seu 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.

Baixe o pacote do CodeQL em https://github.com/github/codeql-action/releases. O pacote contém:

  • produto de CodeQL CLI
  • Uma versão compatível das consultas e bibliotecas do https://github.com/github/codeql
  • Versões pré-compiladas de todas as consultas incluídas no pacote

Você sempre deve usar o pacote de CodeQL, uma vez que ele garante compatibilidade e também fornece um desempenho muito melhor do que um download separado de CodeQL CLI e checkout das consultas de CodeQL. Se estiver executando apenas a CLI em uma plataforma específica, baixe o arquivo codeql-bundle-PLATFORM.tar.gz apropriado. Como alternativa, você pode baixar codeql-bundle.tar.gz, que contém a CLI para todas as plataformas compatíveis.

Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

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

Do macOS versão 10.15 ("Catalina") em diante, verifique se o navegador da Web não extrai os 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… ou Configurações… (versão 13 "Ventura" em diante).
  3. Clique na guia Geral.
  4. Verifique se a caixa de seleção rotulada Abrir arquivos "seguros" após o download está desmarcada.

2. Extrair o arquivo zip

Para os 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", "Monterey" ou "Ventura" devem executar os seguintes comandos no Terminal, sendo 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 ver a lista completa dos comandos da CodeQL CLI, confira "Manual de comandos da CLI do CodeQL".

Observação: se você adicionar codeql a PATH, ele poderá ser acessado pelo CodeQL para Visual Studio Code a fim de compilar e executar consultas. Para obter mais informações de como configurar o VS Code para acessar a CodeQL CLI, confira "Como configurar o CodeQL no Visual Studio Code".

Como testar a configuração de CodeQL CLI

Depois de extrair o pacote da CodeQL CLI, execute o comando a seguir para verificar se a CLI está configurada corretamente para criar e analisar bancos de dados:

  • codeql resolve qlpacks se /<extraction-root>/codeql estiver no PATH.
  • /<extraction-root>/codeql/codeql resolve qlpacks caso contrário.

Extração de uma saída bem-sucedida:

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

Você deve verificar se a saída contém as linguagens esperadas e também se o local do diretório de arquivos qlpack está correto. O local deve estar no pacote extraído da CodeQL CLI, mostrado no exemplo anterior como <extraction root>, a menos que você esteja usando um check-out de github/codeql. Se o CodeQL CLI não conseguir localizar os qlpacks para as linguagens esperadas, certifique-se de que você faz o download do pacote CodeQL e não uma cópia independente do CodeQL CLI.

Execute também codeql resolve languages para mostrar as linguagens 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) Baixe alguns "Como personalizar a análise com pacotes CodeQL" contendo consultas pré-compiladas que você 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.

Gerando um token para autenticação com GitHub

Se, em última análise, você desejar carregar os resultados no GitHub para exibi-los como alertas da verificação de código, gere um personal access token com a permissão de gravação security_events. Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal".

Se você instalou a CodeQL CLI em um sistema de CI de terceiros para criar resultados a serem exibidos no GitHub como alertas da verificação de código, use um GitHub App ou um personal access token para carregar os resultados no GitHub. Para obter mais informações, confira "Instalando CodeQL CLI no seu sistema de CI".

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 1. 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 "Como personalizar a análise com pacotes CodeQL".

Observação: há diferentes versões das consultas do CodeQL disponíveis para diferentes usuários. Confira a versão correta para seu caso de uso:

  • Para as consultas que devem ser usadas com a versão mais recente da CodeQL CLI, confira o branch marcado como codeql-cli/latest. Você deve usar esse branch para bancos de dados criados usando a CodeQL CLI, buscados na verificação de código no GitHub ou baixados recentemente do GitHub.com.
  • Para obter as consultas mais atualizadas do CodeQL, confira o branch main. Esse branch representa a versão mais recente da análise do CodeQL.

4. Extrair o arquivo zip

Para os usuários do Linux, do Windows e do 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.