Fazer o upload de arquivo SARIF para o GitHub

Sobre os uploads de arquivos SARIF para code scanning

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). Os arquivos SARIF podem ser enviados para um repositório usando a API ou GitHub Actions. Para saber mais, confira Usando a varredura de código com seu sistema de CI existente.

Você pode gerar arquivos SARIF usando muitas ferramentas de teste de segurança de análise estática, incluindo CodeQL. Os resultados devem usar o SARIF versão 2.1.0. Para saber mais, confira Suporte SARIF para a varredura de código.

Você pode enviar os resultados usando a API de GitHub Actions, a code scanning ou CodeQL CLI. O melhor método de upload dependerá de como você gera o arquivo SARIF. Por exemplo, se você usar:

• GitHub Actions para executar a ação CodeQL, não haverá nenhuma ação adicional necessária. A ação CodeQL faz o upload do arquivo SARIF automaticamente quando ele conclui a análise.
• O arquivo SARIF pode ser gerado a partir de uma ferramenta de análise compatível com o SARIF, que você executa no mesmo fluxo de trabalho de GitHub Actions usado para fazer o upload do arquivo.
• O CodeQL CLI para executar code scanning em seu sistema CI, você pode usar a CLI para carregar resultados para GitHub (para saber mais informações, confira Usando a varredura de código com seu sistema de CI existente).
• Uma ferramenta que gera resultados como um artefato fora de seu repositório, você pode usar a API code scanning para carregar o arquivo (para saber mais, confira Pontos de extremidade da API REST para varredura de código).

Fazer o upload uma análise de code scanning com GitHub Actions

Para fazer com que GitHub Actions faça um upload de um arquivo SARIF de terceiros para um repositório, você precisará de um fluxo de trabalho. Para saber mais, confira 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 carregados. 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 reveja os resultados usando as visualizações de code scanning em GitHub. Por exemplo, você pode analisar usando várias ferramentas, e nos monorrepositórios, você pode analisar diferentes porções do repositório com base no subconjunto de arquivos alterados.

Para obter mais informações, consulte a upload-sarifação.

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. O GitHub só poderá criar partialFingerprints quando o repositório contiver o arquivo SARIF e o código-fonte usado na análise estática. Para saber mais sobre como evitar alertas duplicados, confira Suporte SARIF para a varredura de código.

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".

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 saber mais, confira Eventos que disparam fluxos de trabalho.

Esse fluxo de trabalho carrega o arquivo results.sarif localizado na raiz do repositório. Para saber mais 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 saber mais, confira 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@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        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, você poderá criar um usando um modelo de GitHub Actions. Para obter mais informações, confira Início rápido para GitHub Actions.

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 saber mais, confira Eventos que disparam fluxos de trabalho.

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. Em seguida, o fluxo de trabalho carrega o arquivo results.sarif no GitHub usando a ação upload-sarif. Para saber mais sobre como criar um arquivo de fluxo de trabalho, confira Entendendo o 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@v4
      - 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@v3
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Leitura adicional

• Solução de problemas de uploads SARIF
• Sintaxe de fluxo de trabalho para o GitHub Actions
• Visualizar o histórico de execução do fluxo de trabalho
• Usando a varredura de código com seu sistema de CI existente
• Pontos de extremidade da API REST para varredura de código