Executando o CodeQL CLI no seu sistema de CI

Você pode usar CodeQL CLI para executar CodeQL Varredura de código em um sistema de integração contínua de terceiros.

Varredura de código is available for organization-owned repositories where Segurança Avançada GitHub is enabled. Para obter mais informações, consulte "Sobre Segurança Avançada GitHub".

Observação: O administrador do site deve habilitar Varredura de código para sua instância do GitHub Enterprise Server antes de usar este recurso. Para obter mais informações, consulte "Configurar o Varredura de código para seu aplicativo ".

Sobre o CodeQL CLI

Você pode usar CodeQL CLI para executar o Varredura de código no código que você está processando em um sistema de integração contínua (CI) de terceiros. Varredura de código é um recurso que você usa para analisar o código em um repositório de GitHub para localizar vulnerabilidades de segurança e erros de codificação. Quaisquer problemas identificados pela análise são exibidos em GitHub Enterprise Server. Para obter informações, consulte "Sobre Varredura de código.

The CodeQL CLI is a standalone product that you can use to analyze code. Its main purpose is to generate a database representation of a codebase, a CodeQL database. Once the database is ready, you can query it interactively, or run a suite of queries to generate a set of results in SARIF format and upload the results to sua instância do GitHub Enterprise Server.

Como alternativa, você pode usar Executor do CodeQL no seu sistema de CI, ou GitHub Actions para executar Varredura de código dentro de GitHub Enterprise Server. Para obter uma visão geral das opções para os sistemas de CI, consulte "Sobre o CodeQL Varredura de código no seu sistema de CI". Para obter informações sobre Varredura de código usando ações, consulte "Configurar Varredura de código para um repositório".

Observação: O CodeQL CLI está disponível para clientes com uma licença de Segurança Avançada.

Fazer o download do CodeQL CLI

Você deve fazer o download do pacote CodeQL em https://github.com/github/codeql-action/releases. O pacote contém:

  • produto de CodeQL CLI
  • Uma versão compatível das consultas e bibliotecas de https://github.com/github/codeql
  • Versões pré-compiladas de todas as consultas incluídas no pacote

Você sempre deve usar o pacote de CodeQL, uma vez que ele garante compatibilidade e também fornece um desempenho muito melhor do que um download separado de CodeQL CLI e checkout das consultas de CodeQL. Se você estiver executando o CLI apenas em uma plataforma específica, faça o download do arquivo codeql-bundle-PLATFORM.tar.gz apropriado. Como alternativa, você pode fazer o download de codeql-bundle.tar.gz, que contém a CLI para todas as plataformas compatíveis.

Configurando o CodeQL CLI no seu sistema de CI

Você precisa disponibilizar todo o conteúdo do pacote CodeQL CLI para cada servidor de CI no qual você deseja executar a análise de CodeQL de Varredura de código. Por exemplo, você pode configurar cada servidor para que copie o pacote de um local interno central, interno e extraí-lo. Como alternativa, você pode usar a API REST para obter o pacote diretamente do GitHub, garantindo que você irá beneficiar-se das últimas melhorias das consultas. Atualizações no CodeQL CLI são lançadas a cada 2 a 3 semanas. Por exemplo:

$ wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ../codeql-bundle-linux64.tar.gz

Depois de extrair o pacote do CodeQL CLI, você poderá executar o executável codeql no servidor:

  • Ao executar /extraction-root/codeql/codeql, em que <extraction-root> é a pasta de onde você extraiu o pacote CodeQL CLI.
  • Adicionando /extraction-root/codeql ao seu PATH, para que você possa executar o executável como apenas codeql.

Testando a configuração de CodeQL CLI

Depois de extrair o pacote de CodeQL CLI, você pode executar o comando a seguir para verificar se a CLI está configurada corretamente para criar e analisar bases de dados.

  • codeql resolve linguagens se /extraction-root/codeql estiver no PATH.
  • caso contrário, /extraction-root/codeql/codeql resolve linguagens.

Exemplo de saída bem-sucedida:

cpp (/extraction-root/codeql/cpp)
csharp (/extraction-root/codeql/csharp)
csv (/extraction-root/codeql/csv)
go (/extraction-root/codeql/go)
html (/extraction-root/codeql/html)
java (/extraction-root/codeql/java)
javascript (/extraction-root/codeql/javascript)
properties (/extraction-root/codeql/properties)
python (/extraction-root/codeql/python)
xml (/extraction-root/codeql/xml)

Se CodeQL CLI não conseguir resolver as linguagens esperadas, certifique-se de que você fez o download do pacote CodeQL e não uma cópia independente do CodeQL CLI.

Gerando um token para autenticação com GitHub Enterprise Server

Cada servidor de CI precisa de um aplicativo GitHub ou token de acesso pessoal para CodeQL CLI para usar para fazer o upload dos resultados para GitHub Enterprise Server. Você deve usar um token de acesso ou um aplicativo GitHub com a permissão de gravação de security_events. Se os servidores de CI já usam um token com este escopo para repositórios de checkout de GitHub Enterprise Server, potencialmente você poderia permitir que CodeQL CLI usasse o mesmo token. Caso contrário, você deve criar um novo token com a permissão de gravação de security_events e adicionar isso à loja secreta do sistema de CI. Para obter informações, consulte "Criar Aplicativos do GitHub" e "Criar um token de acesso pessoal".

Usando CodeQL CLI para gerar dados e fazer o upload GitHub Enterprise Server

Você chama CodeQL CLI para analisar o codebase em três etapas:

  1. Crie um banco de dados de CodeQL para representar uma única linguagem de programação no repositório usando: criação do banco de dados do codeql
  2. Execute consultas para analisar o banco de dados de CodeQL e resumir os resultados em um arquivo SARIF usando: análise do banco de dados de codeql
  3. Faça o upload do arquivo SARIF para GitHub Enterprise Server em que os resultados correspondem a um branch ou pull request e é exibido como alertas de Varredura de código que usam: resultados do upload do github do codeql

Cada comando tem algumas opções obrigatórias, com opções adicionais que você pode usar para modificar o comportamento do comando. Você pode mostrar a ajuda de linha de comando para qualquer comando usando --help opção.

Note: Uploading SARIF data to display as Varredura de código results in GitHub Enterprise Server is supported for organization-owned repositories with Segurança Avançada GitHub enabled. Para obter mais informações, consulte "Gerenciar configurações de segurança e análise do seu repositório".

Criando um banco de dados de CodeQL para analisar

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

    • Para um branch, faça check-out do cabeçalho do branch que você quer analisar.
    • Para um pull request, faça o check-out do commit do cabeçalho do pull request ou do commit de merge gerado por GitHub Enterprise Server do pull request.
  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. Execute a criação do banco de dados do codeql a partir da raiz de checkout do seu repositório.

    codeql database create <database> --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.
`--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).
`--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.
`--command` Opcional para linguagens compiladas. Use se você desejar substituir a detecção e compilação automática do sistema de compilação de CLI. Especifique o comando de criação ou script que chama o compilador. Os comandos são executados a partir da pasta atual ou de onde são definidos, a partir de `--source-root`. Não use esta opção para análise de Python e JavaScript/TypeScript.

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

Exemplo básico
$ 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.

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

Analisando um banco de dados de CodeQL

  1. Criar um banco de dados de CodeQL (ver acima).
  2. Execute análise do banco de dados de codeql no banco de dados e especifique quais consultas usar.
    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.
<queries> Especifique as consultas a executar. Para executar as consultas padrão usadas para Varredura de código, use: <language>-code-scanning.qls, em que <language> é um código curto para a linguagem do banco de dados. Para ver os outros itens de consulta 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: 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.

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

Exemplo básico
$ 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

Note: 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.

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 criou antes para o CodeQL CLI (consulte gerar um token para autenticação com GitHub Enterprise Server acima). Recomendamos que você revise a orientação do seu sistema de CI sobre o uso seguro da loja de segredo. 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/pulls/NUMBER/head ou para o commit de merge gerado por GitHub Enterprise Server 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-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
$ 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. Alertas são exibidos diretamente no pull request ou na aba Segurança para branches, dependendo do código que foi feito check-out. 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

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.