Sobre a análise de bancos de dados com o CodeQL CLI
Para analisar uma base de código, execute consultas em um CodeQL banco de dados extraído do código. CodeQL as análises produzem resultados que podem ser carregados em GitHub para gerar alertas de verificação de código.
Pré-requisitos
Antes de iniciar uma análise, você precisa:
-
[Configurar o CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) para executar comandos localmente. -
[Crie um CodeQL banco de dados](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) para o código-fonte que você deseja analisar.
A maneira mais simples de executar codeql database analyze é usando as consultas padrão incluídas no CodeQL CLI pacote.
Em execução codeql database analyze
Quando executado, o database analyze:
- Opcionalmente, baixa todos os pacotes referenciados CodeQL que não estão disponíveis localmente.
- Executa um ou mais arquivos de consulta executando-os em um CodeQL banco de dados.
- 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 CodeQL banco de dados para uma única confirmação, deverá especificar uma categoria SARIF para cada conjunto de resultados gerados por esse comando. Quando você carrega os resultados, GitHubcode scanning usa essa categoria para armazenar os resultados de cada idioma 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ção | Obrigatório | Usage |
|---|---|---|
<database> | Especifique o caminho para o diretório que contém o CodeQL banco de dados a ser analisado. | |
<packs,queries> | Especifique CodeQL pacotes ou consultas a serem executados. Para executar as consultas padrão usadas para code scanning, omita esse parâmetro. Para ver os outros conjuntos de consultas incluídos no CodeQL CLI pacote, execute codeql resolve queries. Os conjuntos listados ali podem ser fornecidos com ou sem a extensão .qls. Para obter informações sobre como criar seu próprio conjunto de consultas, consulte Como criar conjuntos de consultas do CodeQL na documentação do 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 carregar para GitHub isso deve ser: sarif-latest. Para saber mais, confira Suporte SARIF para a varredura de código. | |
--output | Especifique o local onde você deseja salvar o arquivo de resultados SARIF, incluindo o nome do arquivo desejado com a extensão .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-baseline-file-info |
**Recomendado.** Use para enviar informações de cobertura de arquivo para o página de status da ferramenta. Para saber mais, confira [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files). |
| --sarif-include-query-help | | Especifique se deseja incluir ajuda de consulta na saída SARIF. Um destes: always: incluir ajuda de consulta para todas as consultas.
custom_queries_only (padrão): incluir ajuda de consulta apenas para consultas personalizadas, ou seja, aquelas em pacotes que não são do formulário codeql/<lang>-queries.
never: Não inclua ajuda de consulta para quaisquer consultas. Qualquer ajuda de consulta para consultas personalizadas incluídas na saída SARIF será exibida nos alertas de verificação de código para a consulta. Para saber mais, confira Escrevendo consultas personalizadas para a CLI do CodeQL. |
| <packs> | | Use se você quiser incluir CodeQL pacotes de consulta em sua análise. Para obter mais informações, veja Baixando e usando CodeQL pacotes. |
| --download | | Use se alguns de seus CodeQL pacotes de consulta ainda não estiverem em disco e precisarem ser baixados antes de executar consultas. |
| --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. |
| --threat-model | | (Versão prévia pública) Utilize para adicionar modelos de ameaça e configurar fontes adicionais em sua CodeQL análise. Durante o versão prévia pública, os modelos de ameaça são suportados apenas por análise em Java. Para saber mais, confira análise de banco de dados. |
Observação
**Como atualizar bancos de dados**
Para bancos de dados criados pela CodeQL CLI v2.3.3 ou anterior, você precisará atualizar explicitamente o banco de dados antes de executar uma análise com uma versão mais recente do 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 as atualizações necessárias. Não é necessário executar explicitamente o comando de atualização.
Para mais detalhes de todas as opções que você pode usar ao analisar bancos de dados, confira análise de banco de dados.
Exemplo básico de análise de um CodeQL banco de dados
Este exemplo analisa um CodeQL banco de dados armazenado /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 CodeQL banco de dados para analisar uma única confirmação 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 GitHub para exibição no página de status da ferramenta para code scanning. Para saber mais sobre as informações de cobertura de arquivo, confira Usar a página de status da ferramenta para verificação de código.
Para incluir informações de cobertura de arquivo com seus code scanning resultados, adicione o flag --sarif-add-baseline-file-info à chamada codeql database analyze em seu 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 CodeQL pacotes e como usar um check-out local do CodeQL repositório. Esses exemplos pressupõem que seus CodeQL bancos de dados foram criados em um diretório que é um irmão de suas cópias locais do CodeQL repositório.
Executando um CodeQL pacote de consultas
Para executar um pacote de consultas existente a partir do GitHubContainer registry, você pode especificar um ou mais nomes de pacote:
codeql database analyze <database> microsoft/[email protected] github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download
Esse comando executa o conjunto de consultas padrão de dois CodeQL pacotes de consulta: microsoft/coding-standards versão 1.0.0 e a versão mais recente do banco de github/security-queries dados especificado. Para saber mais 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 única consulta em um CodeQL banco de dados para uma base de código JavaScript, você pode usar o seguinte comando do diretório que contém seu 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 , é uma das consultas JavaScript incluídas no CodeQL repositório. 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ê tiver o CodeQL repositório verificado, poderá executar as mesmas consultas especificando o caminho para a 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 usar com o CodeQL CLI, consulte AUTOTITLE.
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 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, basta executar:
codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download
Como alternativa, se você tiver o CodeQL repositório verificado, 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. Especificar --format=sarif-latest garante que os resultados sejam formatados de acordo com a especificação SARIF mais recente suportada por CodeQL.
Executando um subconjunto de consultas em um CodeQL pacote
Se você estiver usando CodeQL CLI a 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 CodeQL pacote. -
`range` é um [intervalo semver](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). -
`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 CodeQL
Pacote.
Para analisar um banco de dados usando todas as consultas na experimental/Security pasta dentro do codeql/cpp-queriesCodeQL pacote, 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-queriesCodeQL, use:
codeql database analyze --format=sarif-latest --output=results <db> \
'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'
Para analisar seu banco de dados usando a suite de consultas cpp-security-and-quality.qls de uma versão do pacote codeql/cpp-queriesCodeQL que é >= 0.0.3 e < 0.1.0, (a versão mais alta compatível 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 CodeQL pacotes, consulte Como personalizar a análise com pacotes CodeQL.
Como executar conjuntos de consultas
Para executar um conjunto de consultas em um CodeQL banco de dados para uma base de código C/C++, você pode usar o seguinte comando do diretório que contém 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 codeql/cpp-queriesCodeQL pacote de consultas, executa a análise e gera um arquivo no formato SARIF versão 2.1.0 compatível com todas as versões de GitHub. Esse arquivo pode ser carregado para GitHub pela execução de codeql github upload-results ou pela API de verificação de código.
Para obter mais informações, confira Carregando resultados da análise do CodeQL para GitHub ou Pontos de extremidade da API REST para varredura de código.
CodeQL Os conjuntos de consultas são `.qls` arquivos que usam diretivas para selecionar consultas a serem executadas com base em determinadas propriedades de metadados. Os pacotes padrão CodeQL têm metadados que especificam o local dos conjuntos de consultas usados pela verificação de código, para que o sistema CodeQL CLI saiba onde encontrar esses arquivos dos pacotes automaticamente, e você não precisa especificar o caminho completo na linha de comando.
Para saber mais, 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
Observação
Modelos de riscos estão em versão prévia pública e estão sujeitos a alterações. Durante o versão prévia pública, os modelos de risco são compatíveis apenas com a análise para Java/Kotlin e C#.
Você pode configurar modelos de ameaças em uma code scanning análise. Para obter mais informações, consulte Modelos de ameaças para Java e Kotlin e Modelos de ameaças para C# 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.
Results
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.
Para saber mais 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
Quando você analisa um CodeQL banco de dados usando um code scanning conjunto de consultas, 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 métricas de resumo. 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 achar essas informações úteis para determinar se há realmente poucos problemas no código ou se houve erros ao gerar o CodeQL banco de dados. 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 Logs de análise de código.
Você pode optar por exportar e carregar informações de diagnóstico para GitHub mesmo que uma CodeQL análise falhe. Para saber mais, confira Carregando resultados da análise do CodeQL para GitHub.
Próximas etapas
- Para saber como carregar os CodeQL resultados da análise para GitHub, consulte Carregando resultados da análise do CodeQL para GitHub.