Como configurar a CLI do CodeQL

Configurando o CodeQL CLI

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

CodeQL CLI dá suporte a uma variedade de casos de uso e estruturas de diretórios. Este artigo explica uma configuração simples que funciona para a maioria dos usuários e ambientes.

Se você planeja usar a CodeQL CLI para pesquisa de segurança, testar ou contribuir com consultas, talvez seja necessária uma configuração mais avançada. Para obter mais informações, consulte CLI do CodeQL.

Antes de começar

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.

1. Baixar o CodeQL CLI arquivo tar

O pacote de download CodeQL CLI é um arquivo tar que contém ferramentas, scripts e vários arquivos específicos de CodeQL. Se você não tiver uma licença GitHub Enterprise, ao baixar este arquivo, estará concordando com os GitHubCodeQL Termos e Condições.

Você deve baixar o CodeQL bundle em https://github.com/github/codeql-action/releases. O pacote contém:

• CodeQL CLI produto
• 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 CodeQL bundle. Isso garante compatibilidade e oferece um desempenho muito melhor do que fazer separadamente o download do CodeQL CLI e o checkout das consultas CodeQL. Baixe o codeql-bundle-PLATFORM.tar.zst arquivo da plataforma em que você executará a CLI. Substitua PLATFORM pelo Linux x64, linux-arm64 para Linux ARM64, osx64 para macOS ou win64 para linux64 Windows.

O pacote de todas as plataformas (codeql-bundle.tar.zst e codeql-bundle.tar.gz) está fechando e deixará de ser publicado em uma versão futura. Em vez disso, baixe o codeql-bundle-PLATFORM.tar.zst arquivo específico para cada plataforma. Na CodeQL CLI versão 2.27.0 e posterior, a execução da CLI de uma distribuição de todas as plataformas produz um aviso.

Existem também variantes tar.gz do pacote, que são idênticas às variantes tar.zst, exceto por serem compactadas usando o algoritmo gzip menos eficiente. A única razão para baixar as variantes tar.gz é se você estiver usando ferramentas de descompactação mais antigas que não suportam o algoritmo de compactação Zstandard.

2. Extrair o arquivo tar CodeQL CLI

Extraia o CodeQL CLI arquivo tar para um diretório de sua escolha.

Opcional: disponibilize o CodeQL CLI no seu sistema de CI

Se você planeja executar CodeQLcode scanning a análise em um sistema de CI, verifique se o conteúdo completo do CodeQL CLI pacote está disponível para todos os servidores de CI que executarão a análise.

Por exemplo, você pode:

• Copiar o pacote de um local interno central e extraí-lo em cada servidor ou
• Use a API REST para baixar o pacote diretamente de GitHub, garantindo que as melhorias mais recentes nas consultas sejam recebidas. Para obter mais informações, consulte Pontos de extremidade da API REST para lançamentos e ativos de lançamento.

3. Iniciar codeql

Depois de extrair, você pode executar processos CodeQL executando o executável codeql de duas maneiras:

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

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

Testando a CodeQL CLI configuração

Depois de extrair o CodeQL CLI pacote, você pode executar o seguinte comando para verificar se a CLI está configurada corretamente para criar e analisar bancos de dados:

• codeql resolve packs Se /<extraction root>/codeql estiver no PATH.
• /<extraction root>/codeql/codeql resolve packs caso contrário.

Se a operação for bem-sucedida, você deverá ver uma saída semelhante ao trecho abaixo:

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

Os resultados foram truncados por questões de brevidade. Os resultados reais serão mais extensos e detalhados.

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 dentro do pacote extraído CodeQL CLI , mostrado no exemplo anterior como <extraction root>. Se o CodeQL CLI não for capaz de localizar os qlpacks para os idiomas esperados, verifique se você baixou o pacote CodeQL e não uma versão 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á os idiomas compatíveis por padrão em seu CodeQL CLI pacote.

Opcionalmente, você pode baixar alguns pacotes CodeQL contendo consultas pré-compiladas que você gostaria de executar. Para obter mais informações, consulte Como personalizar a análise com pacotes CodeQL.

O comando codeql resolve packs é útil para diagnosticar problemas quando CodeQL CLI não é possível localizar pacotes de consulta que se espera estejam disponíveis para análise.

Próximas Etapas 

Para aprender como preparar seu código para ser analisado pelo CodeQL CLI, consulte Como preparar seu código para a análise do CodeQL.