Como configurar a CLI do CodeQL

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.

Quem pode usar esse recurso?

O CodeQL está disponível para os seguintes tipos de repositórios:

Neste artigo

Como configurar a CodeQL CLI

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

O CodeQL CLI é compatível com uma variedade de casos de uso e estruturas de diretório. Este artigo explica uma configuração simples que funciona para a maioria dos usuários e ambientes.

Se você planeja usar o CodeQL CLI para pesquisa de segurança ou para testar ou contribuir com consultas, talvez seja necessária uma configuração mais avançada. Para saber mais, confira Configuração avançada da CodeQL CLI.

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.

Observação

O CodeQL CLI não é atualmente compatível com distribuições Linux que não utilizam glibc, como o Alpine Linux (baseado em muslc).

1. Baixar o arquivo tar da CodeQL CLI

O pacote de download do CodeQL CLI é um arquivo tar 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 http://github.com/github/codeql-action/releases. O pacote contém:

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

Use sempre o pacote CodeQL. Fazer isso garante a compatibilidade e proporciona um desempenho muito melhor que um download separado da CodeQL CLI e o check-out das consultas da CodeQL. Se estiver executando apenas a CLI em uma plataforma específica, baixe o arquivo codeql-bundle-PLATFORM.tar.zst apropriado. Como alternativa, você pode baixar codeql-bundle.tar.zst, que contém a CLI para todas as plataformas compatíveis.

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 da CodeQL CLI

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

Opcional: disponibilize o CodeQL CLI no seu sistema de CI

Se você pretende executar análises de CodeQL code scanning em um sistema de CI, certifique-se de que todo o conteúdo do pacote CodeQL CLI esteja disponível para todos os servidores de CI que executarão a análise.

Por exemplo, você pode:

3. Iniciar 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 uma lista completa dos comandos da CodeQL CLI, confira Manual de comandos da CLI do CodeQL.

Observação

Se você adicionar codeql ao seu PATH, ele poderá ser acessado por CodeQL para Visual Studio Code para compilar e executar consultas. Para obter mais informações sobre como configurar VS Code para acessar o CodeQL CLI, consulte Configurar o acesso à CLI do CodeQL.

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 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 da CodeQL CLI extraído, mostrado no exemplo anterior como <extraction root>. 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.

Opcionalmente, você pode baixar alguns pacotes CodeQL contendo consultas pré-compiladas que você gostaria de executar. Para saber mais, confira Como personalizar a análise com pacotes CodeQL.

O comando codeql resolve packs é útil para diagnosticar problemas quando o CodeQL CLI não consegue localizar pacotes de consultas que você espera que estejam disponíveis para análise.

Observação

O comando codeql resolve packs está disponível nas versões 2.19.0 e posteriores do CodeQL CLI. Para versões anteriores da CLI, você deve executar o comando codeql resolve qlpacks, que produz uma saída semelhante, porém menos detalhada.

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.