Skip to main content
Glama
remediation-flight-recorder

remediation-flight-recorder

by SweetKenneth

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.

Related MCP server: agent-mcp-workflow-platform

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

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:

{
  "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, 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. 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. SHPBL (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. 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.

Available Tools

6 tools
remediation_approveA

Record explicit human/operator approval for a preflighted transaction.

Inputs: approvedBy (required), transactionId (required).

remediation_preflightB

Create a policy-gated remediation transaction and compute blast radius and rollback plan.

Inputs: policy (required), actions (required), snapshot (required), transactionId (required).

remediation_record_executionB

Bind execution receipts to an approved transaction; this package does not execute remote commands itself.

Inputs: receipts (required), transactionId (required).

remediation_record_rollbackB

Bind rollback receipts to a transaction that entered rollback state.

Inputs: receipts (required), transactionId (required).

remediation_verifyC

Compare a post-remediation exposure snapshot with declared expectations.

Inputs: expectation (required), postSnapshot (required), transactionId (required).

remediation_verify_ledgerB

Verify both payload hashes and the local tamper-evident evidence chain.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct lifecycle stage: preflight, approve, record execution, verify, record rollback, and verify ledger. There is no overlap in purpose or state transition.

    Naming Consistency5/5

    All tools follow a consistent remediation_<verb> pattern, with verbs clearly indicating the action (preflight, approve, record_execution, verify, record_rollback, verify_ledger).

    Tool Count5/5

    Six tools cover the full remediation workflow without redundancy. The count is well-scoped for a focused domain.

    Completeness4/5

    The lifecycle is well covered: create, approve, execute, verify, rollback, and ledger verification. A minor gap is the lack of a tool to query transaction status or history, but the core workflow is complete.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables transparent MCP proxying with a hash-chained effect ledger, classifying agent actions by reversibility, enforcing approval gates, and dry-run previews of sessions.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents and security automation to adjudicate proposed defense mutations against a sealed, canonicalized attack scenario, enforcing reproduction, impact-screening, regression, and proven-improvement gates before promoting at most one candidate. Every verdict, rejected candidate, and rejection reason is sealed into a recomputable SHA-256 Merkle evidence root and hash-linked lineage that can be independently verified without trusting the server.
      6
      MIT