Esta versão do GitHub Enterprise Server foi descontinuada em 2024-07-09. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise Server. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

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

Neste artigo

Como configurar a CodeQL CLI

Observação: este artigo descreve os recursos disponíveis com o pacote CodeQL CLI 2.12.7 incluído na versão inicial de GitHub Enterprise Server 3.9.

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.

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ê planeja usar a CodeQL CLI para pesquisa de segurança ou para testar ou contribuir com consultas, talvez queira uma configuração mais avançada da CodeQL CLI. Para obter mais informações, confira "Configuração avançada da CodeQL CLI".

Se estiver configurando o pacote da CodeQL CLI no seu sistema de CI, você precisará disponibilizar todo o conteúdo do pacote da CodeQL CLI para cada servidor de CI no qual deseja executar análises do CodeQL code scanning. Por exemplo, você pode configurar cada servidor para que copie o pacote de um local interno central, interno e extraí-lo. Como alternativa, você pode usar a API REST para obter o pacote diretamente do GitHub, garantindo que você irá beneficiar-se das últimas melhorias das consultas. Para obter mais informações, confira "Pontos de extremidade da API REST para lançamentos e ativos de lançamento" na documentação da API REST.

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

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 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
Para o GitHub Enterprise Server 3.9, recomenda-se o CodeQL CLI versão 2.12.7.

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.

2. Extrair o arquivo tar da CodeQL CLI

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

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 sobre como configurar o VS Code para acessar a CodeQL CLI, confira "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 qlpacks se /<extraction-root>/codeql estiver no PATH.
  • /<extraction-root>/codeql/codeql resolve qlpacks caso contrário.

Se for bem-sucedido, você verá uma saída semelhante ao trecho abaixo:

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 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, é possível baixar alguns pacotes de CodeQL que contêm consultas pré-compiladas que você gostaria de executar. Para obter mais informações, confira "Como personalizar a análise com pacotes CodeQL".

Próximas etapas

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