Configuração avançada da CodeQL CLI

Sobre a configuração avançada da CodeQL CLI

Se você planeja usar o CodeQL para mais do que apenas varredura de código, talvez prefira uma configuração avançada da CodeQL CLI.

• Se quiser contribuir com consultas compartilhadas de código aberto do CodeQL, talvez prefira trabalhar diretamente com o código-fonte do CodeQL.
• Se quiser usar os recursos mais recentes do CodeQL para gerar alertas de varredura de código para uma base de código, mas também quiser analisar outra base de código que seja compatível apenas com uma versão específica da CodeQL CLI, uma ideia é instalar várias versões da CodeQL CLI.
• Se você estiver pesquisando ou desenvolvendo consultas, uma sugestão é baixar bancos de dados interessantes ou exclusivos do GitHub.com.

Para saber mais sobre a configuração mais simples da CodeQL CLI, confira Como configurar a CLI do CodeQL.

Como conferir o código-fonte do CodeQL diretamente

Alguns usuários preferem usar fontes de consulta do CodeQL diretamente para trabalhar com consultas compartilhadas de código aberto ou contribuir para elas. Para isso, são recomendadas as etapas a seguir.

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

Use sempre o pacote CodeQL. Fazer isso garante a compatibilidade e proporciona um desempenho muito melhor que um download separado da CodeQL CLI e o check-out das consultas da CodeQL. Se estiver executando apenas a CLI em uma plataforma específica, baixe o arquivo codeql-bundle-PLATFORM.tar.zst apropriado. Como alternativa, você pode baixar codeql-bundle.tar.zst, que contém a CLI para todas as plataformas compatíveis.

Existem também variantes tar.gz do pacote, que são idênticas às variantes tar.zst, exceto por serem compactadas usando o algoritmo gzip menos eficiente. A única razão para baixar as variantes tar.gz é se você estiver usando ferramentas de descompactação mais antigas que não suportam o algoritmo de compactação Zstandard.

2. Criar um diretório do CodeQL

Crie um diretório no qual você pode colocar a CLI e todas as consultas e bibliotecas que deseja usar. Por exemplo, $HOME/codeql-home.

As operações de pesquisa internas da CLI procuram automaticamente em todos os diretórios irmãos os arquivos usados na criação e na análise do banco de dados. Com esses componentes no próprio diretório, a CLI não pesquisa diretórios irmãos não relacionados, garantindo que todos os arquivos estejam disponíveis sem especificar outras opções na linha de comando.

3. Obter uma cópia local das consultas do CodeQL

O repositório do CodeQL contém as consultas e as bibliotecas necessárias para que o CodeQL analise todas as linguagens com suporte. Clone uma cópia desse repositório em codeql-home.

Por padrão, a raiz do repositório clonado será chamada de codeql. Renomeie essa pasta codeql-repo para evitar conflitos com a CodeQL CLI que você extrairá na etapa 1. Se você usar o Git na linha de comando, poderá clonar e renomear o repositório em uma só etapa executando git clone git@github.com:github/codeql.git codeql-repo na pasta codeql-home.

Nesse repositório, as consultas e as bibliotecas são organizadas em pacotes do CodeQL. Junto com as consultas, os pacotes do CodeQL contêm metadados importantes que informam à CodeQL CLI como processar os arquivos de consulta. Para saber mais, confira Como criar e trabalhar com pacotes do CodeQL.

4. Extrair o arquivo tar da CodeQL CLI

Extraia o arquivo tar para o diretório criado na etapa 2.

Por exemplo, se o caminho para a cópia do repositório do CodeQL for $HOME/codeql-home/codeql-repo, extraia a CLI para $HOME/codeql-home/.

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

6. Verificar a configuração da CodeQL CLI

A CodeQL CLI tem subcomandos que você pode executar para verificar se está tudo configurado corretamente para a criação e análise de bancos de dados:

• Execute codeql resolve languages para mostrar quais linguagens estão disponíveis para a criação do banco de dados. Isso listará as linguagens com suporte por padrão no pacote da CodeQL CLI.
• Execute codeql resolve qlpacks para mostrar quais pacotes do CodeQL a CLI pode encontrar. Isso exibirá os nomes de todos os pacotes do CodeQL diretamente disponíveis para os dados da CodeQL CLI. Devem estar inclusos:
• Pacotes de consultas para cada linguagem com suporte, por exemplo, codeql/{language}-queries. Esses pacotes contêm as consultas padrão que serão executadas para cada análise.
• Pacotes de biblioteca para cada linguagem com suporte, por exemplo, codeql/{language}-all. Esses pacotes contêm bibliotecas de consulta, como fluxo de controle e bibliotecas de fluxo de dados, que podem ser úteis para quem escreve consultas.
• Pacotes de exemplo para cada linguagem com suporte, por exemplo, codeql/{language}-examples. Esses pacotes contêm snippets do CodeQL que podem ser úteis para quem escreve consultas.
• Pacotes herdados que garantem que consultas e bibliotecas criadas usando produtos mais antigos sejam compatíveis com a versão do CodeQL.

Como usar duas versões da CodeQL CLI

Se você quiser usar os recursos mais recentes do CodeQL para executar consultas ou testes do CodeQL, mas também quiser preparar bancos de dados compatíveis com uma versão específica da verificação de código do CodeQL no GitHub Enterprise Server, poderá ser necessário instalar duas versões da CLI. Você pode baixar as versões da CodeQL CLI desejadas e descompactar os dois arquivos da CLI no mesmo diretório pai.

Como baixar bancos de dados do GitHub.com

O GitHub armazena os bancos de dados CodeQL para mais de 200 mil repositórios no GitHub.com, que você pode baixar usando a API REST. A lista de repositórios está sempre crescendo e evoluindo para garantir que ele inclua as bases de código mais interessantes para pesquisa de segurança.

Você também pode analisar bancos de dados do GitHub.com usando a extensão do CodeQL para VS Code. Para saber mais, confira Como executar consultas do CodeQL.

Você pode verificar se um repositório tem bancos de dados do CodeQL disponíveis para download usando o ponto de extremidade /repos/<owner>/<repo>/code-scanning/codeql/databases. Por exemplo, para verificar os bancos de dados do CodeQL usando o GitHub CLI, você executaria:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

Esse comando retorna informações sobre todos os bancos de dados do CodeQL que estão disponíveis para um repositório, incluindo a linguagem que o banco de dados representa e quando ele foi atualizado pela última vez. Se nenhum banco de dados do CodeQL estiver disponível, a resposta estará vazia.

Ao confirmar que existe um banco de dados do CodeQL para a linguagem do seu interesse, você poderá baixá-lo usando o seguinte comando:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Para obter mais informações, confira a documentação Obter um ponto de extremidade do banco de dados do CodeQL.

Antes de executar uma análise com os dados da CodeQL CLI, você precisa descompactar os bancos de dados.