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

Varredura de código está disponível para todos os repositórios públicos e para repositórios privados pertencentes a organizações em que Segurança Avançada GitHub está habilitado. Para obter mais informações, consulte "Sobre Segurança Avançada GitHub".

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. criar um banco de dados para criar um banco de dados de CodeQL para representar a estrutura hierárquica de cada linguagem de programação compatível no repositório.
  2. análise do banco de dados para executar consultas para analisar cada banco de dados de CodeQL e resumir os resultados em um arquivo SARIF.
  3. github upload-results para fazer o upload dos arquivos SARIF resultantes para GitHub em que os resultados são correspondentes a um branch ou pull request e exibidos como alertas de Varredura de código.

Você pode mostrar a ajuda de linha de comando para qualquer comando usando --help opção.

Observação: Fazer o upload dos dados SARIF para exibir como resultados de Varredura de código em GitHub é compatível com repositórios de organizações com Segurança Avançada GitHub habilitado, e repositórios públicos em GitHub.com. Para obter mais informações, consulte "Gerenciar configurações de segurança e análise do seu repositório".

Criando bancos de dados de CodeQL para analisar

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

    • Para um branch, confira o cabeçalho do branch que você deseja analisar.
    • Para um pull request, faça o checkout do commit principal do pull request, ou confira um commit do pull request gerado por GitHub.
  2. Defina o ambiente para a base de código, garantindo que quaisquer dependências estejam disponíveis. Para mais informações, consulte Criando bancos de dados para linguagens não compiladas e Criando bancos de dados para linguagens compiladas na documentação do CodeQL CLI.

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

  4. Execute codeql database creater a partir da raiz de checkout do seu repositório e construa a base de código.

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

    Observação: Se você usar uma criação conteinerizada, você deverá executar o CodeQL CLI no contêiner em que ocorre a tarefa de criação.

Opção Obrigatório Uso
<database> Especifique o nome e local de um diretório a ser criado para o banco de dados de CodeQL. O comando irá falhar se você tentar substituir um diretório existente. Se você também especificar --db-cluster, este será o diretório principal e um subdiretório será criado para cada linguagem analisada.
`--language` Especifique o identificador para a linguagem para criar um banco de dados: `cpp`, `csharp`, `go`, `java`, `javascript` e `python` (use javascript para analisar o código TypeScript).
When used with `--db-cluster`, a opção aceita uma lista separada por vírgulas, ou pode ser especificada mais de uma vez.
`--command` Recomendado. Use para especificar o comando de criação ou o script que invoca o processo de criação para a base de código. Os comandos são executados a partir da pasta atual ou de onde são definidos, a partir de `--source-root`. Não é necessário para análise de Python e JavaScript/TypeScript.
`--db-cluster` Opcional. Use em bases de código linguagem múltipla para gerar um banco de dados para cada linguagem especificada por `--language`.
`--no-run-unnecessary-builds` Recomendado. 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-root` Opcional. Use se você executar a CLI fora da raiz do check-out do repositório. Por padrão, o comando criação de banco de dados supõe que o diretório atual é o diretório raiz para os arquivos de origem, use esta opção para especificar uma localidade diferente.

Para obter mais informações, consulte Criar bancos de dados de CodeQL na documentação para o CodeQL CLI.

Exemplo de linguagem única

Este exemplo cria um banco de dados de CodeQL para o repositório verificado em /checkouts/example-repo. Ele usa o extrator do JavaScript para criar uma representação hierárquica do código JavaScript e TypeScript no repositório. O banco de dados resultante é armazenado em /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 de CodeQL para o repositório verificado em /checkouts/example-repo-multi. Ela usa:

  • --db-cluster para solicitar análise de mais de uma linguagem.
  • --language para especificar para quais linguagens criar bancos de dados.
  • --command para dizer a ferramenta que o comando de compilação para a base de código. Nesse caso, make.
  • --no-run-unnecessary-builds para informar a ferramenta que ignore o comando de criação para linguagens em que não é necessário (como Python).

Os bancos de dados resultantes são armazenados em python e nos subdiretórios cpp e /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.
Banco de dados criado com sucesso em /codeql-dbs/example-repo-multi.
$

Analisando um banco de dados de CodeQL

  1. Criar um banco de dados de CodeQL (ver acima).
  2. Opcional, execute codeql pack download para fazer o download de quaisquer pacotes (beta) de CodeQL que você deseja executar durante a análise. Para obter mais informações, consulte "Fazer o download e usando pacotes de consulta de CodeQL pacotes de consulta" abaixo.
    codeql pack download <packs> 
  3. Executar codeql database analyze no banco de dados e especifique quais pacotes e/ou consultas devem ser usados.
    codeql database analyze <database> --format=<format> \
        --output=<output>  <packs,queries> 

Observação: Se você analisar mais de um banco de dados de CodeQL para um único commit, você deverá especificar uma categoria SARIF para cada conjunto de resultados gerados por este comando. Ao fazer o upload dos resultados para GitHub, Varredura de código usa essa categoria para armazenar os resultados para cada linguagem separadamente. Se você esquecer de fazer isso, cada upload irá substituir os resultados anteriores.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>
Opção Obrigatório Uso
<database> Especifique o caminho para o diretório que contém o banco de dados de CodeQL a ser analisado.
<packs,queries> Specify CodeQL packs or queries to run. To run the standard queries used for Varredura de código, omit this parameter. Para ver os outros itens de consultas incluídos no pacote de CodeQL CLI, procure em /<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites. Para obter informações sobre como criar seu próprio conjunto de consulta, consulte Criando conjuntos de consultas de CodeQL na documentação do CodeQL CLI.
`--format` Especifique o formato para o arquivo de resultados gerado pelo comando. Para fazer upload para GitHub, deverá ser: sarif-latest. Para obter mais informações, consulte "Suporte SARIF para Varredura de código".
`--output` Especifique onde salvar o arquivo de resultados SARIF.
--sarif-category Opcional para análise única do banco de dados. Necessário para definir a linguagem quando você analisa vários bancos de dados para um único commit em um repositório. Especifique uma categoria a incluir no arquivo de resultados SARIF para esta análise. Usa-e uma categoria para distinguir várias análises para a mesma ferramenta e commit, mas é realizada em diferentes linguagens ou diferentes partes do código.
<packs> Opcional. Use se você fez o download dos pacotes de consulta CodeQL e desejar executar as consultas padrão ou os conjuntos de consulta especificados nos pacotes. Para obter mais informações, consulte "Fazer o download e usar pacotes de CodeQL."
`--threads` Opcional. Use se você quiser usar mais de um tópico 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` Opcional. Use para obter informações mais detalhadas sobre o processo de análise e dados de diagnóstico do processo de criação do banco de dados.

Para obter mais informações, consulte Analisando bancos de dados com CodeQL CLI na documentação do CodeQL CLI.

Exemplo básico

Este exemplo analisa um banco de dados 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. Isto é essencial quando você tem mais de um banco de dados de 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

Notas:

  • SARIF upload supports a maximum of 5000 results per upload. Todos os resultados acima deste limite são ignorados. Se uma ferramenta gerar muitos resultados, você deverá atualizar a configuração para focar nos resultados para as regras ou consultas mais importantes.

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

Antes de poder fazer o upload dos resultados para GitHub, você deverá determinar a melhor maneira de passar o token de acesso aplicativo GitHub ou pessoal que você criou anteriormente para o CodeQL CLI (consulte Instalando CodeQL CLI no seu sistema de CI). Recomendamos que você revise a orientação do seu sistema de CI sobre o uso seguro de um armazenamento de segredos. O CodeQL CLI é compatível com:

  • Passando o token para a CLI através da entrada padrão usando a opção --github-auth-stdin (recomendado).
  • Salvando o segredo na variável de ambiente GITHUB_TOKEN e executando a CLI sem incluir a opção --github-auth-stdin.

Quando você decidir o método mais seguro e confiável para o seu servidor de CI, execute codeql github upload-results no arquivo de resultados 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ção Obrigatório Uso
`--repository` Especifique o PROPRIETÁRIO/NOME do repositório para o qual será feito o upload dos dados. O proprietário deve ser uma organização dentro de uma empresa com uma licença para Segurança Avançada GitHub e Segurança Avançada GitHub deve estar habilitado para o repositório, a menos que o repositório seja público. Para obter mais informações, consulte "Gerenciar configurações de segurança e análise do seu repositório".
`--ref` Especifique o nome do ref que você verificou e analisou para que os resultados possam ser correspondidos ao código correto. Para o uso de um branch: refs/heads/BRANCH-NAME, para o commit principal de um pull request, use refs/pulls/NUMBER/head ou para o commit de merge gerado por GitHub do uso de um pull request refs/pulls/NUMBER/merge.
`--commit` Especifique o SHA completo do commit que você analisou.
`--sarif` Especifique o arquivo SARIF a ser carregado.
`--github-auth-stdin` Opcional. Use para passar a CLI, aplicativo GitHub ou o token de acesso pessoal criado para autenticação com a API REST de GitHubpor meio da entrada padrão. Isso não é necessário se o comando tiver acesso a uma variável de ambiente GITHUB_TOKEN definida com este token.

Para obter mais informações, consulte github upload-results na documentação para CodeQL CLI.

Exemplo básico

Este exemplo faz o upload dos resultados do arquivo SARIF temp/example-repo-js.sarif para o repositório meu-org/example-repo. Ele informa à API de Varredura de código que os resultados são para o 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 Varredura de código em GitHub pouco tempo depois. É possível ver alertas diretamente no pull request ou na aba Segurança para branches, dependendo do código que você fizer checkout. Para obter mais informações, consulte "Triar alertas de Varredura de código em pull requests" e "Gerenciar alertas de Varredura de código para o seu repositório".

Fazendo o download e usando pacotes de consulta de CodeQL

Note: The CodeQL package management functionality, including CodeQL packs, is currently in beta and subject to change.

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, consulte "Sobre digitalização de código com o CodeQL".

Antes de usar um pacote de CodeQL para analisar um banco de dados, você deve fazer o download de todos os pacotes que precisar a partir de GitHub Container registry executando codeql download e especificando os pacotes que você deseja baixar. Se um pacote não estiver disponível publicamente, você precisará usar um aplicativo GitHub ou um token de acesso pessoal para efetuar a autenticação. Para obter mais informações e um exemplo, consulte "o Fazer upload dos resultados para GitHub" acima.

codeql pack download <scope/name@version>,... 
Opção Obrigatório Uso
`` 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.
`--github-auth-stdin` Opcional. Passe o token de acesso aplicativo GitHub ou pessoal criado para autenticação com a API REST de GitHubpara a CLI por meio da entrada padrão. Isso não é necessário se o comando tiver acesso a uma variável de ambiente GITHUB_TOKEN definida com este token.

Exemplo básico

Este exemplo executa dois comandos para baixar a última versão do pacote octo-org/security-queries e, em seguida, analisar o banco de dados /codeql-dbs/exemplo-repo.

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download octo-org/security-queries

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0

$ codeql database analyze /codeql-dbs/example-repo  octo-org/security-queries \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/1] 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.
> [1/1 eval 394ms] Evaluation done; writing results to docto-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

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 Varredura de código, 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 saídas mais detalhadas de codeql database analyze, use a opção --verbose.

Para obter mais informações sobre o tipo de informações de diagnóstico disponíveis, consulte "Visualizar registros de Varredura de código".

Varredura de código mostra apenas os resultados da análise de uma das linguagens analisadas

Por padrão, Varredura de código 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 Varredura de código para um commit em um repositório, você deve identificar cada conjunto de resultados como um conjunto único. Para repositórios em que você cria mais de um banco de dados de CodeQL para 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.

Alternativa caso o seu sistema de CI não puder acionar CodeQL CLI

Se o seu sistema CI não puder habilitar o autobuild CodeQL CLI e você não puder especificar uma linha de comando para a compilação, você poderá usar o rastreamento de compilação indireto para criar bancos de dados de CodeQL para linguagens compiladas. Para obter mais informações, consulte Usando o rastreamento indireto de compilação na documentação de CodeQL CLI.

Leia mais

Esse documento ajudou você?

Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.