# Remediation Flight Recorder

**One auditable remediation transaction: frozen pre-state, policy gate, execution receipts, verified post-state, rollback on failure.**

Runs security remediation as one auditable transaction: freezes the pre-change exposure snapshot, computes direct and transitive blast radius, gates on policy and explicit approval, binds external execution receipts, verifies the post-change state, and enters rollback when verification fails — all sealed in a SHA-256 evidence chain.

It is an analysis and decision surface, not an actuator: it has no network client, touches no files, spawns no processes, and reads no environment variables.

## Why a practitioner would install this

- **The pre-state is frozen before anything moves.** Nobody can reconstruct 'what it looked like before' from memory after a bad change.
- **Blast radius is computed, not estimated.** Direct and transitive impact comes from the supplied dependency graph before approval is even possible.
- **Denied means denied.** A transaction that fails policy cannot be approved or executed; the state machine refuses out-of-order transitions.
- **Execution is external and receipted.** The server never SSHes, calls an API or changes a device; it binds the receipts your executor returns.
- **Verification failure has a defined next move.** Failed post-state verification enters rollback when a rollback plan exists, and the rollback is receipted too.
- **The whole flight is hash-linked.** Every lifecycle event is chained with SHA-256 over canonical data, so tampering is detectable after the fact.

## Behavioural contract

1. `remediation_preflight` seals the exposure snapshot, computes blast radius, evaluates policy, builds the rollback plan and appends evidence.
2. Denied transactions can never be approved or executed.
3. `remediation_approve` records an explicit named approver; approval is never implied.
4. `remediation_record_execution` binds external executor receipts to an approved transaction.
5. `remediation_verify` compares the declared post-state expectation against the supplied post-change snapshot.
6. Failed verification enters rollback where a plan exists; `remediation_record_rollback` closes the transaction as rolled back or failed.
7. `remediation_verify_ledger` re-verifies payload hashes and the chain independently of session trust.
8. Every out-of-order transition fails closed.

## Prerequisites

- Node.js 20 or newer (`node --version`). Zero runtime dependencies.
- An MCP client that speaks stdio (Claude Code, Claude Desktop, Cursor), or direct library use from TypeScript.
- No API key, account, network access or Tenable product is required.

## Install and run

```bash
git clone https://github.com/SweetKenneth/shpbl-remediation-flight-recorder.git
cd shpbl-remediation-flight-recorder
npm install      # devDependencies only: typescript
npm run build    # compiles to dist/
npm test         # 33 behavioural, boundary and fail-closed tests
npm start        # starts the MCP server on stdio
```

MCP client configuration:

```json
{
  "mcpServers": {
    "remediation-flight-recorder": {
      "command": "node",
      "args": ["/absolute/path/to/shpbl-remediation-flight-recorder/dist/src/mcp-server.js"]
    }
  }
}
```

## Tools exposed

- `remediation_preflight` — Create a policy-gated remediation transaction and compute blast radius and rollback plan.
- `remediation_approve` — Record explicit human/operator approval for a preflighted transaction.
- `remediation_record_execution` — Bind execution receipts to an approved transaction; this package does not execute remote commands itself.
- `remediation_verify` — Compare a post-remediation exposure snapshot with declared expectations.
- `remediation_record_rollback` — Bind rollback receipts to a transaction that entered rollback state.
- `remediation_verify_ledger` — Verify both payload hashes and the local tamper-evident evidence chain.

## What it outputs

Transaction records with sealed pre-state, blast-radius sets, policy decisions, rollback plans, receipt bindings, verification results, and a verifiable SHA-256 evidence chain.

## Verification

Reproduce all of it from a clean clone with `npm run check`:

- Strict TypeScript compile and `--noEmit` typecheck: **PASS**
- Behavioural tests: **33/33 PASS**
- Randomised invariant hammer: **30,000 cases / 180,000 invariant checks PASS**
- Static scan for network, filesystem, process and dynamic-eval surfaces in `src/`: **PASS (0 findings)**
- Worked example runs end to end: **PASS**
- Runtime dependencies: **0**

## Known limitations

- No remote execution or vendor API client is embedded; an operator or adapter supplies execution and rollback receipts.
- Blast radius follows the supplied dependency graph — an incomplete graph produces an incomplete impact model.
- Policy correctness depends on the caller-supplied policy.
- The ledger is tamper-evident within the supplied chain; durable external anchoring is out of scope for this local server.

## Provenance and lineage

This product exists because two things were put together, and both are credited.

**Upstream capability inspiration — [`packetchaos/navi`](https://github.com/packetchaos/navi)**, by Casey Reid (packetchaos), MIT licensed. Its observed behaviour was studied as a capability surface: what a practitioner in that domain actually needs to do. The exact paths and lines that were read are recorded in [`PROVENANCE.json`](./PROVENANCE.json). **No line of upstream implementation code is used in this package.** The upstream licence text is preserved under `THIRD_PARTY_NOTICES/` as provenance; it does not license this implementation.

**SHPBL capability library — [shpbl.com](https://shpbl.com).** SHPBL ([shpbl.com](https://shpbl.com)) is a governed library of reusable software capabilities and a method for composing them: it reads a target repository, identifies what capability it demonstrates, matches that against owned capability records, and writes new software where neither side had it before. The capability parents used here are listed by identifier in `PROVENANCE.json`. **No harvested capability body is embedded in this package.**

**The implementation in this repository was written fresh** from the approved capability contract for this run. The literal composition is 0% upstream code, 0% copied SHPBL capability bodies, 100% new implementation. That is an exact-line and byte-level statement about this source tree, not a legal opinion.

Author and copyright: **Kenneth E. Sweet Jr.**, MIT licensed.

Attribution does not imply endorsement by Casey Reid (packetchaos), Tenable, or any other party.

## Tenable status

Submitted to the Tenable CyberAgents Exchange for review on September 14, 2026 — [pull request #174](https://github.com/tenable/cyberagents-exchange/pull/174).
Submission does not imply review, approval, certification, validation, endorsement or acceptance by Tenable.

## Files

- `src/` — implementation and the stdio MCP server.
- `tests/` — behavioural, fail-closed and MCP integration tests.
- `scripts/` — randomised invariant hammer and the static security scan.
- `examples/worked-example.ts` — an end-to-end run you can execute.
- `SECURITY.md` — threat boundary and forbidden behaviour.
- `PROVENANCE.json` — upstream and SHPBL capability lineage.
- `MANIFEST.json` / `CHECKSUMS.sha256` — released file inventory and hashes.
- `LICENSE` — MIT.

## License

MIT © 2026 Kenneth E. Sweet Jr.. See [`LICENSE`](./LICENSE).