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 Enterprise Server, você estárá pronto para gerar dados.

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

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 Enterprise Server, 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 as consultas a serem usados.

   codeql database analyze <database> --format=<format> \
       --output=<output>  <queries>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <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=sarifv2.1.0 --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 Enterprise Server

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 Enterprise Server, 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-url=<URL> \
      --github-auth-stdin

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

Exemplo básico do upload de resultados para GitHub Enterprise Server

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-url=https://github.example.com \
    --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 Enterprise Server 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".

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

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

Leitura adicional

• Como criar bancos de dados do CodeQL
• Como analisar bancos de dados com a CLI do CodeQL