Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Esta versão do GitHub Enterprise será descontinuada em 2022-06-03. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

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 Enterprise Server para exibição como os alertas de Varredura de código.

Varredura de código está disponível para repositórios de organizações onde Segurança Avançada GitHub está habilitado. 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 your GitHub Enterprise Server instance antes de usar este recurso. Para obter mais informações, consulte "Configurar o Varredura de código para seu aplicativo ".

Observação: Este artigo descreve as funcionalidades presentes na versão de CodeQL CLI disponível no momento da versão de GitHub Enterprise Server. Se a sua empresa usar uma versão mais recente de CodeQL CLI, consulte a a documentação de GitHub Enterprise Cloud.

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.

Observação: Fazer o upload dos dados SARIF para exibir como resultados de Varredura de código em GitHub Enterprise Server é compatível com repositórios de organizações com Segurança Avançada GitHub habilitado. 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.

    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

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