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

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 obter mais informações, 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 obter mais informações, 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 obter mais informações, confira "Fazer o upload de arquivo SARIF para o GitHub".

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

Antes de carregar seus resultados no GitHub Enterprise Server, você precisará gerar um personal access token com a permissão de gravação security_events. Para obter mais informações, 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 Server. Para obter mais informações, confira "Usando a varredura de código com seu sistema de CI existente".

Fazendo upload de resultados para GitHub Enterprise Server

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 Server, é 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-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	Uso
--repository		Especifique 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. Para obter mais informações, 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 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.
--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		Passe 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 obter mais informações, confira "github upload-results".

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

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 --github-url=https://github.example.com \
    

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 Server pouco tempo depois. Você pode ver os alertas diretamente na solicitação de pull ou na guia Segurança dos branches, dependendo do código que você verificou. Para saber mais, confira "Alertas de varredura de código de triagem em pull requests" e "Gerenciamento de alertas de varredura de código para seu repositório".