Como analisar bancos de dados com a CLI do CodeQL

Sobre a análise de bancos de dados com a CodeQL CLI

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

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:

1. Opcionalmente, baixa todos os pacotes do CodeQL referenciados que não estão disponíveis localmente.
2. Executa um ou mais arquivos de consulta executando-os em um banco de dados do CodeQL.
3. Interpreta os resultados, com base em determinados metadados de consulta, para que os alertas possam ser exibidos no local correto no código-fonte.
4. 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>...

É preciso especificar:

• <database>: o caminho para o banco de dados do CodeQL que você deseja analisar.
• --format: o formato do arquivo de resultados gerado durante a análise. Há suporte para vários formatos diferentes, incluindo CSV, SARIF e formatos de grafo. Para obter mais informações sobre CSV e SARIF, confira Resultados. Para descobrir quais outros formatos de resultados são compatíveis, confira "database analyze".
• --output: o caminho de saída do arquivo de resultados gerado durante a análise.

Você também pode especificar:

• <query-specifiers>...: uma lista separada por espaço de consultas a serem executadas no banco de dados. Esta é uma lista de argumentos, em que cada argumento pode ser:

  • um caminho para um arquivo de consulta
  • um caminho para um diretório que contém arquivos de consulta
  • um caminho para um arquivo de conjunto de consultas
  • o nome de um pacote de consultas do CodeQL
    • com um intervalo de versão opcional
    • com um caminho opcional para uma consulta, um diretório ou um conjunto de consultas dentro do pacote

  Se omitido, o conjunto de consultas padrão da linguagem do banco de dados analisado será usado. Para ver a sintaxe completa dos especificadores de consulta, confira "Como especificar as consultas a serem executadas em um pacote do CodeQL".

• --sarif-category: uma categoria de identificação dos resultados. Usada quando você deseja carregar mais de um conjunto de resultados de um commit. Por exemplo, quando você usa github upload-results para enviar resultados de mais de uma linguagem na API de verificação de código do GitHub. Para obter mais informações sobre esse caso de uso, confira Como configurar a CodeQL CLI no sistema de CI.

• --sarif-add-query-help: (com suporte na versão 2.7.1 em diante) adiciona qualquer ajuda de consulta personalizada escrita em markdown aos arquivos SARIF (v2.1.0 ou posterior) gerados pela análise. A ajuda de consulta armazenada em arquivos .qhelp deve ser convertida em .md antes da execução da análise. Para obter mais informações, confira "Como incluir a ajuda de consulta para consultas personalizadas do CodeQL em arquivos SARIF".

• --download: um sinalizador booliano que permitirá que a CLI baixe todos os pacotes do CodeQL referenciados que não estejam disponíveis localmente. Se esse sinalizador estiver ausente e um pacote do CodeQL referenciado não estiver disponível localmente, o comando falhará.

Para obter detalhes completos de todas as opções que você pode usar ao analisar bancos de dados, confira "database analyze".

Como especificar quais consultas devem ser executadas em um pacote do CodeQL

Os especificadores de consulta são usados por codeql database analyze e outros comandos que operam em um conjunto de consultas. A forma completa de um especificador de consulta é scope/name@range:path, em que:

• scope/name é o nome qualificado de um pacote do CodeQL.

• range é um intervalo semver.

• path é um caminho do sistema de arquivos para uma só consulta, um diretório que contém consultas ou um arquivo de conjunto de consultas.

Quando você especifica scope/name, range e path são opcionais. Se você omitir um range, a versão mais recente do pacote especificado será usada. Se você omitir um path, o conjunto de consultas padrão do pacote especificado será usado.

O pode path ser um dos seguintes: um arquivo de consulta .ql, um diretório que contém uma ou mais consultas ou um arquivo de conjunto de consultas .qls. Se você omitir um nome de pacote, precisará fornecer um path, que será interpretado em relação ao diretório de trabalho do processo atual. Não há suporte para padrões glob.

Se você especificar scope/name e path, o path não poderá ser absoluto. Ele é considerado relativo à raiz do pacote do CodeQL.

Especificadores de consulta de exemplo

• codeql/python-queries – Todas as consultas no pacote de consultas padrão da versão mais recente do pacote codeql/python-queries.

• codeql/python-queries@1.2.3 – Todas as consultas no pacote de consultas padrão da versão 1.2.3 do pacote codeql/python-queries.

• codeql/python-queries@~1.2.3 – Todas as consultas no conjunto de consultas padrão da versão mais recente do pacote codeql/python-queries que são >= 1.2.3 e < 1.3.0.

• codeql/python-queries:Functions – Todas as consultas no diretório Functions na versão mais recente do pacote codeql/python-queries.

• codeql/python-queries@1.2.3:Functions – Todas as consultas no diretório Functions da versão 1.2.3 do pacote codeql/python-queries.

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls – Todas as consultas no diretório codeql-suites/python-code-scanning.qls da versão 1.2.3 do pacote codeql/python-queries.

• suites/my-suite.qls – Todas as consultas no arquivo suites/my-suite.qls relativas ao diretório de trabalho atual.

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 um pacote de consultas do CodeQL

Para executar um pacote de consultas do CodeQL existente do Container registry do GitHub, você pode especificar um ou mais nomes de pacote:

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Esse comando executa o conjunto de consultas padrão de dois pacotes de consultas do CodeQL: a versão 1.0.0 do microsoft/coding-standards e a versão mais recente do github/security-queries no banco de dados especificado. Para obter mais informações sobre os pacotes padrão, confira "Como publicar e usar pacotes CodeQL".

O sinalizador --download é opcional. O uso dele garantirá que o pacote de consultas seja baixado se ainda não estiver disponível localmente.

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 as consultas a serem usadas com a CodeQL CLI, confira "Como usar consultas personalizadas com a CodeQL CLI".

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.

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 um subconjunto de consultas em um pacote do CodeQL

Se você estiver usando a CodeQL CLI v2.8.1 ou posterior, poderá incluir um caminho no final de uma especificação de pacote para executar um subconjunto de consultas dentro do pacote. Isso se aplica a qualquer comando que localiza ou executa consultas em um pacote.

A maneira completa de especificar um conjunto de consultas tem o formato scope/name@range:path, em que:

• scope/name é o nome qualificado de um pacote do CodeQL.

• range é um intervalo semver.

• path é um caminho do sistema de arquivos para uma só consulta, um diretório que contém consultas ou um arquivo de conjunto de consultas.

Quando você especifica scope/name, range e path são opcionais. Se você omitir um range, a versão mais recente do pacote especificado será usada. Se você omitir um path, o conjunto de consultas padrão do pacote especificado será usado.

O path pode ser: um arquivo de consulta \*.ql, um diretório que contém uma ou mais consultas ou um arquivo de conjunto de consultas .qls. Se você omitir um nome de pacote, precisará fornecer um path, que será interpretado em relação ao diretório de trabalho do processo atual.

Se você especificar as opções scope/name e path, a path não poderá ser absoluta. Ele é considerado relativo à raiz do pacote do CodeQL.

Para analisar um banco de dados usando todas as consultas na pasta experimental/Security dentro do pacote codeql/cpp-queries no CodeQL, você pode usar:

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

Para executar a consulta RedundantNullCheckParam.ql no pacote codeql/cpp-queries do CodeQL, use:

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Para analisar o banco de dados usando o conjunto de consultas cpp-security-and-quality.qls de uma versão do pacote codeql/cpp-queries do CodeQL >= 0.0.3 e < 0.1.0 (a versão compatível mais alta será escolhida), você pode usar:

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Se você precisar fazer referência a um arquivo de consulta, a um diretório ou a um pacote cujo caminho contenha um literal @ ou :, poderá prefixar a especificação de consulta com path: da seguinte forma:

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Para obter mais informações sobre pacotes do CodeQL, confira Sobre os pacotes do 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 obter mais informações, confira Como configurar a CodeQL CLI no 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 obter mais informações, confira Saída SARIF.

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.

Leitura adicional

• "Como analisar os projetos no CodeQL para VS Code"