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 CodeQL para representar a estrutura hierárquica de uma linguagem de programação compatível com o repositório.
2. database analyze para executar consultas a fim de analisar o banco de dados CodeQL e resumir os resultados em um arquivo SARIF.
3. github upload-results para fazer o upload do arquivo SARIF resultante para GitHub Enterprise Server 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.

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.

   codeql database create <database> --command<build> --language=<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`, and `python` (use javascript para analisar o código TypeScript).
`--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.
`--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 básico

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.

Analisando um banco de dados de CodeQL

1. Criar um banco de dados de CodeQL (ver acima).
2. Executar codeql database analyze no banco de dados e especifique quais consultas devem ser usados.

   codeql database analyze <database> --format=<format> \
       --output=<output>  <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>		Especifique pacotes ou consultas de CodeQL para executar. Para executar as consultas padrão usadas para Varredura de código, omita este parâmetro. Para ver os outros itens de consulta incluídos no pacote de CodeQL CLI, consulte /<extraction-root>/qlpacks/codeql/<language>-queries/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: sarifv2.1.0. Para obter mais informações, consulte "Suporte SARIF para Varredura de código".
`--output`		Especifique onde salvar o arquivo de resultados SARIF.
`--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.

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.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls 
    --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

Antes de poder fazer o upload dos resultados para GitHub Enterprise Server, 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-url=<URL> --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. 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/pull/NUMBER/head ou para o commit de merge gerado por GitHub do uso de um pull request refs/pull/NUMBER/merge.
`--commit`		Especifique o SHA completo do commit que você analisou.
`--sarif`		Especifique o arquivo SARIF a ser carregado.
`--github-url`		Especifique a URL para GitHub Enterprise Server.
`--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-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 Varredura de código em GitHub Enterprise Server 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".

Leia mais

• Criando bancos de dados de CodeQL
• Analisando bancos de dados com a CLI do CodeQL