Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Instalando CodeQL CLI no seu sistema de CI

Você pode instalar o CodeQL CLI e usá-lo para executar CodeQL code scanning em um sistema de integração contínua de terceiros.

A Code scanning está disponível para os repositórios pertencentes à organização no GitHub Enterprise Server. Esse recurso exige uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Observação: o administrador do site precisa habilitar o code scanning para o your GitHub Enterprise Server instance a fim de que seja possível usar esse recurso. Para obter mais informações, confira "Como configurar a code scanning para seu dispositivo".

Sobre o uso do CodeQL CLI for code scanning

Você pode usar a CodeQL CLI para executar a code scanning no código que está processando em um sistema de CI (integração contínua) de terceiros. Code scanning é um recurso que você usa para analisar o código em um repositório de GitHub para localizar vulnerabilidades de segurança e erros de codificação. Quaisquer problemas identificados pela análise são exibidos em GitHub Enterprise Server. Para obter informações, confira "Sobre a code scanning com o CodeQL". Para obter especificações recomendadas (RAM, núcleos de CPU e disco) para executar a análise do CodeQL, confira "Recursos de hardware recomendados para executar o CodeQL".

O CodeQL CLI é um produto inependente que você pode usar para analisar o código. Seu principal propósito é gerar uma representação do banco de dados de uma base de código, um banco de dados de CodeQL. Assim que o banco de dados estiver pronto, será possível consultá-lo interativamente ou executar um conjunto de consultas a fim de gerar um conjunto de resultados no formato SARIF e enviá-los ao your GitHub Enterprise Server instance.

Como alternativa, você pode usar GitHub Actions para executar code scanning em GitHub Enterprise Server. Para obter informações sobre a code scanning usando ações, confira "Como configurar a code scanning para um repositório". Para ter uma visão geral das opções para sistemas de CI, confira "Sobre a code scanning do CodeQL no seu sistema de CI".

Observações:

  • O CodeQL CLI está disponível para clientes com uma licença de Advanced Security.

  • Atualmente, o CodeQL CLI não é compatível com distribuições Linux não glibc, como o Alpine Linux (baseado em musl).

Como baixar a CodeQL CLI

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.7, recomenda-se o CodeQL CLI versão 2.10.5.

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.

Configurando o CodeQL CLI no seu sistema de CI

Você precisa disponibilizar todo o conteúdo do pacote CodeQL CLI para cada servidor de CI no qual você deseja executar a análise de CodeQL de 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. Atualizações no CodeQL CLI são lançadas a cada 2 a 3 semanas. Por exemplo:

$ wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ./codeql-bundle-linux64.tar.gz

Depois de extrair o pacote da CodeQL CLI, execute o executável codeql no servidor:

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

Testando a configuração de CodeQL CLI

Depois de extrair o pacote de CodeQL CLI, você pode executar o comando a seguir para verificar se a CLI está configurada corretamente para criar e analisar bases 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 da CodeQL CLI, mostrado acima 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.

Gerando um token para autenticação com GitHub Enterprise Server

Cada servidor de CI precisa de um GitHub App ou de um personal access token para uso pelo CodeQL CLI ao enviar resultados para o GitHub Enterprise Server. Você precisa usar um token de acesso ou um GitHub App com a permissão de gravação security_events. Se os servidores de CI já usam um token com este escopo para repositórios de checkout de GitHub Enterprise Server, potencialmente você poderia permitir que CodeQL CLI usasse o mesmo token. Caso contrário, crie um token com a permissão de gravação security_events e adicione-o ao repositório de segredos do sistema de CI. Para obter informações, confira "Como criar GitHub Apps" e "Como criar um personal access token".

Próximas etapas

Agora você está pronto para configurar o sistema de CI para executar a análise de CodeQL, gerar resultados e enviá-los para GitHub Enterprise Server onde os resultados serão correspondidos com um branch ou pull request e exibidos como alertas de code scanning. Para obter informações detalhadas, confira "Como configurar a CodeQL CLI no seu sistema de CI".