security-remediation
Laboratório local para separar proposta de remediação de mudança autorizada.
git clone https://github.com/fernando-moretes/lab-security-remediation.gitcerca de 4 min · áudio gerado ao tocar
O lab-security-remediation é um exercício local, em Node.js e sem credencial de nuvem, que treina uma pergunta só: quando um finding de segurança vira proposta de correção, o que exatamente autoriza essa proposta a virar mudança?
Por que este laboratório existe
A conversa sobre remediação automática costuma começar pela pergunta errada. A pergunta não é "o agente consegue corrigir o bucket público?". Consegue. A pergunta é: quem revisou o quê, contra qual estado do recurso, e o que impede essa revisão de cobrir outra coisa depois?
Na prática, os incidentes que vejo nesse tipo de esteira não vêm da correção em si. Vêm de aprovação reaproveitada para conteúdo que mudou, de recurso que mudou entre a revisão e a aplicação, de execução repetida depois de um timeout e de rollback que ninguém revisou porque "só estava desfazendo".
Este repositório isola esses quatro modos de falha em cenários determinísticos. O finding e o bucket são sintéticos. Não há chamada à AWS, nem a modelo, nem dependência de runtime. Isso é proposital: o objetivo é ler o código inteiro em uma sessão e enxergar cada regra de rejeição, não montar uma integração.
O que ele não é: não é integração com o AWS Security Hub e não é um controle completo de S3. O README diz isso com essas palavras, e eu mantenho a mesma fronteira aqui.
O que vem no repositório
approved, unapproved, tampering, drift, duplicate, rollback e conflict, cada um com resultado esperado e lição explícita.web sobe um servidor só em 127.0.0.1, porta automática, leitura apenas dos arquivos fixos da demo, sem telemetria.propose, initialState, finding) e runScenario importáveis.--lang pt|en, roteiro de oficina de 40 minutos e contribuições aceitas em português ou inglês.Do finding à mudança: onde a revisão pode falhar
O diagrama responde a uma pergunta: em que ponto uma proposta é barrada? Toda mudança passa pela validação de digest e estado; qualquer divergência termina em rejeição, não em correção parcial. O registro é consultado antes de aplicar para impedir execução duplicada (linha tracejada). Simplificação: o rollback revisado segue o mesmo portão e foi omitido.
- Synthetic finding · S3 bucket
- Bounded proposal · before/after + digest
- Explicit review · --approve
- Validate · digest + state
- Rejected · no change
- Simulated change · in memory
- Ledger · memory or SQLite
Instalar e rodar
- 1
Confira o Node.js
Node.js 22 basta para os cenários e o
lab.mjs. Para o registro em SQLite da 0.4.0, use 22.13 ou superior. Nenhumnpm installé necessário: o projeto não tem dependência de runtime. - 2
Escolha entre npm e clone
npx security-remediation-review-lab@0.3.0roda a versão publicada e verificada. A 0.4.0 existe só no GitHub; para ela, clone o repositório. Se você quer ler o código antes de executar, e deveria, clone. - 3
Rode os testes primeiro
node bin/cli.mjs testounpm test. No exercício mínimo,node lab.mjs --self-testdeve reportar sete testes aprovados. - 4
Percorra os cenários
node bin/cli.mjs scenarios all --lang ptroda os sete. Use--jsonpara ver os passos em formato estruturado, por exemplo no cenáriodrift. - 5
Abra a demonstração visual
node bin/cli.mjs webimprime uma URL local. Alterne PT/EN, escolha um cenário e revele cada passo. Os resultados vêm do código da simulação; Ctrl+C encerra e nada é salvo.
git clone https://github.com/fernando-moretes/lab-security-remediation.git
cd lab-security-remediation
npm test
node bin/cli.mjs scenarios all --lang pt
node bin/cli.mjs scenarios drift --lang en --json
node bin/cli.mjs web
# Exercício mínimo / minimal exercise
node lab.mjs --self-test
node lab.mjs # só propõe / proposes only
node lab.mjs --approve # status: simulated-change
# Versão npm verificada / verified npm release
npx security-remediation-review-lab@0.3.0 asffComo funciona por dentro
O fluxo tem seis estágios: finding sintético, proposta limitada, revisão explícita simulada, validação de digest e estado, mudança em memória e registro.
Proposta limitada: propose(finding, initialState()) devolve before, after, o recurso e um digest. Rodar node lab.mjs sem flag para aqui. Proposta não é autorização, e o cenário unapproved termina em rejected justamente para provar isso.
Digest: vincula a revisão ao conteúdo exato da proposta. Se o conteúdo muda depois da aprovação, o cenário tampering rejeita. Um ponto que vale repetir: o digest não autentica o revisor. A aprovação é simulada pelo argumento --approve. Em produção, identidade do aprovador é outro controle.
Estado do recurso: se o bucket mudou entre revisão e aplicação, drift rejeita e exige revisão nova. conflict impede que o mesmo finding autorize uma operação diferente.
Registro: na 0.3.0 é local ao processo, o que basta para duplicate barrar reaplicação na mesma execução. A 0.4.0 leva o registro para SQLite e trata o caso que um registro em memória não cobre: o processo morre no meio, e o resultado fica incerto. Os detalhes estão em DURABILITY.md.
Rollback: rollback termina em reviewed-rollback. Restaurar um estado inseguro é mudança como outra qualquer.
Resultado incerto é o caso perigoso
Depois de um crash, a tentação é reexecutar. Se a primeira tentativa chegou a aplicar, você aplica duas vezes; se a mudança era um rollback, você pode reabrir o bucket. A 0.4.0 bloqueia resultado incerto em vez de adivinhar, e essa é a regra que eu levaria para qualquer esteira real.
Usando como biblioteca ou em oficina
O núcleo é importável. runScenario("drift") devolve o estado sintético, a rejeição esperada e os passos, o que serve para montar o seu próprio cenário ou testar uma variação da regra antes de levá-la para uma esteira de verdade. API.md documenta contratos e limitações; leia antes de depender de qualquer campo.
import { initialState, finding, propose } from "security-remediation-review-lab";
import { runScenario } from "security-remediation-review-lab/scenarios";
console.log(propose(finding, initialState()));
console.log(runScenario("drift"));
Para grupo, WORKSHOP.md traz um roteiro de 40 minutos. O formato que funciona é rodar web, deixar a turma prever o resultado de cada cenário antes de revelar o passo e discutir só os que erraram. Como não há credencial nem rede depois da instalação, o laboratório roda em máquina corporativa travada sem pedir exceção a ninguém.
Resultado de teste em outro ambiente entra por issue, pelo template "Report a result". ROADMAP.md diz o que vem a seguir.
Perguntas frequentes
Preciso de conta AWS?
Não. Não há chamada à AWS nem a modelo. O finding e o bucket são sintéticos.
Por que o npm fica na 0.3.0?
A publicação npm é independente do GitHub. A 0.3.0 é a versão verificada no npm; a 0.4.0, com SQLite, roda a partir do clone.
O servidor web expõe algo na rede?
Ele escuta só em 127.0.0.1, aceita apenas leitura dos arquivos fixos da demonstração e não grava arquivo nem telemetria.
Posso usar isto como controle de produção?
Não. É material de estudo. O digest não autentica revisor e o escopo de S3 não é completo. Use as regras como especificação para o seu controle, não o código como controle.
Para quem é
Use este laboratório quando você estiver desenhando remediação automática ou com agente e precisar alinhar o time sobre o que conta como autorização, ou quando for conduzir uma oficina de 40 minutos sem pedir credencial a ninguém. Se você procura uma integração com o Security Hub ou um controle de S3 pronto, não é isto. O valor está nos sete cenários de rejeição: são as regras que eu exigiria antes de deixar qualquer pipeline aplicar uma correção sozinho.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser