Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.
Introdução à CodeQL CLI
Observação: este artigo descreve os recursos disponíveis com o pacote CodeQL CLI 2.7.6 incluído na versão inicial de GitHub Enterprise Server 3.4.
Se o administrador do site atualizou a versão do CodeQL CLI para uma mais recente, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes.
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 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 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.
Importante: há várias versões da CLI disponíveis para download, dependendo do caso de uso:
- Se você quiser usar as ferramentas e os recursos mais atualizados do CodeQL, baixe a versão marcada como
latest
. - Se você quiser gerar dados de verificação de código a serem carregados no servidor GitHub Enterprise, baixe a versão compatível com a CodeQL CLI usada no sistema de CI. Para obter mais informações, confira "Como instalar a CodeQL CLI no seu sistema de CI".
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 extrairá os arquivos zip automaticamente. Se você usa o Safari, conclua as seguintes etapas antes de baixar o arquivo zip da CodeQL CLI:
- Abra o Safari.
- No menu do Safari, selecione Preferências… .
- Clique na guia Geral.
- 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" ou "Monterey" 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:
mv ~/Downloads/codeql\*.zip ${extraction-root}
cd ${extraction-root}
/usr/bin/xattr -c codeql\*.zip
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
aoPATH
, para que você possa executar o executável apenas comocodeql
.
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".
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.
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
.
Observação: as bibliotecas e as consultas do CodeQL para análise do Go residiam em um repositório do CodeQL separado para Go. Depois, elas foram movidas para o repositório github/codeql
. Não é mais necessário clonar o github/codeql-go
em uma pasta codeql-home/codeql-go
separada.
Para obter mais informações, confira o Anúncio de realocação.
Importante: 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
.