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 obter mais informações, confira "Como gerenciar alertas da code scanning do seu repositório".

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 obter mais informações, confira "Suporte do SARIF �  code scanning".

Você pode carregar os resultados usando o GitHub Actions, a API code scanning, o CodeQL runner, ou a 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.
• A CodeQL CLI para executar a code scanning no sistema de CI. Você pode usar a CLI para carregar resultados no GitHub (para obter mais informações, confira "Como instalar a CodeQL CLI no sistema de CI").
• Por padrão, para executar a code scanning no seu sistema de CI, o CodeQL runner carrega automaticamente os resultados no GitHub após a conclusão. Se você bloquear o upload automático, quando estiver pronto para carregar os resultados, use o comando upload (para obter mais informações, confira "Como executar o CodeQL runner no seu sistema de CI").
• Uma ferramenta que gera resultados como um artefato fora do repositório. Você pode usar a API da code scanning para carregar o arquivo (para obter mais informações, confira "Carregar uma análise como dados SARIF").

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 obter mais informações, confira "Aprenda a usar o GitHub Actions".

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, 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 obter mais informações sobre os eventos do 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 obter mais informações sobre como evitar alertas duplicados, confira "Sobre o suporte do SARIF para verificação 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, confira "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 editar um arquivo de fluxo de trabalho, confira "Saiba como usar o GitHub Actions".

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, confira "Objeto runAutomationDetails".

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@v2
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v1
        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 o guia de início rápido do "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 obter mais informações, 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 obter mais informações sobre como criar um arquivo de fluxo de trabalho, confira "Introdução ao 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@v2
      - 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@v1
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

Leitura adicional

• "Sintaxe de fluxo de trabalho do GitHub Actions"
• "Como ver o histórico do fluxo de trabalho"
• "Sobre a code scanning do CodeQL no seu sistema de CI"
• "Carregar uma análise como dados SARIF"