Exportação em SARIF e integração com o GitHub code scanning

Exporte uma auditoria concluída do vetkit pelo endpoint de relatório com format=sarif e depois faça o upload do arquivo SARIF 2.1.0 pelo seu workflow do GitHub Actions. Antes do upload, confira se a auditoria corresponde ao repositório e ao commit analisados. Baixar o relatório não publica alertas no GitHub por si só; o upload é uma etapa separada que você configura.

1. Confira os pré-requisitos

• Tenha em mãos o ID da organização, o ID da auditoria e uma chave de API do vetkit com reports:read. Um workflow automatizado que também inicia e consulta auditorias precisa de audits:write e audits:read.
• Confirme o repositório e o SHA do commit da auditoria. No CI, solicite ou reutilize uma auditoria do commit exato do workflow e espere que ela termine antes de exportar.
• Inspecione o relatório JSON em busca de resultados parciais e do escopo real do scan. Um documento SARIF válido ainda pode representar uma análise incompleta.

O GitHub oferece code scanning para repositórios públicos e para repositórios de organizações elegíveis com o GitHub Code Security ativado. Confira a elegibilidade do seu repositório e o acesso de escrita na documentação de upload de SARIF do GitHub.

2. Exporte a auditoria

Defina as variáveis abaixo no seu shell local ou no ambiente de CI. VETKIT_API_URL é a origem da API do vetkit, sem /v1. Guarde a chave em um gerenciador de segredos ou em um secret do CI, não no arquivo de workflow, no repositório ou em um script de shell. Este comando exige curl e jq:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

O endpoint retorna application/sarif+json e um nome de arquivo de anexo baseado no commit auditado. O comando salva o arquivo propositalmente como vetkit.sarif para a etapa de upload. A verificação com jq é uma checagem básica de formato, não uma validação completa do schema nem uma confirmação de que o scan foi completo. Trate o relatório baixado como informação do repositório e controle o acesso a ele.

3. Faça o upload pelo seu workflow

Em um workflow do repositório escaneado, faça o checkout do código correspondente, obtenha a auditoria concluída e execute o comando de download acima. Mantenha a VETKIT_API_KEY em um secret do Actions. O trecho a seguir mostra as permissões e a etapa final de upload; não é um workflow de scan autônomo. Adicione o download entre o checkout e o upload:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

A action de upload do GitHub usa sarif_file para o caminho do relatório e category para distinguir as análises. Reutilizar uma combinação de ferramenta/categoria no mesmo commit pode substituir resultados anteriores; use categorias distintas para análises separadas. As permissões e as versões das actions acima seguem o exemplo do GitHub.

O exemplo de integração de repositório do vetkit mantém o upload de SARIF opcional, atrás de VETKIT_UPLOAD_SARIF=true. O workflow de scan completo dele solicita uma auditoria do commit exato e rejeita resultados com falha, parciais ou sem nota antes do upload opcional. Essa verificação de conclusão não impõe um limite de severidade dos achados nem de nota: defina a sua política de lançamento separadamente. Os checks do GitHub App e o upload de SARIF são caminhos de integração separados.

4. Interprete os resultados importados

O vetkit exporta uma única execução SARIF com vetkit como driver. Os resultados incluem IDs de regra, locais nos arquivos quando disponíveis, texto de correção e fingerprints do vetkit. As versões dos analisadores são registradas como extensões, e a procedência de repositório/commit é incluída. O mapeamento de severidade usa os níveis do SARIF junto com as propriedades de severidade do vetkit; esses mapeamentos numéricos não são notas CVSS calculadas de forma independente.

Achados no nível do repositório usam um local sintético (repository), então podem não apontar para uma linha real do código-fonte. Achados suprimidos permanecem na exportação com metadados de supressão do SARIF. Não presuma que o número de resultados exportados é igual ao número de alertas ativos exibidos pelo GitHub. Guarde o relatório original do vetkit para ter o contexto de cobertura, de nota e os detalhes de revisão.

Solução de problemas

• O download falha: confira a origem da API, os IDs da organização e da auditoria, a validade da chave e o escopo reports:read. Não imprima a chave ao depurar.
• Locais errados no código-fonte: compare o commit da auditoria com o commit e o checkout do workflow. Não faça upload de um relatório antigo como evidência de uma revisão mais nova.
• O upload é rejeitado: confira a elegibilidade no GitHub, as permissões do workflow e a saída de erro da action de upload. O GitHub aplica as próprias propriedades de SARIF suportadas e os próprios limites de tamanho.
• Nenhum alerta visível: inspecione os resultados do arquivo, os metadados de supressão, a análise selecionada e a cobertura da auditoria original. Um transporte bem-sucedido não prova um scan limpo.

Fontes e limitações

Verificado em 1º de novembro de 2026 com base no controller/service de relatórios do vetkit, no serializador de SARIF e no exemplo de integração do repositório com o GitHub Actions. Veja a referência da API e os requisitos de upload do GitHub para os dois lados da integração. A elegibilidade no GitHub e o comportamento das actions podem mudar. A exportação em SARIF transfere achados existentes; ela não executa o CodeQL, não adiciona verificações à auditoria original nem garante que todos os detalhes do relatório do vetkit apareçam na interface do GitHub.