Pular para conteúdo

AUR-562: tutoriais executáveis do gate, exceções, auditoria/SARIF e reaproveitamento

O que entrega

  • Quatro tutoriais em docs/tutorials/ (gate.md, excecoes.md, auditoria-sarif.md, reaproveitamento.md), indexados em docs/tutorials/README.md e linkados da página inicial (docs/index.md); o nav vem do hook do site (aba Tutoriais).
  • Quatro demonstrações em demo/tutoriais/<tutorial>/ no framework do AUR-561 (run.sh com uma fase por caso, expected/, out/ da execução real).
  • Uma extensão do framework, em arquivos novos (o tutorial.sh não foi editado): demo/tutoriais/_lib/github-falso.py e _lib/pr.sh. O primeiro é um GitHub falso e local (127.0.0.1) que só serve o que review --pr consulta e registra o que o produto publica; o segundo expõe tut_pr_servidor, aurum_pr (container em --network host, só para alcançar o loopback do host) e tut_pr_log. Serve para provar o texto publicado do status aurumcode/policy-gate; não é um runner nem o GitHub.
  • tests/acceptance/AUR-562.sh: all, AC-001..AC-004, AC-002-MUT-001; seletor desconhecido sai 64.

Decisões

  • O SAST usa o Semgrep real da imagem com uma regra local (sem rede); a falha do SAST é simulada por um semgrep falso na frente do PATH (gate/fakebin/), declarado no run.sh e no tutorial.
  • Conclusões do script são frases RESULTADO: afirmadas por expect_rc; o que não tem caso executado leva a marca "não demonstrado aqui" no texto.

Não demonstrado aqui (declarado)

  • Artefato de análise vencido (analysis_data_stale) e digest divergente: exigem um servidor de releases; só analysis_data_unavailable (sem rede) é executado.
  • SBOM na auditoria: exige Trivy e rede.
  • Upload ao Code Scanning (upload-sarif) e a proteção de branch: configuração do GitHub; a demo confere o workflow do chamador contra o review.yml real.
  • Compartilhamento da mesma chave de veredito entre --base e --pr (ver achado 4).
  • --pr roda contra o GitHub falso: prova o que o produto publica, não o comportamento do GitHub.

Achados sobre o produto (o que o tutorial mediu)

  1. A origem na linha de gate não é uniforme. A auditoria e o SARIF trazem o origin tipado (skills, analysis, sast), mas a linha impressa diz origem analysis só para a análise; para o SAST diz origem policy (de onde veio a configuração) e para a skill não diz nada. docs/configuration.md promete a origem "nas linhas de gate". Caso gate/fontes.
  2. Falha ao gravar a auditoria não reprova. --auditoria num diretório inexistente avisa em stderr e a saída segue 0 numa revisão limpa; um pipeline de compliance precisa conferir o arquivo. Caso auditoria-sarif/falha-caminho-invalido.
  3. A mensagem do gate é redigida de forma diferente do relatório. A linha de gate mostra [REDACTED] secret or credential assigned inline onde o relatório mostra Hardcoded secret or credential assigned inline.
  4. --base e --pr gravaram chaves de veredito diferentes neste experimento (mesmo SHA, política, modelo e identidade do repositório; diff do GitHub falso). Não é possível afirmar que seja defeito do produto: o diff do servidor falso pode diferir do real. Caso reaproveitamento/veredito-base-e-pr.
  5. O cache por arquivo atravessa uma mudança de política (a resposta do modelo não mudou); só o veredito é por política. Documentado nos tutoriais.
  6. Observado em experimento exploratório, não versionado: sem provedor, com --seguranca e inconclusive: warn, um achado [error] do passe de segurança (security/hardcoded-secret) apareceu no relatório e a saída foi 0 com fail_on: [high]. Precisa de um caso próprio antes de ser afirmado.

Execução real

Execução real, em container, com a imagem aurum-tutoriais:local construída do Dockerfile do worktree, sem rede (exceto o loopback do GitHub falso no caso gate/status-pr e em reaproveitamento/veredito-base-e-pr) e com o provedor falso. Comandos: bash demo/tutoriais/<t>/run.sh all (os quatro terminaram com exit 0) e run.sh --check. A saída completa de cada caso é demo/tutoriais/<t>/out/<caso>.log.

gate

  • gate/fail-on-severidade: exit_code(s) 0,3,3,3; warning abaixo do limiar high nao reprova | warning no limiar medium reprova (exit 3) | error reprova com fail_on error | high e error sao o mesmo limiar: o achado error reprova
  • gate/inconclusivo-provedor: exit_code(s) 1,0,1; block: provedor ausente reprova, motivo quality_skipped | warn: provedor ausente alerta e sai 0, nunca aprovado | --exigir-qualidade reprova mesmo com warn (provider_failure)
  • gate/inconclusivo-cobertura: exit_code(s) 1,0; block: cobertura parcial reprova | warn: cobertura parcial alerta e sai 0
  • gate/inconclusivo-sast: exit_code(s) 1,0,1,3; block: SAST que falhou nunca vira 'sem achados' (sast_execution_error) | warn: SAST falho alerta e sai 0 | block: saida invalida do SAST e inconclusiva (sast_invalid_output) | com o Semgrep real o SAST conclui e o achado reprova (nao e inconclusivo)
  • gate/inconclusivo-analysis-data: exit_code(s) 1; block: artefato de analise indisponivel reprova (analysis_data_unavailable)
  • gate/fontes: exit_code(s) 3,3,3,3; sources todas: o gate reprova | sources skills: o gate reprova | sources analysis: o gate reprova | sources sast: o gate reprova
  • gate/status-pr: exit_code(s) 0,3,1; o ultimo caso (inconclusivo em block) sai 1 e publica status failure
  • gate/repo-afrouxa: exit_code(s) 0,1; o proprio repositorio aceita cobertura parcial como alerta | o repositorio nao consegue afrouxar o inconclusive da politica
  • gate/falha-fonte-invalida: exit_code(s) 1; gate.sources com valor desconhecido falha antes de qualquer chamada ao modelo
  • gate/achado-deterministico (AUR-569): exit_code(s) 3,3,0; warn: o achado [error] do passe de seguranca reprova (exit 3), origem security | block: o achado reprova com exit 3, nao so o inconclusivo | warn sem achado deterministico continua so avisando (exit 0)
  • gate/modelo-pondera (AUR-579): exit_code(s) 3,3,0; a politica conta o achado contestado (exit 3) e o parecer propoe a excecao, sem aplica-la | confirmado: o achado conta e nenhuma excecao e proposta | sem politica, a contestacao rebaixa o achado (gate.triage: model) e o gate aprova

excecoes

  • excecoes/excecao-valida: exit_code(s) 3,0; sem excecao, o warning cruza o limiar medium | a excecao valida tira o achado do gate
  • excecoes/excecao-vencida: exit_code(s) 3; a excecao vencida nao vale: o achado volta a reprovar
  • excecoes/nao-casa: exit_code(s) 3,3,3; excecao para outro caminho nao casa | excecao de outro repositorio nao casa | sem identidade confirmada, nenhuma excecao casa (falha fechado)
  • excecoes/excecao-do-repo-ignorada: exit_code(s) 0,3; sem politica, o gate e a excecao do proprio repositorio valem | sob politica, a excecao do repositorio nao vale
  • excecoes/falha-sem-dono: exit_code(s) 1; excecao sem dono invalida a politica inteira (falha fechado)

auditoria-sarif

  • auditoria-sarif/auditoria-reprovado: exit_code(s) 3; a revisao reprova e a auditoria e escrita mesmo assim
  • auditoria-sarif/sarif-campos: exit_code(s) 3; o SARIF e escrito com o gate reprovado
  • auditoria-sarif/sarif-inconclusivo: exit_code(s) 1; inconclusivo em block reprova
  • auditoria-sarif/canario-de-redacao: exit_code(s) 3; a revisao reprova | o canario nao vazou para saida, auditoria nem SARIF
  • auditoria-sarif/upload-workflow: exit_code(s) n/a; conferência
  • auditoria-sarif/falha-caminho-invalido: exit_code(s) 0; ACHADO: a auditoria nao foi gravada (veja o aviso) e o exit continua 0; confira o arquivo no job

reaproveitamento

  • reaproveitamento/reuso-por-arquivo: exit_code(s) 3,3; o achado reprova | o mesmo veredito, sem reenviar o arquivo ao modelo
  • reaproveitamento/veredito-base-e-pr: exit_code(s) 3,3; o --pr chega ao mesmo veredito
  • reaproveitamento/modelo-mudou: exit_code(s) 3,0; modelo A reprova | com outro modelo nada e reaproveitado: a resposta nova vale
  • reaproveitamento/politica-mudou: exit_code(s) 0,3; politica high: o warning passa | politica medium: o mesmo warning reprova; a politica nova gera outra entrada de veredito (a resposta por arquivo segue reaproveitada)
  • reaproveitamento/cache-degradado: exit_code(s) 3,3; primeira execucao reprova e grava o cache | cache corrompido: revisao nova, o achado continua reprovando
  • reaproveitamento/falha-sem-cache: exit_code(s) 3,1; sem cache a revisao funciona, mas o veredito nao e compartilhado | inconclusivo em block reprova
CHECK OK dos quatro tutoriais (run.sh --check)