Skip to main content

Como analisar o código com as consultas CodeQL

Você pode executar consultas em um banco de dados do CodeQL extraído de uma base de código.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

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 que podem ser carregados no GitHub Enterprise Cloud para gerar alertas de varredura de código.

Pré-requisitos

Antes de iniciar uma análise, você precisa:

A maneira mais simples de executar codeql database analyze é usar as consultas padrão incluídas no pacote da CodeQL CLI.

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

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 Cloud, 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> \
    <packs,queries>

Você precisa especificar <database>, --format e --output. Você pode especificar opções adicionais dependendo da análise que deseja fazer.

OpçãoObrigatórioUso
<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.
--formatEspecifique 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: sarif-latest. Para obter mais informações, confira "Suporte SARIF para a varredura de código".
--outputEspecifique o local onde você deseja salvar o arquivo de resultados SARIF, incluindo o nome do arquivo desejado com a extensão .sarif.
--sarif-categoryOpcional 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-baseline-file-infoRecomendado. Use-o para enviar informações de cobertura de arquivo para a página de status da ferramenta. Para obter mais informações, confira "Sobre a página de status da ferramenta para a verificação de código".
--sarif-add-query-helpUse 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 saber mais, confira "Como usar consultas personalizadas com a CLI do CodeQL".
<packs>Use se quiser incluir pacotes de consulta CodeQL em sua análise. Para obter mais informações, confira "Como baixar e usar pacotes do CodeQL".
--downloadUse se alguns de seus pacotes de consulta CodeQL ainda não estiverem em disco e precisarem ser baixados antes de executar consultas.
--threadsUse 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.
--verboseUse 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.
--threat-model(Beta) Use para adicionar modelos de risco para configurar fontes adicionais em sua análise de CodeQL. Durante a beta, só há suporte para os modelos de risco em análises Java. Para obter mais informações, confira "database analyze".

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-typescript \
    --format=sarif-latest --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.

Adicionando informações de cobertura de arquivo aos resultados para monitoramento

Opcionalmente, você pode enviar informações de cobertura de arquivo para o GitHub Enterprise Cloud para exibição na página de status da ferramenta da code scanning. Para obter mais informações sobre as informações de cobertura de arquivo, confira "Sobre a página de status da ferramenta para a verificação de código".

Para incluir informações de cobertura de arquivo com os resultados do code scanning, adicione o sinalizador --sarif-add-baseline-file-info à invocação codeql database analyze no sistema de CI, por exemplo:

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

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

Observação

A funcionalidade de gerenciamento de pacote do CodeQL, incluindo pacotes do CodeQL, está em versão beta no momento e sujeita a alterações. Durante a versão beta, os pacotes do CodeQL estão disponíveis apenas usando o GitHub Packages – O Container registry do GitHub. Para usar essa funcionalidade beta, instale a versão mais recente do pacote da CodeQL CLI de: https://github.com/github/codeql-action/releases.

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 "Publicar e usar pacotes do 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 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 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'

Caso você precise referenciar um arquivo de consulta, um diretório ou um pacote cujo caminho contenha um literal @ ou :, acrescente o prefixo path: à especificação de consulta 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 os pacotes do CodeQL, confira Como personalizar a análise com pacotes 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 "Como carregar os resultados da análise do CodeQL no GitHub" 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".

Como incluir pacotes de modelos para adicionar fontes potenciais de dados afetados

Nota: os modelos de risco estão atualmente em versão beta e sujeitos a alterações. Durante a beta, só há suporte para os modelos de risco em análises Java.

Você pode configurar modelos de risco em uma análise code scanning. Para obter mais informações, consulte “Customizing library models for Java and Kotlin” na documentação CodeQL.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

Neste exemplo, as consultas relevantes no pacote de consultas padrão codeql/java-queriesusam o modelo de risco local, bem como o modelo de risco padrão para fontes de fluxo de dados remote. Você deve usar o modelo de risco local se considerar dados de fontes locais (por exemplo: sistemas de arquivos, argumentos da linha de comando, bancos de dados e variáveis de ambiente) como fontes potenciais de dados afetados para sua base de código.

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 da CLI do CodeQL".

Para obter mais informações sobre a aparência dos resultados no formato CSV, consulte "Saída CSV da CodeQL CLI".

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.

Visualizando o registro e as informações de diagnóstico

Ao analisar um banco de dados CodeQL usando um conjunto de consultas de code scanning, além de gerar informações detalhadas sobre alertas, a CLI relata dados de diagnóstico da etapa de geração de banco de dados e resumo de métricas. Se você quiser gerar a saída SARIF, os dados adicionais também serão incluídos no arquivo SARIF. Para repositórios com poucos alertas, você pode considerar úteis essas informações para determinar se realmente existem poucos problemas no código, ou se houve erros ao gerar o banco de dados CodeQL. Para obter uma saída mais detalhados de codeql database analyze, use a opção --verbose.

Para saber mais sobre o tipo de informações de diagnóstico disponível, confira "Visualizar os registros de varredura de código".

Você pode optar por exportar e carregar informações de diagnóstico para o GitHub Enterprise Cloud, mesmo se uma análise do CodeQL falhar. Para obter mais informações, confira "Como carregar os resultados da análise do CodeQL no GitHub".

Próximas etapas