Configurando a CLI do CodeQL no seu sistema de CI

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.

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 do CodeQL" e "Como criar bancos de dados do CodeQL."

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.

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>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

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

Exemplo básico da 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=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 na página de status da ferramenta do 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 \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

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 "Suporte SARIF para a varredura de código".

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

Para obter mais informações, confira "github upload-results".

Exemplo básico do upload de resultados para GitHub

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 que você verificou. Para saber mais, confira "Alertas de varredura de código de triagem em pull requests" e "Gerenciamento de alertas de varredura de código para seu repositório".

Carregar informações de diagnóstico em GitHub se a análise falhar

Quando CodeQL CLI termina de analisar um banco de dados com êxito, ele coleta informações de diagnóstico, como cobertura de arquivo, avisos e erros, e o inclui no arquivo SARIF com os resultados. Quando você carrega o arquivo SARIF no GitHub, as informações de diagnóstico são exibidas na página de status de ferramentas do code scanning do repositório para facilitar a visualização de como CodeQL está funcionando e depurar eventuais problemas. Para obter mais informações, confira "Sobre a página de status da ferramenta para a verificação de código".

No entanto, se codeql database analyze falhar por algum motivo, não haverá nenhum arquivo SARIF para carregar no GitHub e nenhuma informação de diagnóstico a ser mostrada na página de status de ferramentas do code scanning para o repositório. Isso dificulta que os usuários solucionem problemas de análise, a menos que tenham acesso aos arquivos de log em seu sistema de CI.

Recomendamos que você configure seu fluxo de trabalho de CI para exportar e carregar informações de diagnóstico para GitHub quando uma análise falhar. Você pode fazer isso usando os comandos simples a seguir para exportar informações de diagnóstico e carregá-los em GitHub.

Exportar informações de diagnóstico se a análise falhar

Você pode criar um arquivo SARIF para a análise com falha usando "database export-diagnostics", por exemplo:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Esse arquivo SARIF conterá informações de diagnóstico para a análise com falha, incluindo quaisquer informações de cobertura de arquivo, avisos e erros gerados durante a análise.

Carregar informações de diagnóstico se a análise falhar

Você pode disponibilizar essas informações de diagnóstico na página de status da ferramenta carregando o arquivo SARIF em GitHub usando "github upload-results", por exemplo:

$ 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

Isso é o mesmo que o processo para carregar arquivos SARIF de análises bem-sucedidas.

Fazendo o download e usando pacotes de consulta de CodeQL

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 varredura de código com 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.

Exemplo básico do download e uso de pacotes de consulta

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 verificação de código".

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 saber mais sobre o tipo de informações de diagnóstico disponível, confira "Visualizar os registros de varredura de código".

O 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

• Como criar bancos de dados do CodeQL
• Como analisar bancos de dados com a CLI do CodeQL
• Como publicar e usar pacotes do CodeQL