Como carregar os resultados da análise do CodeQL no GitHub

Use a CodeQL CLI para carregar os resultados da análise do CodeQL no GitHub Enterprise Cloud.

Quem pode usar esse recurso?

Usuários com com acesso para gravação

O CodeQL está disponível para os seguintes tipos de repositórios:

Neste artigo

Sobre a saída SARIF

O GitHub cria alertas de code scanning em um repositório usando informações de arquivos de Formato Intercâmbio de Resultados de Análise Estática (SARIF). O SARIF foi projetado para representar a saída de uma ampla gama de ferramentas de análise estática, e há muitos recursos na especificação SARIF que são considerados "opcionais". Os resultados devem usar o SARIF versão 2.1.0. Para saber mais, confira Suporte SARIF para a varredura de código.

Depois de analisar um banco de dados do CodeQL usando o CodeQL CLI, você terá um arquivo SARIF que contém os resultados. Para saber mais, confira Como analisar o código com as consultas CodeQL. Em seguida, você poderá usar a CodeQL CLI para carregar os resultados no GitHub.

Se você usar um método diferente da CodeQL CLI para gerar os resultados, poderá usar outros métodos de upload. Para saber mais, confira Fazer o upload de arquivo SARIF para o GitHub.

Note

Há suporte para o upload de dados SARIF a serem exibidos como resultados da code scanning no GitHub Enterprise Cloud nos repositórios pertencentes à organização com o GitHub Advanced Security habilitado e em repositórios públicos no GitHub.com. Para obter mais informações, confira "Gerenciando as configurações de segurança e análise do repositório".

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

Antes de carregar seus resultados no GitHub Enterprise Cloud, você precisará gerar um personal access token.

  • Personal access token (classic) exige os alertas "Code scanning" Acesso de leitura e gravação para os repositórios necessários.
  • Fine-grained personal access token requer acesso security_events para "repo".

Para saber mais, confira Gerenciar seus tokens de acesso pessoal.

Se você instalou a CodeQL CLI em um sistema de CI de terceiros para criar resultados a serem exibidos no GitHub como alertas da verificação de código, use um GitHub App ou um personal access token para carregar os resultados no GitHub Enterprise Cloud. Para saber mais, confira Usando a varredura de código com seu sistema de CI existente.

Fazendo upload de resultados para GitHub Enterprise Cloud

Você pode verificar se as propriedades SARIF têm um tamanho compatível com o upload e se o arquivo é compatível com a verificação de código. Para obter mais informações, confira "Suporte SARIF para a varredura de código".

Antes de carregar os resultados no GitHub Enterprise Cloud, é preciso determinar a melhor maneira de transmitir o GitHub App ou o personal access token que você criou na seção anterior para a CodeQL CLI. Recomendamos que você examine as diretrizes do sistema da CI sobre o uso seguro de um repositório secreto. O CodeQL CLI é compatível com:

  • Interface com um repositório de segredos usando a opção --github-auth-stdin (recomendado).
  • Salvar o segredo na variável de ambiente GITHUB_TOKEN e executar a CLI sem incluir a opção --github-auth-stdin.
  • Para fins de teste, você pode passar a opção de linha de comando --github-auth-stdin e fornecer um token temporário por meio de entrada padrão.

Quando você tiver decidido o método mais seguro e confiável para a configuração, execute codeql github upload-results em cada arquivo de resultados 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>
OpçãoObrigatórioUso
--repositoryEspecifique o PROPRIETÁRIO/NOME do repositório no qual os dados serão carregados. O proprietário precisa ser uma organização dentro de uma empresa com uma licença do GitHub Advanced Security, e o GitHub Advanced Security precisa estar habilitado para o repositório, a menos que o repositório seja público. Para saber mais, confira Gerenciando as configurações de segurança e análise do repositório.
--refEspecifique o nome da ref do qual 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 o commit principal de uma solicitação de pull, use refs/pull/NUMBER/head ou para o commit de mesclagem de uma solicitação de pull gerado pelo GitHub, use refs/pull/NUMBER/merge.
--commitEspecifique o SHA completo do commit que você analisou.
--sarifEspecifique o arquivo SARIF a ser carregado.
--github-auth-stdinPasse a CLI pelo GitHub App ou o personal access token já criado para autenticação com a API REST de GitHub do repositório de segredo por meio da 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.

Para saber mais, confira github upload-results.

Note

Se você analisou mais de um banco de dados do CodeQL para um só commit, deve ter especificado uma categoria SARIF para cada conjunto de resultados gerados por esse comando. Ao fazer o upload dos resultados para GitHub Enterprise Cloud, code scanning usa essa categoria para armazenar os resultados para cada linguagem separadamente. Se você se esquecer de fazer isso, cada upload substituirá os resultados anteriores. Para saber mais, confira Como analisar o código com as consultas CodeQL.

Exemplo básico do upload de resultados para GitHub Enterprise Cloud

Este exemplo carrega os resultados do arquivo SARIF temp/example-repo-js.sarif no repositório my-org/example-repo. Ele informa à API da code scanning de que os resultados referem-se ao commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 no branch main. O exemplo assume que o GitHub App ou o personal access token criado para autenticação com a API REST do GitHub usa a variável de ambiente GITHUB_TOKEN.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

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 code scanning em GitHub Enterprise Cloud pouco tempo depois. É possível ver alertas diretamente no pull request ou na guia Security para branches, dependendo do código que você fizer checkout. Para saber mais, confira Alertas de varredura de código de triagem em pull requests e Avaliar alertas de verificação de código para seu repositório.

Carregar informações de diagnóstico em GitHub Enterprise Cloud se a análise falhar

Quando CodeQL CLI termina de analisar um banco de dados com êxito, ele coleta informações de diagnóstico, como cobertura de arquivo, avisos e erros, e o inclui no arquivo SARIF com os resultados. Quando você carrega o arquivo SARIF no GitHub, as informações de diagnóstico são exibidas na página de status da ferramenta da code scanning do repositório, a fim de facilitar a visualização de como CodeQL está funcionando e depurar eventuais problemas. Para saber mais, confira Sobre a página de status da ferramenta para a verificação de código.

No entanto, em caso de falha em codeql database analyze por algum motivo, não haverá nenhum arquivo SARIF a ser carregado no GitHub e nenhuma informação de diagnóstico a ser mostrada na página de status da ferramenta da code scanning do repositório. Isso dificulta que os usuários solucionem problemas de análise, a menos que tenham acesso aos arquivos de log em seu sistema de CI.

Recomendamos que você configure seu fluxo de trabalho de CI para exportar e carregar informações de diagnóstico para GitHub Enterprise Cloud quando uma análise falhar. Você pode fazer isso usando os comandos simples a seguir para exportar informações de diagnóstico e carregá-los em GitHub.

Exportar informações de diagnóstico se a análise falhar

Você pode criar um arquivo SARIF para a análise com falha usando database export-diagnostics, por exemplo:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

Esse arquivo SARIF conterá informações de diagnóstico para a análise com falha, incluindo quaisquer informações de cobertura de arquivo, avisos e erros gerados durante a análise.

Carregar informações de diagnóstico se a análise falhar

Você pode disponibilizar essas informações de diagnóstico na página de status da ferramenta carregando o arquivo SARIF no GitHub Enterprise Cloud usando github upload-results, por exemplo:

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

Isso é o mesmo que o processo para carregar arquivos SARIF de análises bem-sucedidas.