Sobre a análise de bancos de dados com a CodeQL CLI
Observação: este artigo descreve os recursos disponíveis com o pacote CodeQL CLI 2.12.7 incluído na versão inicial de GitHub Enterprise Server 3.6.
Se o administrador do site atualizou a versão do CodeQL CLI para uma mais recente, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes.
Para analisar uma base de código, execute consultas em um banco de dados do CodeQL extraído do código.
As análises do CodeQL produzem resultados interpretados que podem ser exibidos como alertas ou caminhos no código-fonte.
Para obter informações de como escrever consultas a serem executadas com database analyze, confira "Como usar consultas personalizadas com a CodeQL CLI".
Outros comandos de execução de consulta
As consultas executadas com database analyze têm requisitos estritos de metadados. Você também pode executar consultas usando os seguintes subcomandos no nível do plumbing:
-
database run-queries, que gera resultados não interpretados em um formato binário intermediário chamado BQRS
-
query run, que produzirá arquivos BQRS ou imprimirá tabelas de resultados diretamente na linha de comando. Pode ser útil ver os resultados diretamente na linha de comando no caso de desenvolvimento de consultas iterativas usando a CLI.
As consultas executadas com esses comandos não têm os mesmos requisitos de metadados.
No entanto, para salvar dados legíveis por humanos, você precisa processar cada arquivo de resultados BQRS usando o subcomando de conexão de bqrs decode. Portanto, para a maioria dos casos de uso, é mais fácil usar database analyze para gerar diretamente resultados interpretados.
Pré-requisitos
Antes de iniciar uma análise, você precisa:
- Configurar a CodeQL CLI para executar comandos localmente.
- Criar um banco de dados do CodeQL para o código-fonte que você deseja analisar.
A maneira mais simples de executar codeql database analyze é usando pacotes do CodeQL. Você também pode executar o comando usando consultas de um check-out local do repositório do CodeQL, ideal para personalizar as consultas principais do CodeQL.
Em execuçãocodeql database analyze
Quando executado, o database analyze:
- Opcionalmente, baixa todos os pacotes do CodeQL referenciados que não estão disponíveis localmente.
- Executa um ou mais arquivos de consulta executando-os em um banco de dados do CodeQL.
- Interpreta os resultados, com base em determinados metadados de consulta, para que os alertas possam ser exibidos no local correto no código-fonte.
- Relata os resultados de consultas de diagnóstico e de resumo à saída padrão.
Você pode analisar um banco de dados executando o seguinte comando:
codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...
Observação: se você analisar mais de um banco de dados do CodeQL para um só commit, precisará especificar uma categoria SARIF para cada conjunto de resultados gerado por este comando. Ao fazer o upload dos resultados para GitHub Enterprise Server, code scanning usa essa categoria para armazenar os resultados para cada linguagem separadamente. Se você se esquecer de fazer isso, cada upload substituirá os resultados anteriores.
codeql database analyze <database> --format=<format> \
--sarif-category=<language-specifier> --output=<output> \
<queries>
Você precisa especificar <database>, --format e --output. Você pode especificar opções adicionais dependendo da análise que deseja fazer.
| Opção | Obrigatório | Uso |
|---|---|---|
<database> | Especifique o caminho para o diretório que contém o banco de dados de CodeQL a ser analisado. | |
<packs,queries> | Especifique pacotes ou consultas de CodeQL para executar. Para executar as consultas padrão usadas para code scanning, omita este parâmetro. Para ver os outros conjuntos de consultas incluídos no pacote da CodeQL CLI, confira /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites. Para obter informações sobre como criar seu pacote de consultas, confira Como criar conjuntos de consultas do CodeQL na documentação da CodeQL CLI. | |
--format | Especifique o formato para o arquivo de resultados gerado durante a análise. Há suporte para vários formatos diferentes, incluindo CSV, SARIF e formatos de grafo. Para upload no GitHub, isso deve ser: sarifv2.1.0. Para obter mais informações, confira "Suporte SARIF para a varredura de código". | |
--output | Especifique em que local salvar o arquivo de resultados SARIF. | |
--sarif-category | Opcional para análise de banco de dados individual. Necessário para definir a linguagem ao analisar vários bancos de dados para um só commit em um repositório. Especifique uma categoria a ser incluída no arquivo de resultados SARIF para esta análise. Uma categoria é usada para distinguir várias análises para a mesma ferramenta e commit, mas executadas em diferentes linguagens ou partes diferentes do código. | |
--sarif-add-query-help | Use se você quer incluir qualquer ajuda de consulta renderizada por markdown disponível para as consultas personalizadas usadas em sua análise. Qualquer ajuda de consulta para consultas personalizadas incluídas na saída SARIF será exibida na interface do usuário de verificação de código se a consulta relevante gerar um alerta. Para obter mais informações, confira "Como incluir a ajuda de consulta em consultas personalizadas do CodeQL em arquivos SARIF". | |
--threads | Use se você quiser usar mais de um thread para executar consultas. O valor padrão é 1. Você pode especificar mais threads para acelerar a execução da consulta. Para definir o número de threads para o número de processadores lógicos, especifique 0. | |
--verbose | Use o para obter informações mais detalhadas sobre o processo de análise e os dados de diagnóstico do processo de criação do banco de dados. |
Atualizando bancos de dados
Para bancos de dados criados pela CodeQL CLI v2.3.3 ou anteriores, você precisará atualizar explicitamente o banco de dados antes de executar uma análise com uma versão mais recente da CodeQL CLI. Se essa etapa for necessária, você verá uma mensagem informando que o banco de dados precisa ser atualizado quando executar o database analyze.
Para bancos de dados criados pela CodeQL CLI v2.3.4 ou posterior, a CLI executará implicitamente todas as atualizações necessárias. Não é necessário executar explicitamente o comando de atualização.
Para obter detalhes completos de todas as opções que você pode usar ao analisar bancos de dados, confira "database analyze".
Exemplo básico de análise de um banco de dados CodeQL
Este exemplo analisa um banco de dados do CodeQL armazenado em /codeql-dbs/example-repo e salva os resultados como um arquivo SARIF: /temp/example-repo-js.sarif. Ele usa --sarif-category para incluir informações extras no arquivo SARIF que identifica os resultados como JavaScript. Isso é essencial quando você tem mais de um banco de dados CodeQL para analisar um único commit em um repositório.
$ codeql database analyze /codeql-dbs/example-repo \
javascript-code-scanning.qls --sarif-category=javascript \
--format=sarifv2.1.0 --output=/temp/example-repo-js.sarif
> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.
Exemplos de análises de banco de dados em execução
Os exemplos a seguir mostram como executar database analyze usando pacotes do CodeQL e como usar um check-out local do repositório do CodeQL. Esses exemplos pressupõem que os bancos de dados do CodeQL foram criados em um diretório que é irmão das cópias locais do repositório do CodeQL.
Como executar uma só consulta
Para executar uma só consulta em um banco de dados do CodeQL em uma base de código JavaScript, você pode usar o seguinte comando do diretório que contém o banco de dados:
codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
Esse comando executa uma consulta simples que localiza possíveis bugs relacionados a variáveis, importações, funções ou classes não utilizados. E uma das consultas JavaScript incluídas no repositório do CodeQL. Você pode executar mais de uma consulta especificando uma lista e caminhos semelhantes separados por espaço.
A análise gera um arquivo CSV (js-results.csv) em um novo diretório (js-analysis).
Como alternativa, se você fizer check-out no repositório CodeQL, poderá executar as mesmas consultas especificando o caminho da consulta diretamente:
codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
Você também pode executar as próprias consultas personalizadas com o comando database analyze.
Para obter mais informações sobre como preparar suas consultas para uso com a CodeQL CLI, confira "Como usar consultas personalizadas com a CLI do CodeQL".
Como executar todas as consultas em um diretório
Você pode executar todas as consultas localizadas em um diretório fornecendo o caminho do diretório, em vez de listar todos os arquivos de consulta individuais. Os caminhos são pesquisados recursivamente, portanto, todas as consultas contidas em subpastas também serão executadas.
Importante
Você deve evitar especificar a raiz de um pacote de consultas principal do CodeQL ao executar database analyze, pois ele pode conter algumas consultas especiais que não foram projetadas para serem usadas com o comando. Nesse caso, execute o pacote de consultas para incluir as consultas padrão do pacote na análise ou execute um dos conjuntos de consultas de verificação de código.
Por exemplo, para executar todas as consultas Python contidas no diretório Functions no pacote de consultas codeql/python-queries, você executaria:
codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download
Como alternativa, se você fizer o check-out do repositório do CodeQL, poderá executar as mesmas consultas especificando o caminho diretamente para o diretório:
codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
Quando a análise for concluída, um arquivo de resultados SARIF será gerado. A especificação de --format=sarif-latest garante que os resultados sejam formatados de acordo com a especificação SARIF mais recente compatível com o CodeQL.
Como executar conjuntos de consultas
Para executar um conjunto de consultas em um banco de dados do CodeQL em uma base de código C/C++, você pode usar o seguinte comando do diretório contendo o banco de dados:
codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download
Esse comando baixa o pacote de consultas codeql/cpp-queries do CodeQL, executa a análise e gera um arquivo no formato SARIF versão 2.1.0 compatível com todas as versões do GitHub. Esse arquivo pode ser carregado em GitHub executando codeql github upload-results ou a API de verificação de código.
Para saber mais, confira "Configurando a CLI do CodeQL no seu sistema de CI" ou "Verificação de código".
Os conjuntos de consultas do CodeQL são arquivos .qls que usam diretivas para selecionar as consultas a serem executadas com base em determinadas propriedades de metadados. Os pacotes padrão do CodeQL têm metadados que especificam o local dos conjuntos de consultas usados pela verificação de código, para que a CodeQL CLI saibs onde encontrar esses arquivos de pacote automaticamente e você não precisa especificar o caminho completo na linha de comando.
Para obter mais informações, confira "Como criar conjuntos de consultas do CodeQL".
Para obter informações sobre como criar conjuntos de consultas personalizados, confira "Como criar conjuntos de consultas do CodeQL".
Informações de diagnóstico e resumo
Quando você cria um banco de dados do CodeQL, o extrator armazena dados de diagnóstico no banco de dados. Os conjuntos de consultas de verificação de código incluem consultas adicionais para relatar esses dados de diagnóstico e calcular métricas de resumo. Quando o comando database analyze é concluído, a CLI gera o arquivo de resultados e relata todos os dados de diagnóstico e de resumo para a saída padrão. Se você quiser gerar a saída SARIF, os dados adicionais também serão incluídos no arquivo SARIF.
Se a análise encontrou menos resultados para consultas padrão do que você esperava, examine os resultados das consultas de diagnóstico e de resumo para verificar se o banco de dados do CodeQL poderá ser uma boa representação da base de código a ser analisada.
Como integrar um pacote do CodeQL a um fluxo de trabalho de verificação de código no GitHub
Você pode usar os pacotes de consultas do CodeQL na configuração de verificação de código. Isso permite que você selecione pacotes de consultas publicados por várias fontes e use-os para analisar o código. Para obter mais informações, confira "Como usar pacotes de consultas do CodeQL na ação do CodeQL ou "Como baixar e usar pacotes de consultas do CodeQL no sistema de CI".
Como incluir a ajuda de consulta para consultas personalizadas do CodeQL em arquivos SARIF
Se você usar a CodeQL CLI para executar análises de verificação de código em sistemas de CI/CD de terceiros, poderá incluir a ajuda de consulta nas consultas personalizadas nos arquivos SARIF gerados durante uma análise. Depois de carregar o arquivo SARIF no GitHub, a ajuda de consulta será mostrada na interface do usuário de verificação de código para os alertas gerados pelas consultas personalizadas.
Da CodeQL CLI v2.7.1 em diante, você pode incluir a ajuda de consulta renderizada por markdown em arquivos SARIF fornecendo a opção --sarif-add-query-help ao executar codeql database analyze.
Para saber mais, confira Configurando a CLI do CodeQL no seu sistema de CI.
Você pode escrever uma ajuda de consulta para consultas personalizadas diretamente em um arquivo markdown e salvá-la junto com a consulta correspondente. Como alternativa, para consistência com as consultas padrão do CodeQL, você pode escrever a ajuda de consulta no formato .qhelp. A ajuda de consulta escrita em arquivos .qhelp não pode ser incluída em arquivos SARIF e não pode ser processada pela verificação de código, portanto, precisa ser convertida em markdown antes da execução da análise. Para obter mais informações, confira "Arquivos de ajuda de consulta" e "Como testar arquivos de ajuda de consulta".
Resultados
Você pode salvar os resultados da análise em vários formatos diferentes, incluindo SARIF e CSV.
O SARIF foi projetado para representar a saída de uma ampla gama de ferramentas de análise estática. Para saber mais, confira Saída SARIF da CLI do CodeQL.
Se você optar por gerar resultados no formato CSV, cada linha no arquivo de saída corresponderá a um alerta. Cada linha é uma lista separada por vírgulas com as informações a seguir.
| Propriedade | Descrição | Exemplo |
|---|---|---|
| Nome | Nome da consulta que identificou o resultado. | Inefficient regular expression |
| Descrição | Descrição da consulta. | A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks. |
| Severidade | Severidade da consulta. | error |
| Mensagem | Mensagem de alerta. | This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'. |
| Caminho | Caminho do arquivo que contém o alerta. | /vendor/codemirror/markdown.js |
| Linha inicial | Linha do arquivo em que o código que disparou o alerta começa. | 617 |
| Coluna inicial | Coluna da linha inicial que marca o início do código de alerta. Não incluída quando igual a 1. | 32 |
| Linha final | Linha do arquivo em que o código que disparou o alerta termina. Não incluída quando tem o mesmo valor que a linha inicial. | 64 |
| Coluna final | Quando disponível, a coluna da linha final que marca o final do código de alerta. Caso contrário, a linha final será repetida. | 617 |
Os arquivos de resultados podem ser integrados à sua infraestrutura de revisão ou depuração de código. Por exemplo, a saída do arquivo SARIF pode ser usada para realçar alertas no local correto no código-fonte usando um plug-in de visualizador do SARIF para seu IDE.