Depois de analisar um banco de dados do CodeQL usando o CodeQL CLI, você terá um arquivo SARIF que contém os resultados. Em seguida, você poderá usar o CodeQL CLI para fazer upload dos 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 AUTOTITLE.
Gerando um token para autenticação com GitHub
Antes de fazer upload dos seus resultados no GitHub, você precisará gerar um personal access token. Confira AUTOTITLE.
- Personal access token (classic) exige os alertas "Code scanning" Acesso de leitura e gravação aos repositórios necessários.
- Fine-grained personal access token requer acesso security_events para "repo".
Se você tiver instalado o CodeQL CLI em um sistema de CI de terceiros, também poderá usar um GitHub App para carregar resultados em GitHub. Confira AUTOTITLE.
Como fazer upload dos resultados para o GitHub
-
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 saber mais, confira Suporte SARIF para a varredura de código.
-
Determine a melhor forma de passar o GitHub App ou personal access token que 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 é compatível com:
- Interface com um repositório de segredos usando a opção (recomendado).
- Salvar o segredo na variável de ambiente e executar a CLI sem incluir a opção .
- Para fins de teste, você pode passar a opção de linha de comando 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 em cada arquivo de resultados SARIF e inclua , a menos que o token esteja disponível na variável de ambiente .
# 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 precisa ser uma organização com o GitHub Code Security habilitado para o repositório. Para saber mais, confira AUTOTITLE. | |
--ref | Especifique o nome da do qual você fez check-out e analisou para que os resultados possam corresponder ao código correto. Para um branch, use , para o commit principal de uma solicitação de pull, use ou para o commit de mesclagem de uma solicitação de pull gerado pelo GitHub, use . | |
--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 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 definida com esse token. |
Para saber mais, confira AUTOTITLE.
Observação
Se você analisar mais de um banco de dados do CodeQL para um só commit, precisará especificar uma categoria SARIF para cada conjunto de resultados gerado por este comando. Ao fazer o upload dos resultados para GitHub, 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 AUTOTITLE.
Exemplo básico do upload de resultados para o GitHub
Este exemplo carrega os resultados do arquivo SARIF no repositório . Ele informa à API da code scanning de que os resultados referem-se ao commit no branch . 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 .
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ê poderá explorar os alertas de code scanning em GitHub pouco tempo depois. Você pode ver alertas diretamente na solicitação de pull ou na guia Segurança para ramificações, dependendo do código que você fez check-out.
Como fazer upload de informações de diagnóstico para o GitHub 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 AUTOTITLE.
No entanto, em caso de falha em 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 fazer upload de informações de diagnóstico para o 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 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 AUTOTITLE, 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 na página de status da ferramenta fazendo upload do arquivo SARIF para o GitHub usando AUTOTITLE, 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.