Usar a CLI do CodeQL

8 minutos

Além da interface gráfica do usuário no GitHub.com, você também pode acessar muitos dos mesmos recursos primários do CodeQL por meio de uma interface de linha de comando.

Esta unidade abordará o uso da CLI do CodeQL para criar e analisar bancos de dados e carregar os resultados no GitHub.

Comandos da CLI do CodeQL

Depois de disponibilizar a CLI do CodeQL para os servidores em seu sistema de CI e garantir que eles possam se autenticar com o GitHub, você estará pronto para gerar dados.

Você pode usar três comandos diferentes para gerar resultados e carregá-los no GitHub:

database create para criar um banco de dados CodeQL para representar a estrutura hierárquica de cada linguagem de programação com suporte no repositório.
database analyze executar consultas para analisar cada banco de dados do CodeQL e resumir os resultados em um arquivo SARIF.
github upload-results para carregar os arquivos SARIF resultantes para GitHub em que os resultados são correspondidos a uma ramificação ou solicitação de pull e exibidos como alertas de verificação de código.

Você pode exibir a ajuda de linha de comando para qualquer comando usando o --help option.

Carregar os dados do SARIF para exibir como resultados da verificação de código no GitHub tem suporte para repositórios de propriedade da organização com o GitHub Advanced Security habilitado e repositórios públicos em GitHub.com.

Criar bancos de dados do CodeQL para analisar

Siga estas etapas para criar bancos de dados CodeQL a serem analisados.

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, confira a confirmação de cabeçalho da solicitação de pull ou confira um commit de mesclagem gerada pelo GitHub da solicitação de pull.
Configure o ambiente para a base de código, verificando se todas as dependências estão disponíveis.
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.
Execute codeql database create da raiz de check-out do seu repositório e compile a base de código:
- Para criar um banco de dados CodeQL para uma só linguagem com suporte, use o seguinte comando:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Para criar um banco de dados CodeQL por linguagem para várias linguagens com suporte, use o seguinte comando:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Observação

Se você usar um build em contêiner, precisará executar a CLI do CodeQL dentro do contêiner em que a tarefa de build ocorre.

A lista completa de parâmetros para o comando database create é mostrada na seguinte tabela:

Opção	Uso necessário
`<database>`	Especifique o nome e o local de um diretório a ser criado para o banco de dados 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.
`--language`	Especifique o identificador do idioma para criar um banco de dados para um de `cpp`, `csharp`, `go`, `java`, `javascript`, `python` e `ruby` (use JavaScript para analisar o código TypeScript). Quando usado com `--db-cluster`, a opção aceita uma lista separada por vírgulas ou pode ser especificada mais de uma vez.
`--command`	Recomendá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 a partir da pasta atual ou, onde ela é definida, de `--source-root`. Não é necessário para a análise de Python e JavaScript/TypeScript.
`--db-cluster`	Opcional. Use em bases de código de vários linguagens para gerar um banco de dados para cada linguagem especificada pelo `--language`.
`--no-run-unnecessary-builds`	Recomendável. Use para suprimir o comando de build para idiomas em que a CLI do CodeQL não precisa monitorar o build (por exemplo, Python e JavaScript/TypeScript).
`--source-root`	Opcional. Use se você executa a CLI fora da raiz de check-out do repositório. Por padrão, o comando database create presume que o diretório atual é o diretório raiz para os arquivos de origem. Use essa opção para especificar outro local.

Exemplo de linguagem única

Este exemplo cria um banco de dados 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 várias linguagens

Este exemplo cria dois bancos de dados 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 informar à ferramenta o comando de build para a base de código, veja aqui.
--no-run-unnecessary-builds para dizer à ferramenta para ignorar o comando de build para idiomas 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.
$

Analisar um banco de dados CodeQL

Depois de criar o seu banco de dados do CodeQL, siga essas etapas para analisá-lo:

Opcionalmente, execute codeql pack download <packs> para baixar qualquer pacote de CodeQL (beta) que você queira executar durante a análise.
Execute codeql database analyze no banco de dados e especifique quais pacotes e/ou consultas usar.

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

Observação

Se você analisar mais de um banco de dados do CodeQL para uma só confirmação, será necessário especificar uma categoria SARIF para cada conjunto de resultados gerados por esse comando. Quando você carrega os resultados para o GitHub, a verificação de código usa essa categoria para armazenar os resultados de 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>

A lista completa de parâmetros para o comando database analyze é mostrada na seguinte tabela:

Opção	Uso necessário
`<database>`	Especifique o caminho para o diretório que contém o banco de dados CodeQL a ser analisado.
`<packs,queries>`	Especifique os pacotes de CodeQL ou as consultas a serem executadas. Para executar as consultas padrão usadas para verificação de código, omita esse parâmetro. Você pode encontrar os outros conjuntos de consultas incluídos no pacote da CLI do CodeQL, em `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Para obter informações sobre como criar seu próprio conjunto de consultas, consulte Criando conjuntos de consultas CodeQL^[5] na documentação da CLI do CodeQL.
`--format`	Especifique o formato para o arquivo de resultados gerado pelo comando. Para carregar no GitHub, deve ser: `sarif-latest`.
`--output`	Especifique em que local salvar o arquivo de resultados 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-query-help`	Opcional. 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.
`<packs>`	Opcional. Use se você baixou os pacotes de consulta do CodeQL e deseja executar as consultas padrão ou os conjuntos de consulta especificados nos pacotes.
`--threads`	Opcional. 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`	Opcional. 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.

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. Isso é essencial quando você tem mais de um banco de dados CodeQL para analisar um só 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.

Carregar os resultados para o GitHub

O upload sarif dá suporte a um máximo de 25.000 resultados por upload. No entanto, apenas os 5.000 principais resultados são exibidos, priorizados pela gravidade. Se uma ferramenta gerar muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados referentes às regras ou às consultas mais importantes.

Cada upload do SARIF dá suporte a um máximo de 10 MB para o arquivo SARIF compactado gzip. Todos os uploads acima desse limite são rejeitados. Se o arquivo SARIF for muito grande porque contém muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados das regras ou consultas mais importantes. Para obter mais informações sobre limitações e validação de arquivos SARIF, consulte a documentação^[6].

Para carregar os resultados para o GitHub, determine a melhor maneira de passar o token de acesso pessoal ou aplicativo GitHub criado anteriormente para a CLI do CodeQL. Recomendamos que você examine as diretrizes do sistema da CI sobre o uso seguro de um repositório secreto. A CLI do CodeQL dá suporte a:

Interface com um armazenamento secreto utilizando a opção --github-auth-stdin. Essa é a maneira recomendada de autenticação.
Salvar o segredo na variável de ambiente GITHUB_TOKEN e executar a CLI sem incluir a opção --github-auth-stdin.
Passe a opção de linha de comando --github-auth-stdin e forneça um token temporário pela entrada padrão. Isso é recomendado para fins de teste.

Quando você tiver decidido qual é 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.

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>

A lista completa de parâmetros para o github upload-results comando é mostrada na tabela da seguinte maneira.

Opção	Uso necessário
`--repository`	Especifique o PROPRIETÁRIO/NOME do repositório no qual carregar dados. O proprietário deve ser uma organização em uma empresa que tem uma licença para o GitHub Advanced Security e este deve estar habilitado para o repositório, a menos que o repositório seja público.
`--ref`	Especifique o nome da referência de que 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 a confirmação principal de uma solicitação de pull, use `refs/pulls/NUMBER/head`; ou para a confirmação de mesclagem gerada pelo GitHub de uma solicitação de pull, use `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 do token de acesso pessoal ou aplicativo GitHub criado para autenticação com a API REST do GitHub por meio de 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.

Comentários

Esta página foi útil?