Instalando CodeQL CLI no seu sistema de CI

Sobre o uso do CodeQL CLI for Varredura de código

Você pode usar CodeQL CLI para executar o Varredura de código no código que você está processando em um sistema de integração contínua (CI) de terceiros. Varredura de código é 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, consulte "Sobre Varredura de código com CodeQL." Para as especificações recomendadas (RAM, núcleos de CPU e disco) para executar a análise CodeQL, consulte "Recursos recomendados de hardware para executar 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, você poderá consultá-lo interativamente, ou executar um conjunto de consultas para gerar um conjunto de resultados no formato SARIF e fazer o upload dos resultados para your GitHub Enterprise Server instance.

Como alternativa, você pode usar GitHub Actions para executar Varredura de código em GitHub Enterprise Server. Para obter informações sobre Varredura de código usando ações, consulte "Configurar Varredura de código para um repositório". Para obter uma visão geral das opções para os sistemas de CI, consulte "Sobre o CodeQL Varredura de código no seu sistema de CI".

Fazer o download do CodeQL CLI

Você deve fazer o download do pacote 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 de https://github.com/github/codeql
• Versões pré-compiladas de todas as consultas incluídas no pacote

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 você estiver executando o CLI apenas em uma plataforma específica, faça o download do arquivo codeql-bundle-PLATFORM.tar.gz apropriado. Como alternativa, você pode fazer o download de 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 Varredura de código. 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 do CodeQL CLI, você poderá executar o executável codeql no servidor:

• Ao executar /<extraction-root>/codeql/codeql, onde <extraction-root> é a pasta onde você extraiu o pacote CodeQL CLI.
• Adicionando /<extraction-root>/codeql ao seu PATH, para que você possa executar o executável como apenas 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 em PATH.
• Caso contrário, /<extraction-root>/codeql/codeql resolve qlpacks.

Extrair da 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 dentro do pacote de CodeQL CLI extraído, mostrado acima como <extraction root>, a menos que você esteja usando uma verificação 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 aplicativo GitHub ou token de acesso pessoal para CodeQL CLI para usar para fazer o upload dos resultados para GitHub Enterprise Server. Você deve usar um token de acesso ou um aplicativo GitHub com a permissão de gravação de 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, você deve criar um novo token com a permissão de gravação de security_events e adicionar isso �  loja secreta do sistema de CI. Para obter informações, consulte "Criar Aplicativos do GitHub" e "Criar um token de acesso pessoal".

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 Varredura de código. Para obter informações detalhadas, consulte "Configurar CodeQL CLI no seu sistema de CI".