Skip to main content
Glama
SweetKenneth

remediation-flight-recorder

by SweetKenneth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
approvedByYes
transactionIdYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the behavioral burden. It discloses that this is a record/write operation requiring an explicit human/operator approver and a preflighted transaction, but it does not state whether transaction state changes, whether approvals are idempotent, or what validation occurs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with an active verb and no filler. It is front-loaded with the core action and remains economical while communicating the essential purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the purpose is clear, but the description omits workflow ordering, side effects, and any output or response behavior. Since there is no output schema and no annotations, those gaps leave the agent to infer important operational details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It loosely maps approvedBy to a human/operator and transactionId to the preflighted transaction, but it adds no format, source, or relationship details beyond what the bare parameter names already suggest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Record') with a clear object ('explicit human/operator approval') and ties it to a precondition ('preflighted transaction'). This clearly differentiates the tool from execution, rollback, and verification siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: the word 'preflighted' suggests this happens after remediation_preflight and before execution. However, there is no explicit 'use this when...' guidance or mention of when not to use it versus siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediation_preflightB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
policyYes
actionsYes
snapshotYes
transactionIdYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions creating a transaction and computing blast radius/rollback plan, but does not disclose side effects (e.g., persistence, reversibility, mutation of existing state), permission requirements, or what happens on failure. This is a significant gap for a create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It efficiently conveys the core action and outputs. However, it is too short given the tool's complexity, leaving out critical details that would make it more useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four required nested parameters, no output schema, and no annotations, yet the description explains none of the workflow context, parameter relationships, or expected return. An agent cannot confidently call this correctly without more guidance, especially given the sibling workflow that this tool clearly initiates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It only says 'policy-gated' which hints at policy's role, but does not explain what transactionId, snapshot, actions, or policy mean or how they relate. The description adds minimal semantic value beyond field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Create'), a clear resource ('policy-gated remediation transaction'), and the additional outputs ('blast radius and rollback plan'). This clearly distinguishes it from sibling tools like remediation_approve, remediation_verify, and remediation_record_rollback, which focus on later workflow stages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a preflight step by its focus on creation and computation of impact/rollback, which naturally precedes approval or execution. However, it does not explicitly state when to use it versus siblings or mention sequencing. Still, the verb and output make the role obvious enough to route an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediation_record_executionB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
receiptsYes
transactionIdYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose one important behavioral trait: the tool does not execute remote commands itself. But it does not explain side effects, whether receipts are appended or replaced, persistence guarantees, or any authorization prerequisites beyond the word 'approved.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with two clauses. Both earn their place: the first states the core purpose and the second clarifies a critical limitation. There is no filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given two required parameters, no output schema, and no annotations, the description is too thin. It gives a general sense of purpose and one exclusion but does not cover workflow context, receipt format, return behavior, or failure conditions, so an agent would likely need additional information to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It provides high-level mapping: transactionId refers to an approved transaction and receipts are execution receipts. However, it does not describe the expected shape of the receipts array, whether receipts can be empty, or any constraints on transactionId, leaving the agent with insufficient parameter-level guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('bind') and a clear resource ('execution receipts to an approved transaction'), and it adds a distinguishing negative statement: 'this package does not execute remote commands itself.' This differentiates it from any execution-like sibling, though it does not fully position it against all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used after approval when receipts exist, and it explicitly excludes remote command execution as a use case. However, it does not name alternatives or state when to prefer this tool over related actions like remediation_verify or remediation_record_rollback.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediation_record_rollbackB

Bind rollback receipts to a transaction that entered rollback state.

ParametersJSON Schema
NameRequiredDescriptionDefault
receiptsYes
transactionIdYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of behavioral disclosure, but it only describes the binding action. It does not disclose that this is a mutating operation, what persists, whether it is idempotent, or what happens if the transaction is not in rollback state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler; the action and object are front-loaded. It is concise without becoming a pure tautology, though it could add useful context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the description is minimally viable: it states the action and a key precondition. However, with no annotations and no output schema, it omits failure behavior, expected response, and any additional state requirements, making it incomplete for fully autonomous use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description maps the two parameters to domain concepts: transactionId is the transaction and receipts are the rollback receipts. This adds meaning beyond the bare schema, but with 0% schema coverage it still leaves the receipts element format and any constraints unspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation—binding rollback receipts to a transaction—and includes the precondition that the transaction is in rollback state. It does not explicitly differentiate itself from siblings like remediation_record_execution, but the rollback-specific subject makes the intended action reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'transaction that entered rollback state' implies when this tool should be used, giving some contextual guidance. However, there is no explicit comparison with sibling tools such as remediation_preflight or remediation_verify, and no when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediation_verifyC

Compare a post-remediation exposure snapshot with declared expectations.

ParametersJSON Schema
NameRequiredDescriptionDefault
expectationYes
postSnapshotYes
transactionIdYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full behavioral burden. It only says the tool compares two inputs; it does not disclose whether this is a read-only check, whether it records anything, what it returns, or what side effects may occur.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word contributes to stating the operation and its main inputs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has three required parameters, including two unstructured nested objects, no output schema, and no annotations. A one-sentence description is not enough for an agent to know what shapes to provide, what a successful verification looks like, or how this step fits into the remediation workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It alludes to postSnapshot and expectation but does not explain their required structure, relationships, or the role of transactionId. The nested objects remain completely unspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Compare') and a clear resource ('a post-remediation exposure snapshot' vs 'declared expectations'), which conveys the core purpose. It does not explicitly differentiate from the sibling tools, though the phrase 'exposure snapshot' loosely separates it from remediation_verify_ledger.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus remediation_preflight, remediation_approve, or the other siblings. The word 'post-remediation' only implies that it runs after remediation, but no workflow context or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

remediation_verify_ledgerB

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses that the tool verifies two specific things, which implies a read-only check, but it does not mention side effects, failure behavior, permissions, or what happens if verification fails. This is minimal but not completely absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no wasted words, front-loading the action and the two key resources. It is appropriately sized for the tool's apparent simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, a good description should indicate what the verification result looks like or how an agent should act on it, but this is missing. The ambiguity with remediation_verify is also unaddressed, leaving an agent uncertain about return values and workflow context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially complete and the description does not need to add parameter semantics. The baseline of 4 applies because no parameter documentation is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('verify') and two clear resources (payload hashes and the local tamper-evident evidence chain), so an agent knows what the tool acts on. However, it does not explicitly distinguish this from its sibling remediation_verify, leaving some ambiguity about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the closely named sibling remediation_verify, nor any workflow context or prerequisites. The description implies a verification task but does not state when it is the appropriate choice or when it is not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 6 tool updatesv1.0.0
    • First observedremediation_approve
    • First observedremediation_preflight
    • First observedremediation_record_execution
    • First observedremediation_record_rollback
    • First observedremediation_verify
    • First observedremediation_verify_ledger
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • airlock

    Rohit-ATS
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables agents to open production change dossiers, attach proof certificates, and request human approval through a secure, unforgeable gate—ensuring no irreversible change can proceed until it has been verified against a sandboxed shadow copy.
    150 npm
    1
    MIT

  • sagaz-mcp

    BabyKuramaDev
    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