Carregando resultados da análise do CodeQL para GitHub

Depois de analisar um banco de dados CodeQL usando o CodeQL CLI, você terá um arquivo SARIF que contém os resultados. Em seguida, você pode usar o CodeQL CLI para carregar os resultados para GitHub.

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

Gerando um token para autenticação com GitHub

Antes de fazer upload de seus resultados para GitHub, primeiro você precisará gerar um personal access token. Confira Gerenciar seus tokens de acesso pessoal.

        **
        Personal access token (classic)
        ** requer "Code scanning alertas" **Acesso de leitura e gravação** para os repositórios necessários.

        **
        Fine-grained personal access token
        ** requer acesso ao repositório **security_events**.

Se você tiver instalado o CodeQL CLI em um sistema de CI de terceiros, também poderá usar um GitHub App para fazer o upload dos resultados para GitHub. Confira Usando a varredura de código com seu sistema de CI existente.

Carregando resultados para GitHub

Verifique se as propriedades SARIF têm o tamanho com suporte para upload e se o arquivo é compatível com a verificação de código. Para saber mais, confira Suporte SARIF para a varredura de código.
Determine a melhor maneira de passar o GitHub App ou personal access token você criou na seção anterior para o CodeQL CLI. Recomendamos que você examine as diretrizes do sistema da CI sobre o uso seguro de um repositório secreto. O CodeQL CLI suporta:
- 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-url=<URL> \
    --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> --github-url=<URL> \

Opção	Obrigatório	Usage
`--repository`		Especifique o PROPRIETÁRIO/NOME do repositório no qual os dados serão carregados. O proprietário deve ser uma organização com GitHub Code Security habilitado para o repositório. Para saber mais, confira Gerenciando as configurações de segurança e análise do repositório.
`--ref`		Especifique o nome da `ref` do qual você fez check-out e analisou para que os resultados possam corresponder ao código correto. Para um uso de branch: `refs/heads/BRANCH-NAME`, para a confirmação principal de um uso `refs/pull/NUMBER/head`de solicitação de pull ou para a GitHubconfirmação de mesclagem gerada de um uso `refs/pull/NUMBER/merge`de solicitação de pull.
`--commit`		Especifique o SHA completo do commit que você analisou.
`--sarif`		Especifique o arquivo SARIF a ser carregado.
`--github-url`		Especifique a URL para sua instância do GitHub Enterprise Server.
`--github-auth-stdin`		Passe a CLI, a GitHub App ou a personal access token criada para autenticação com a API REST de GitHub a partir do seu armazenamento de segredos, 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.

Para saber mais, confira github upload-results (carregar resultados no GitHub).

Observação

Se você analisou mais de um CodeQL banco de dados para uma única confirmação, deverá ter especificado uma categoria SARIF para cada conjunto de resultados gerados por esse comando. Quando você carrega os resultados, GitHubcode scanning usa essa categoria para armazenar os resultados de cada idioma 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 de carregamento de resultados para GitHub

Este exemplo carrega os resultados do arquivo SARIF temp/example-repo-js.sarif no repositório my-org/example-repo. Ele informa para a code scanning API que os resultados são para o commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 no ramo main. O exemplo pressupõe que o GitHub App ou personal access token criado para autenticação com a GitHub API REST use 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 --github-url=https://HOSTNAME \

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ê deve ser capaz de explorar os code scanning alertas em GitHub logo em seguida. Você pode ver alertas diretamente no pull request ou na aba Security para branches, dependendo do código que você baixou.

Carregando informações de diagnóstico para GitHub se a análise falhar

Ao CodeQL CLI concluir a análise de um banco de dados com êxito, ele coleta informações de diagnóstico, como cobertura de arquivo, avisos e erros, e inclui-o no arquivo SARIF com os resultados. Quando você carrega o arquivo SARIF para GitHub, as informações de diagnóstico são exibidas em code scanningpágina de status da ferramenta, permitindo visualizar facilmente o desempenho de CodeQL e depurar quaisquer problemas. Para saber mais, confira Usar a página de status da ferramenta para verificação de código.

No entanto, se codeql database analyze falhar por algum motivo, não haverá nenhum arquivo SARIF para carregar em GitHub e nenhuma informação de diagnóstico para exibir no code scanningpágina de status da ferramenta relacionado ao 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 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 para 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 Diagnóstico de exportação de banco de dados, por exemplo:

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarifv2.1.0 \
    --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 no página de status da ferramenta carregando o arquivo SARIF em GitHub usando github upload-results (carregar resultados no GitHub), por exemplo:

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

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

Quem pode usar esse recurso?

Neste artigo