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

A CodeQL CLI é uma ferramenta de linha de comando autônoma 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 obter informações sobre como habilitar a verificação de código do CodeQL usando o GitHub Actions, confira "Como definir a configuração padrão da verificação de código" e "Como definir a configuração avançada da verificação de código". 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".

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.

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.

Primeiro, você precisará extrair o pacote CodeQL CLI. Em seguida, você pode executar o codeql executável no servidor de uma das duas 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.

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.

Um exemplo de uma saída bem-sucedida é semelhante ao seguinte:

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 "Criar aplicativos do GitHub" e "Gerenciar seus tokens 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".