Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.

Configurando a CLI do CodeQL no seu sistema de CI

Você pode configurar seu sistema de integração contínua para executar o CodeQL CLI, realizar análise de CodeQL e fazer o upload dos resultados para GitHub para exibição como os alertas de code scanning.

Code scanning está disponível para todos os repositórios públicos no GitHub.com. Code scanning também está disponível em repositórios privados pertencentes às organizações que usam o GitHub Enterprise Cloud e têm uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Sobre como gerar resultados de varredura de código com CodeQL CLI

Uma vez disponibilizado o CodeQL CLI para servidores o seu sistema de CI e após garantir ele possa ser autenticado com GitHub, você estárá pronto para gerar dados.

Você usa três comandos diferentes para gerar resultados e fazer o upload deles para GitHub:

  1. database create para criar um banco de dados do CodeQL a fim de representar a estrutura hierárquica de cada linguagem de programação compatível no repositório.
  2. database analyze para executar consultas a fim de analisar cada banco de dados do CodeQL e resumir os resultados em um arquivo SARIF.
  3. github upload-results para carregar os arquivos SARIF resultantes no GitHub, no qual será feita a correspondência dos resultados com um branch ou uma solicitação de pull e no qual eles serão exibidos como alertas da code scanning.

Veja a ajuda da linha de comando para qualquer comando usando a opção --help.

Observação: há suporte para o upload de dados SARIF a serem exibidos como resultados da code scanning no GitHub nos repositórios pertencentes à organização com o GitHub Advanced Security habilitado e em repositórios públicos no GitHub.com. Para obter mais informações, confira "Como gerenciar as configurações de segurança e de análise do seu repositório".

Criando bancos de dados de CodeQL para analisar

  1. Confira o código que você deseja analisar:

    • Para uma ramificação, confira o cabeçalho da ramificação que você deseja analisar.
    • Para uma solicitação de pull, faça check-out do commit principal da solicitação de pull ou confira um commit de mesclagem da solicitação de pull gerado pelo GitHub.
  2. Configure o ambiente para a base de código, verificando se todas as dependências estão disponíveis. Para obter mais informações, confira "Como criar bancos de dados para linguagens não compiladas" e "Como criar bancos de dados para linguagens compiladas".

  3. Localize o comando de build, se houver, para a base de código. Normalmente, isso está disponível em um arquivo de configuração no sistema de CI.

  4. Execute codeql database create na raiz do check-out do repositório e compile a base de código.

    # Single supported language - create one CodeQL database
    codeql database create <database> --command<build> --language=<language-identifier>
    
    # Multiple supported languages - create one CodeQL database per language
    codeql database create <database> --command<build> \
          --db-cluster --language=<language-identifier>,<language-identifier>

    Observação: se você usar um build conteinerizado, precisará executar a CodeQL CLI no contêiner em que ocorre a tarefa de build.

OpçãoObrigatórioUso
<database>Especifique o nome e local de um diretório a ser criado para o banco de dados de CodeQL. O comando falhará se você tentar substituir um diretório. Se você também especificar --db-cluster, esse será o diretório pai e um subdiretório será criado para cada linguagem analisada.
--languageEspecifique entre os seguintes identificadores aquele da linguagem para a qual um banco de dados será criado: cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby (use javascript para analisar o código TypeScript e java para analisar o código Kotlin). Quando usado com --db-cluster, a opção aceita uma lista separada por vírgulas ou pode ser especificada mais de uma vez.
--commandRecomendável. Use para especificar o comando ou o script de build que invoca o processo de build para a base de código. Os comandos são executados por meio da pasta atual ou no local em que são definidos, em --source-root. Não é necessário para a análise de Python e JavaScript/TypeScript.
--db-clusterOpcional. Use bases de código de linguagem múltipla para gerar um banco de dados para cada linguagem especificada por --language.
--no-run-unnecessary-buildsRecomendável. Use para suprimir o comando de compilação para linguagens em que CodeQL CLI não precisa monitorar a criação (por exemplo, Python e JavaScript/TypeScript).
--source-rootOpcional. Use se você executa a CLI fora da raiz de check-out do repositório. Por padrão, o comando database create pressupõe que o diretório atual seja o diretório raiz dos arquivos de origem. Use essa opção para especificar outro local.
--codescanning-configOpcional (Avançado). Use se você tiver um arquivo de configuração que especifica como criar os bancos de dados CodeQL e quais consultas serão executadas em etapas posteriores. Para obter mais informações, confira "Como personalizar a code scanning" e "criação de banco de dados".

Para obter mais informações, confira "Como criar bancos de dados do CodeQL".

Exemplo de linguagem única

Este exemplo cria um banco de dados do CodeQL para o repositório com check-out em /checkouts/example-repo. Ele usa o extrator de JavaScript para criar uma representação hierárquica do código JavaScript e TypeScript no repositório. O banco de dados resultante é armazenado no /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Exemplo de linguagem múltipla

Este exemplo cria dois bancos de dados do CodeQL para o repositório com check-out em /checkouts/example-repo-multi. Ele usa:

  • --db-cluster para solicitar a análise de mais de uma linguagem.
  • --language para especificar para quais linguagens os bancos de dados são criados.
  • --command para indicar o comando de build para a base de código à ferramenta, acesse aqui make.
  • --no-run-unnecessary-builds para informar a ferramenta para ignorar o comando de build para linguagens em que ele não é necessário (como Python).

Os bancos de dados resultantes são armazenados em subdiretórios python e cpp do /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Analisando um banco de dados de CodeQL

  1. Criar um banco de dados de CodeQL (ver acima).
  2. Execute codeql database analyze no banco de dados e especifique os pacotes e/ou as consultas a serem usados.
    codeql database analyze <database> --format=<format> \
        --output=<output>  --download <packs,queries>

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, 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>
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 conjunto 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 pelo comando. Para upload no GitHub, isso deve ser: sarif-latest. Para obter mais informações, confira "Suporte do SARIF à code scanning".
--outputEspecifique em que local salvar o arquivo de resultados 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-query-helpOpcional. 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 analisar bancos de dados com a CodeQL CLI".
<packs>Opcional. 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".
--downloadOpcional. Use se alguns de seus pacotes de consulta CodeQL ainda não estiverem em disco e precisarem ser baixados antes de executar consultas.
--threadsOpcional. 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.
--verboseOpcional. 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.

Para obter mais informações, confira "Como analisar bancos de dados com a CodeQL CLI".

Exemplo básico

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

Fazendo upload de resultados para GitHub

Você pode verificar se as propriedades SARIF têm um tamanho compatível com o upload e se o arquivo é compatível com a verificação de código. Para obter mais informações, confira "Validar o arquivo SARIF".

Para carregar os resultados no GitHub, você precisa determinar a melhor maneira de transmitir o GitHub App ou o personal access token já criado para a CodeQL CLI (confira Como instalar a CodeQL CLI no sistema de CI). Recomendamos que você examine as diretrizes do sistema da CI sobre o uso seguro de um repositório secreto. O CodeQL CLI é compatível com:

  • Passar o token para a CLI por meio de entrada padrão usando a opção --github-auth-stdin (recomendado).
  • Salvar o segredo na variável de ambiente GITHUB_TOKEN e executar a CLI sem incluir a opção --github-auth-stdin.

Quando você tiver decidido o método mais seguro e confiável para o servidor da CI, execute codeql github upload-results em cada arquivo de resultados do SARIF e inclua --github-auth-stdin, a menos que o token esteja disponível na variável de ambiente GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
OpçãoObrigatórioUso
--repositoryEspecifique o PROPRIETÁRIO/NOME do repositório no qual os dados serão carregados. O proprietário precisa ser uma organização dentro de uma empresa com uma licença do GitHub Advanced Security, e o GitHub Advanced Security precisa estar habilitado para o repositório, a menos que o repositório seja público. Para obter mais informações, confira "Como gerenciar as configurações de segurança e de análise do seu repositório".
--refEspecifique o nome da ref do qual você fez check-out e analisou para que os resultados possam corresponder ao código correto. Para um branch, use refs/heads/BRANCH-NAME, para o commit principal de uma solicitação de pull, use refs/pull/NUMBER/head ou para o commit de mesclagem de uma solicitação de pull gerado pelo GitHub, use refs/pull/NUMBER/merge.
--commitEspecifique o SHA completo do commit que você analisou.
--sarifEspecifique o arquivo SARIF a ser carregado.
--github-auth-stdinOpcional. Use essa opção para passar à CLI o GitHub App ou o personal access token já criado para autenticação com a API REST do GitHub por meio da entrada padrão. Isso não será necessário se o comando tiver acesso a uma variável de ambiente GITHUB_TOKEN definida com esse token.

Para obter mais informações, confira os resultados de upload do GitHub na documentação da CodeQL CLI.

Exemplo básico

Este exemplo carrega os resultados do arquivo SARIF temp/example-repo-js.sarif no repositório my-org/example-repo. Ele informa à API da code scanning de que os resultados referem-se ao commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 no branch main.

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

Não há saída deste comando a menos que o upload não tenha sido bem-sucedido. A instrução de comando retorna quando o upload foi concluído e o processamento de dados é iniciado. Em bases de código menores, você poderá explorar os alertas de code scanning em GitHub pouco tempo depois. Você pode ver os alertas diretamente na solicitação de pull ou na guia Segurança dos branches, dependendo do código do qual você fez check-out. Para obter mais informações, confira "Como fazer a triagem de alertas da code scanning em solicitações de pull" e "Como gerenciar alertas da code scanning do seu repositório".

Fazendo o download e usando pacotes de consulta de CodeQL

Observação: a funcionalidade de gerenciamento de pacotes do CodeQL, incluindo pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

O pacote de CodeQL CLI inclui consultas mantidas por especialistas de GitHub, pesquisadores de segurança e contribuidores da comunidade. Se você quiser executar consultas desenvolvidas por outras organizações, os pacotes de consulta de CodeQL fornecem uma forma eficiente e confiável de fazer o download e executar consultas. Para obter mais informações, confira "Sobre a verificação de código com o CodeQL".

Antes de usar um pacote CodeQL para analisar um banco de dados, você deve baixar os pacotes necessários do GitHub Container registry. Isso pode ser feito usando o sinalizador --download como parte do comando codeql database analyze. Se um pacote não estiver disponível publicamente, você precisará usar um GitHub App ou um personal access token para fazer a autenticação. Para obter mais informações e um exemplo, confira "Como carregar os resultados no GitHub" acima.

OpçãoObrigatórioUso
<scope/name@version:path>Especifique o escopo e o nome de um ou mais pacotes de consulta CodeQL para fazer o download usando uma lista separada por vírgulas. Opcionalmente, inclua a versão para fazer o download e descompactar. Por padrão, a versão mais recente deste pacote foi baixada. Opcionalmente, inclua um caminho para um conjunto de consultas, diretórios ou consultas a serem executadas. Se nenhum caminho for incluído, execute as consultas padrão deste pacote.
--github-auth-stdinOpcional. Passe à CLI o GitHub App ou o personal access token criado para autenticação com a API REST do GitHub por meio da entrada padrão. Isso não será necessário se o comando tiver acesso a uma variável de ambiente GITHUB_TOKEN definida com esse token.

Observação: se você especificar uma versão específica de um pacote de consultas a ser usada, lembre-se de que a versão especificada pode acabar ficando muito antiga em relação à versão mais recente do CodeQL para garantir um uso eficiente. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, reavalie quais versões fixar sempre que atualizar a CLI do CodeQL que você está usando.

Para obter mais informações sobre a compatibilidade do pacote, confira "Sobre a compatibilidade de pacotes do CodeQL".

Exemplo básico

Este exemplo executa o comando codeql database analyze com a opção --download para:

  1. Baixar a versão mais recente do pacote octo-org/security-queries.
  2. Baixar uma versão do pacote octo-org/optional-security-queries que seja compativel com a versão 1.0.1 (nesse caso, é a versão 1.0.2). Para obter mais informações sobre compatibilidade semver, confira a documentação do intervalo de versão semântica do npm.
  3. Execute todas as consultas padrão em octo-org/security-queries.
  4. Executar somente a consulta queries/csrf.ql de octo-org/optional-security-queries
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Download direto de pacotes CodeQL

Se você quiser baixar um pacote CodeQL sem executá-lo imediatamente, poderá usar o comando codeql pack download. Isso será útil se você quiser evitar acessar a Internet ao executar consultas CodeQL. Ao executar a análise CodeQL, você pode especificar pacotes, versões e caminhos da mesma forma que no exemplo anterior:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Baixar pacotes do CodeQL de vários registros de contêiner do GitHub

Se os pacotes do CodeQL residirem em vários registros de contêiner, você precisará instruir a CodeQL CLI onde localizar cada pacote. Para obter mais informações, confira "Como personalizar a code scanning".

Exemplo de configuração de CI para análise de CodeQL

Este é um exemplo da série de comandos que você pode usar para analisar uma base de código com duas linguagens compatíveis e, em seguida, fazer o upload dos resultados para GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

# Upload the SARIF file with the Python results: 'python-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

Solucionando o CodeQL CLI do seu sistema de CI

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. 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 obter mais informações sobre os tipos de informações de diagnóstico disponíveis, confira "Como exibir os logs da code scanning".

Code scanning mostra apenas os resultados da análise de uma das linguagens analisadas

Por padrão, code scanning espera um arquivo de resultados SARIF por análise de um repositório. Consequentemente, quando se faz o upload de um segundo arquivo SARIF para um compromisso, ele é tratado como uma substituição do conjunto original de dados.

Se desejar fazer o upload de mais de um conjunto de resultados para a API de code scanning para um commit em um repositório, você deve identificar cada conjunto de resultados como um conjunto único. Para os repositórios em que você cria mais de um banco de dados do CodeQL a fim de analisar para cada commit, use a opção --sarif-category para especificar uma linguagem ou outra categoria exclusiva para cada arquivo SARIF que você gerar para esse repositório.

Problemas com a extração do Python

Estamos preterindo o suporte do Python 2 para a CodeQL CLI, mais especificamente para a fase de geração de banco de dados do CodeQL (extração de código).

Se você usa a CodeQL CLI para executar CodeQL code scanning no código escrito em Python, verifique se o sistema de CI tem o Python 3 instalado.

Leitura adicional