Habilitar a verificação de código com ferramentas de terceiros
Em vez de executar a verificação de código no GitHub, você pode executar a análise em outro lugar e, em seguida, carregar os resultados. Os alertas para verificação de código que você executa externamente são exibidos da mesma maneira que aqueles executados no GitHub. Você pode carregar arquivos SARIF (Formato de Intercâmbio de Resultados de Análise Estáticos) gerados fora do GitHub ou com GitHub Actions para ver alertas de verificação de código de ferramentas de terceiros em seu repositório.
Nesta unidade, você aprenderá como habilitar a verificação de código com ferramentas de terceiros e como utilizar e carregar arquivos SARIF.
Sobre uploads de arquivo SARIF para verificação de código
O GitHub cria alertas de verificação de código em um repositório utilizando informações de arquivos SARIF. Você pode gerar arquivos SARIF utilizando 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.
Você pode fazer upload dos resultados utilizando a API de verificação de código, a CLI do CodeQL ou GitHub Actions. O melhor método de upload dependerá de como você gerou o arquivo SARIF.
API de Verificação de Código
A API de verificação de código permite que você recupere informações sobre alertas de verificação de código, análises, bancos de dados e configuração de instalação padrão de um repositório. Além disso, você pode atualizar os alertas de verificação de código e a configuração padrão. Você pode utilizar os pontos de extremidade para criar relatórios automatizados para os alertas de verificação de código em uma organização ou carregar os resultados de análise gerados utilizando ferramentas de verificação de código offline.
Você pode acessar a API do GitHub por HTTPS a partir de https://api.github.com. Todos os dados são enviados e recebidos como JSON. A API usa tipos de mídia personalizados para permitir que os consumidores escolham o formato dos dados que desejam receber. Os tipos de mídia são específicos aos recursos, permitindo que eles mudem de forma independente e ofereçam suporte a formatos que outros recursos não.
Há um tipo de mídia personalizado com suporte para a API REST de verificação de código. application/sarif+json
Você pode usar esse tipo de mídia com solicitações GET enviadas ao ponto de extremidade /analyses/{analysis_id}. Quando você usa esse tipo de mídia com essa operação, a resposta inclui um subconjunto dos dados reais que foram carregados para a análise especificada, em vez do resumo da análise retornada quando você usa o tipo de mídia padrão. A resposta também inclui dados adicionais, como as propriedades github/alertNumber e github/alertUrl. Os dados são formatados como SARIF versão 2.1.0.
Veja a seguir um exemplo de comando cURL usando a API para listar os alertas de verificação de código para uma organização:
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
https://api.github.com/orgs/ORG/code-scanning/alerts
Examine os documentos da API REST do GitHub para saber mais sobre o uso da API de verificação de código.
CLI do CodeQL
A CLI do CodeQL é um produto autônomo que você pode usar para analisar o código. Sua principal finalidade é gerar uma representação de banco de dados de uma base de código, um banco de dados CodeQL. Quando o banco de dados estiver pronto, você poderá consultá-lo interativamente ou executar um conjunto de consultas para gerar um conjunto de resultados no formato SARIF e carregar os resultados para GitHub.com. A CLI do CodeQL é gratuita para usar em repositórios públicos mantidos em GitHub.com e está disponível para uso em repositórios privados de propriedade do cliente com uma licença de Segurança Avançada. Baixe o pacote CodeQL de https://github.com/github/codeql-action/releases.
O pacote contém:
- Produto CLI do CodeQL
- Uma versão compatível das consultas e bibliotecas do https://github.com/github/codeql
- Versões pré-compiladas de todas as consultas incluídas no pacote
Você deve sempre utilizar o pacote CodeQL, pois isso garante a compatibilidade e também oferece um desempenho muito melhor do que um download separado da CLI do CodeQL e o check-out das consultas CodeQL.
Análise de verificação de código 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 de GitHub Actions. Um fluxo de trabalho de GitHub Actions é um processo automatizado, composto de um ou mais trabalhos, configurados como um arquivo .yml. Os fluxos de trabalho são armazenados no diretório .github/workflows para seu repositório.
O fluxo de trabalho usa a ação upload-sarif, que faz parte do repositório github/codeql-action. Este fluxo de trabalho inclui parâmetros de entrada que você pode usar para configurar o upload.
O parâmetro de entrada principal é sarif-file, que configura o arquivo ou diretório de arquivos SARIF a serem carregados. O diretório ou caminho do arquivo é relativo à raiz do repositório.
A ação upload-sarif pode ser configurada para ser executada quando o evento push e scheduled ocorrer.
Este exemplo descreve os elementos do arquivo yml da ação upload-sarif:
name: 'Code Scanning : Upload SARIF'
description: 'Upload the analysis results'
author: 'GitHub'
inputs:
sarif_file:
description: |
The SARIF file or directory of SARIF files to be uploaded to GitHub code scanning.
See https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/
uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions
for information on the maximum number of results and maximum file size supported by code scanning.
required: false
default: '../results'
checkout_path:
description: "The path at which the analyzed repository was checked out.
Used to relativize any absolute paths in the uploaded SARIF file."
required: false
default: ${{ github.workspace }}
token:
default: ${{ github.token }}
matrix:
default: ${{ toJson(matrix) }}
category:
description: String used by Code Scanning for matching the analyses
required: false
wait-for-processing:
description: If true, the Action will wait for the uploaded SARIF to be processed before completing.
required: true
default: "false"
runs:
using: 'node12'
main: '../lib/upload-sarif-action.js'
Cada vez que os resultados de uma nova verificação de código são carregados, os resultados são processados e os alertas são adicionados ao repositório. O GitHub usa propriedades no arquivo SARIF para exibir alertas. Por exemplo, para evitar alertas duplicados para o mesmo problema, a verificação de código usa impressões digitais para fazer a correspondência de resultados em várias execuções para que elas apareçam apenas uma vez na execução mais recente da ramificação selecionada. Os arquivos SARIF criados pelo fluxo de trabalho de análise do CodeQL incluem esses dados de impressão digital no campo partialFingerprints. Se você carregar um arquivo SARIF usando a ação upload-sarif e esses dados estiverem ausentes, o GitHub tentará preencher o campo partialFingerprints usando os arquivos de origem.
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.
O upload de SARIF dá suporte a um máximo de 5.000 resultados por upload. Todos os resultados acima desse limite são ignorados. Se uma ferramenta gerar muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados referentes às regras ou às consultas mais importantes.
Cada upload do SARIF dá suporte a um máximo de 10 MB para o arquivo SARIF compactado gzip. Todos os uploads acima desse limite são rejeitados. Se o arquivo SARIF for muito grande porque contém muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados das regras ou consultas mais importantes.
Carregar arquivos SARIF gerados fora do repositório
Você também pode criar um novo fluxo de trabalho que carrega arquivos SARIF depois de confirmá-los em seu repositório. Isso é útil quando o arquivo SARIF é gerado como um artefato fora do seu repositório.
No exemplo a seguir, o fluxo de trabalho é executado sempre que as confirmações são enviadas por push para o 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. Esse fluxo de trabalho carrega o arquivo results.sarif localizado na raiz do repositório. Você também pode modificar esse fluxo de trabalho para carregar 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.
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:
security-events: write
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
Carregar arquivos SARIF gerados como parte de um fluxo de trabalho de CI
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 ainda não tiver um fluxo de trabalho de CI, você poderá criar um usando um fluxo de trabalho inicial no repositório https://github.com/actions/starter-workflows.
Neste exemplo, o fluxo de trabalho é executado sempre que as confirmações são enviadas por push para o 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.
Este exemplo mostra a ferramenta de análise estática ESLint como uma etapa em 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.
```
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:
security-events: write
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
```