Fazer o upload de arquivo SARIF para o GitHub

Se você usar uma ferramenta de análise de terceiros ou um sistema de CI/CD para verificar o código em busca de vulnerabilidades, poderá gerar o arquivo SARIF e carregá-lo para GitHub. O melhor método de upload depende de como você gera o arquivo SARIF.

Por exemplo, se você usar:

        GitHub Actions para executar a ação CodeQL , não há nenhuma ação adicional necessária. A CodeQL ação carrega o arquivo SARIF automaticamente quando ele conclui a análise.

        GitHub Actions para executar uma ferramenta de análise compatível com SARIF, você pode atualizar o fluxo de trabalho para incluir uma etapa final que carrega os resultados. Consulte [Carregar uma code scanning análise com GitHub Actions](#uploading-a-code-scanning-analysis-with-github-actions).

Para CodeQL CLI executar code scanning no seu sistema de CI, você pode usar a CLI para carregar os resultados para GitHub. Consulte Usando a varredura de código com seu sistema de CI existente.
Uma ferramenta que gera resultados como artefato fora do seu repositório; você pode usar a API code scanning para fazer o upload do arquivo. Consulte Pontos de extremidade da API REST para varredura de código.

Por padrão, code scanning espera um arquivo de resultados SARIF por análise para um repositório. Se quiser carregar mais de um conjunto de resultados para um commit em um repositório, você deverá identificar cada conjunto de resultados como um conjunto exclusivo.

Observação

Para repositórios privados e internos, code scanning está disponível quando GitHub Code Security as funcionalidades estão habilitadas para o repositório. Se você vir o erro GitHub Code Security or GitHub Advanced Security must be enabled for this repository to use code scanning, verifique se GitHub Code Security está habilitado. Para obter mais informações, consulte Gerenciando as configurações de segurança e análise do repositório.

Carregando uma code scanning análise com GitHub Actions

Para usar GitHub Actions para carregar um arquivo SARIF de terceiros em um repositório, você precisará de um fluxo de trabalho. Para obter mais informações, consulte Escrevendo fluxos de trabalho.

O fluxo de trabalho precisará usar a ação upload-sarif, que faz parte do repositório github/codeql-action. Ele tem parâmetros de entrada que você pode usar para configurar o upload. Os principais parâmetros de entrada que você vai usar são:

        `sarif_file`, que configura o arquivo ou o diretório de arquivos SARIF a serem enviados. O diretório ou caminho do arquivo é relativo à raiz do repositório.

        `category` (opcional), que atribui uma categoria para os resultados no arquivo SARIF. Isso permite que você analise o mesmo commit de várias maneiras e revise os resultados usando as code scanning exibições em GitHub. Por exemplo, você pode analisar usando várias ferramentas, e nos monorepos, você pode analisar diferentes porções do repositório com base no subconjunto de arquivos alterados.

Para obter mais informações, confira a Ação upload-sarif.

A ação upload-sarif pode ser configurada para ser executada quando os eventos push e scheduled ocorrerem. Para saber mais sobre eventos GitHub Actions, confira Eventos que disparam fluxos de trabalho.

Se o arquivo SARIF não incluir partialFingerprints, a ação upload-sarif calculará o campo partialFingerprints para você e tentará evitar alertas duplicados. GitHub só pode criar partialFingerprints quando o repositório contém o arquivo SARIF e o código-fonte usado na análise estática. Para obter mais informações sobre como evitar alertas duplicados, confira Suporte SARIF para a varredura de código.

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.

Exemplo de fluxo de trabalho para arquivos SARIF gerados fora de um repositório

Você pode criar um novo fluxo de trabalho que faz o upload de arquivos SARIF após fazer o commit deles no seu repositório. Isso é útil quando o arquivo SARIF é gerado como um artefato fora do seu repositório.

Este exemplo de fluxo de trabalho é executado sempre que os commits são carregados no repositório. A ação usa a propriedade partialFingerprints para determinar se as alterações ocorreram. Além de ser executado quando as confirmações são enviadas por push, o fluxo de trabalho é agendado para ser executado uma vez por semana. Para obter mais informações, consulte Eventos que disparam fluxos de trabalho.

Esse fluxo de trabalho carrega o arquivo results.sarif localizado na raiz do repositório. Para obter mais informações sobre como criar um arquivo de fluxo de trabalho, confira Escrevendo fluxos de trabalho.

Como alternativa, você pode modificar este fluxo de trabalho para fazer upload de um diretório de arquivos SARIF. Por exemplo, você pode posicionar todos os arquivos SARIF em um diretório na raiz do seu repositório chamado sarif-output e definir o parâmetro de entrada sarif_file da ação como sarif-output. Observe que, se você carregar um diretório, cada arquivo SARIF precisará incluir uma runAutomationDetails.id exclusiva para definir a categoria para os resultados. Para obter mais informações, consulte Suporte SARIF para a varredura de código.

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

Exemplo de fluxo de trabalho que executa a ferramenta de análise ESLint

Se você gerar o arquivo SARIF de terceiros como parte de um fluxo de trabalho de CI (integração contínua), poderá adicionar a ação upload-sarif como uma etapa depois de executar os testes de CI. Se você ainda não tiver um fluxo de trabalho de CI, poderá criar um usando um GitHub Actions modelo. Para obter mais informações, confira Guia Rápido do GitHub Actions.

O fluxo de trabalho mostra um exemplo de execução da ferramenta de análise estática ESLint como uma etapa de um fluxo de trabalho. A etapa Run ESLint executa a ferramenta ESLint e gera o arquivo results.sarif. O fluxo de trabalho em seguida carrega o arquivo results.sarif para GitHub usando a ação upload-sarif. Para obter mais informações sobre como criar um arquivo de fluxo de trabalho, confira Noções básicas sobre GitHub Actions.

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Carregar mais de um arquivo SARIF para um commit

Por padrão, code scanning espera um arquivo de resultados SARIF por análise para um repositório. Consequentemente, quando se faz o upload de um segundo arquivo SARIF para um compromisso, ele é tratado como uma substituição do conjunto original de dados. Uma sugestão é carregar dois arquivos SARIF diferentes para uma análise quando, por exemplo, sua ferramenta de análise gera um arquivo SARIF diferente para cada linguagem analisada ou para cada conjunto de regras usado. Se quiser carregar mais de um conjunto de resultados para um commit em um repositório, você deverá identificar cada conjunto de resultados como um conjunto exclusivo.

Ao fazer o upload de vários arquivos SARIF para um commit, você deverá indicar uma "categoria" para cada análise. A forma de especificar uma categoria varia de acordo com o método de análise:

Ao usar o CodeQL CLI diretamente, passe o argumento --sarif-category para o comando codeql database analyze ao gerar arquivos SARIF. Para obter mais informações, consulte Sobre a CLI do CodeQL.
Usando GitHub Actions com codeql-action/analyze, a categoria é definida automaticamente a partir do nome do fluxo de trabalho e de qualquer variável de matriz (normalmente, language). Substitua isso especificando uma entrada category para a ação, que é útil quando você analisa diferentes seções de um monorrepositório em um fluxo de trabalho individual.
Usando GitHub Actions para carregar resultados de outras ferramentas de análise estática, você deve especificar uma category entrada se carregar mais de um arquivo de resultados para a mesma ferramenta em um fluxo de trabalho. Para obter mais informações, consulte Fazer o upload de arquivo SARIF para o GitHub.
Se não estiver usando nenhuma dessas abordagens, especifique uma runAutomationDetails.id exclusiva em cada arquivo SARIF para upload. Para obter mais informações sobre esta propriedade, consulte runAutomationDetails do objeto.

Se você fizer o upload de um segundo arquivo SARIF para um commit com a mesma categoria e a partir da mesma ferramenta, os resultados anteriores serão substituídos. No entanto, se você tentar carregar vários arquivos SARIF para a mesma ferramenta e categoria em uma única GitHub Actions execução de fluxo de trabalho, a configuração incorreta será detectada e a execução falhará.

Leitura adicional

        [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)

        [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)

        [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)

        [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

        [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)