Instalando CodeQL CLI no seu sistema de CI

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. A Code scanning é um recurso que você usa para analisar o código em um repositório GitHub para encontrar vulnerabilidades de segurança e erros de codificação. Quaisquer problemas identificados pela análise são exibidos em GitHub. Para saber mais, confira "Sobre a varredura de código com CodeQL". Para especificações recomendadas (RAM, núcleos de CPU e disco) para executar análises 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 GitHub.com.

Como alternativa, você pode usar GitHub Actions para executar code scanning em GitHub. Para saber mais sobre code scanning usando ações, confira "Como configurar a verificação de código para um repositório". Para uma visão geral das opções para sistemas CI, confira "Sobre a varredura de código de CodeQL no seu sistema de CI".

Observações:

O CodeQL CLI é gratuito para uso em repositórios públicos. O CodeQL CLI também está disponível em repositórios privados pertencentes às organizações que usam o GitHub Enterprise Cloud e têm uma licença do GitHub Advanced Security. Para obter informações, confira "Termos e condições do GitHub CodeQL" e "CLI do CodeQL".
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

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.

Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

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://github.com/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.

Se você usar o CodeQL CLI para analisar o código escrito em Python, verifique se o sistema de CI tem o Python 3 instalado.

Como testar 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

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. 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, 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 "Creating GitHub Apps" e "Criando 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 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 "Configurando a CLI do CodeQL no seu sistema de CI".