# security-remediation

Laboratório local para separar proposta de remediação de mudança autorizada.

- URL: https://fernando.moretes.com/open-source/security-remediation

- Markdown: https://fernando.moretes.com/open-source/security-remediation/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/lab-security-remediation

- Homepage: https://fernando.moretes.com/community/2026

- Language: JavaScript

- Topics: aws, education, hands-on-lab, javascript, open-source, security

- Stars: 1

- Forks: 0

- Updated: 2026-10-20T17:24:38Z

---

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

- **Sete cenários:** `approved`, `unapproved`, `tampering`, `drift`, `duplicate`, `rollback` e `conflict`, cada um com resultado esperado e lição explícita.
- **Demonstração visual:** `web` sobe um servidor só em `127.0.0.1`, porta automática, leitura apenas dos arquivos fixos da demo, sem telemetria.
- **Revisão ASFF offline (0.3.0):** finding S3.8 sintético, quatro campos S3 preservados e proposta não executável, com testes de entrada negativa.
- **Durabilidade (0.4.0, só no GitHub):** registro persistente em SQLite, recuperação por recibos e bloqueio de resultado incerto, testados com interrupção de processo e concorrência. Exige Node.js 22.13+.
- **API JavaScript:** núcleo determinístico (`propose`, `initialState`, `finding`) e `runScenario` importáveis.
- **Bilíngue e MIT:** CLI com `--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.

### Input

- Synthetic finding S3 bucket (external)
- Bounded proposal before/after + digest (compute)

### Review gate

- Explicit review --approve (user)
- Validate digest + state (security)
- Rejected no change (security)

### Effect

- Simulated change in memory (compute)
- Ledger memory or SQLite (data)

### Fluxos

- finding -> proposal: gera
- proposal -> review: submete
- review -> validate: aprova
- validate -> reject: digest ou estado divergente
- validate -> change: confere
- ledger -> validate: já aplicado?
- change -> ledger: registra

## 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. Nenhum `npm 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.0` roda 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 test` ou `npm test`. No exercício mínimo, `node lab.mjs --self-test` deve reportar sete testes aprovados.

4. **Percorra os cenários**: `node bin/cli.mjs scenarios all --lang pt` roda os sete. Use `--json` para ver os passos em formato estruturado, por exemplo no cenário `drift`.

5. **Abra a demonstração visual**: `node bin/cli.mjs web` imprime 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.

_Início rápido a partir do clone_

```bash
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 asff
```

## Como 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.

```js
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.

## Referências

- [GitHub: fernando-moretes/lab-security-remediation](https://github.com/fernando-moretes/lab-security-remediation)
- [Community 2026 (homepage)](https://fernando.moretes.com/community/2026)
- [npm: security-remediation-review-lab](https://www.npmjs.com/package/security-remediation-review-lab)

## Links

- [GitHub repository](https://github.com/fernando-moretes/lab-security-remediation)
- [Homepage](https://fernando.moretes.com/community/2026)
