Skip to main content
Glama
SweetKenneth

shpbl-scan-coverage-autopilot

by SweetKenneth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Scan Coverage Autopilot

A capacity-safe next scan schedule that names what it could not fit, and why.

Finds stale and never-scanned coverage against risk-tier maximum ages, predicts each target's duration from real scan history, and emits a capacity-bounded, risk-weighted next schedule that explicitly reports every overdue target it could not fit and the reason.

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

  • Coverage gaps are named, not averaged. Stale targets are measured against risk-tier maximum ages, and never-scanned targets are called out separately.

  • Durations come from your history. Prediction uses the median of the exact scanner/target history first, then target-wide history, then your explicit estimate — in that order.

  • The plan fits the window. Assignments respect scanner capability, scanner capacity and the planning horizon; nothing is scheduled twice.

  • Unschedulable work is reported, not hidden. Every overdue target that did not fit comes back with a reason, which is the number a coverage conversation actually needs.

  • Plans are comparable. Each plan is sealed with SHA-256 and can be diffed against another for coverage and load deltas.

Related MCP server: mcp-security-server

Behavioural contract

  1. now must be supplied explicitly; wall-clock time is never silently inferred.

  2. Determine staleness from risk-tier maximum ages and identify never-scanned targets.

  3. Predict duration from the median exact scanner/target history, then target-wide history, then an explicit estimate.

  4. Rank overdue work by deterministic risk and staleness priority.

  5. Assign only capability-compatible work, never exceeding scanner capacity or the planning horizon.

  6. Schedule each target at most once and report every unscheduled overdue target with a reason.

  7. Seal the proposed plan with SHA-256 and support coverage/load comparison between plans.

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-scan-coverage-autopilot.git
cd shpbl-scan-coverage-autopilot
npm install      # devDependencies only: typescript
npm run build    # compiles to dist/
npm test         # 25 behavioural, boundary and fail-closed tests
npm start        # starts the MCP server on stdio

MCP client configuration:

{
  "mcpServers": {
    "shpbl-scan-coverage-autopilot": {
      "command": "node",
      "args": ["/absolute/path/to/shpbl-scan-coverage-autopilot/dist/src/mcp-server.js"]
    }
  }
}

Tools exposed

  • scan_analyze_coverage — Find risk-weighted scan blind spots using explicit time

  • scan_plan — Generate a deterministic capacity-safe risk-weighted scan plan

  • scan_compare — Compare two sealed scan plans after verifying both seals

What it outputs

Staleness and never-scanned inventories, a capacity-bounded schedule with per-assignment predicted duration and prediction source, an explicit unschedulable list with reasons, a sealed plan digest, and plan-to-plan deltas.

Verification

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

  • Strict TypeScript compile and --noEmit typecheck: PASS

  • Behavioural tests: 25/25 PASS

  • Randomised invariant hammer: 30,000 cases / 120,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 scanner API client is embedded; the plan is a proposal for your scheduler or operator to execute.

  • Duration prediction is only as good as the supplied scan history; sparse history falls back to your estimate.

  • Risk tiers and maximum ages are caller policy, not a recommendation from this package.

  • The autopilot does not launch, stop or modify scans.

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

3 tools
scan_analyze_coverageC

Find risk-weighted scan blind spots using explicit time

ParametersJSON Schema
NameRequiredDescriptionDefault
nowYes
policyYes
targetsYes

TDQS

C2.7/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 full burden of behavioral disclosure. It only says 'find ... blind spots' and does not state whether the operation is read-only, what side effects exist, or what happens with the inputs.

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 an eight-word single sentence with no fluff. However, the phrase 'explicit time' is cryptic enough that clarity is slightly reduced.

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?

For a tool with three required structured parameters, nested objects, no output schema, no annotations, and two sibling tools, a single high-level sentence is insufficient for an agent to construct valid inputs or interpret the result.

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%, and the description does not meaningfully explain the three required parameters. 'Explicit time' vaguely hints at 'now' and 'risk-weighted' hints at the role of 'policy', but targets, policy, and now are otherwise left undefined.

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 concrete goal: find risk-weighted scan blind spots using explicit time. This clearly distinguishes the tool from siblings like scan_plan and scan_compare in intent, though the meaning of 'explicit time' is somewhat ambiguous.

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 scan_plan or scan_compare, and no mention of prerequisites or exclusions. The intended usage is only implied by the tool name and the single action phrase.

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

scan_compareB

Compare two sealed scan plans after verifying both seals

ParametersJSON Schema
NameRequiredDescriptionDefault
currentYes
proposedYes

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 carries the full burden of behavioral disclosure. It mentions seal verification but does not state whether the tool is read-only, what happens if seals are invalid, what the output looks like, or whether there are side effects. Behavioral transparency is minimal.

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 eight-word sentence with no filler. The main action is front-loaded and the precondition follows naturally, making it appropriately concise and well-structured.

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?

For a tool with two nested object parameters, no output schema, and no annotations, the description is too thin. An agent cannot determine what the comparison returns, how to construct the current and proposed objects, what seal verification entails, or how this tool differs from scan_analyze_coverage in practical 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?

Schema coverage is 0% and the parameters are bare object types. The description adds meaning by mapping 'current' and 'proposed' to the two sealed scan plans and implying both seals must be verified. However, it does not explain the internal structure of these objects or how the comparison is performed.

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, 'compare', with a clear resource, 'two sealed scan plans', and adds a precondition, 'after verifying both seals'. This distinguishes it from siblings like scan_plan (creating plans) and scan_analyze_coverage (analyzing coverage), though it does not explicitly name them.

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 precondition 'after verifying both seals' provides some guidance on when the tool should be invoked, and the name implies a comparison use case. However, there is no explicit when-to-use/when-not-to-use guidance, and sibling alternatives are not mentioned.

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

scan_planC

Generate a deterministic capacity-safe risk-weighted scan plan

ParametersJSON Schema
NameRequiredDescriptionDefault
nowYes
policyYes
historyYes
targetsYes
scannersYes

TDQS

C2.3/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 of behavioral disclosure. The description mentions 'deterministic' and 'capacity-safe', which are useful behavioral traits, but it does not explain what 'capacity-safe' means, whether the plan is persisted, what side effects occur, or what the output looks like. For a tool with no annotations, this is a significant gap.

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 sentence with no wasted words. It front-loads the key qualifiers ('deterministic', 'capacity-safe', 'risk-weighted') before the resource. However, it is arguably too terse given the lack of parameter documentation and behavioral context.

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 5 required parameters, nested objects, no output schema, and no annotations. The description provides only a high-level purpose. An agent would not know what inputs to provide, what the output format is, or what 'capacity-safe' and 'risk-weighted' mean in practice. The sibling tools are not referenced, so the agent cannot disambiguate. This is incomplete for a tool of this complexity.

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

Parameters1/5

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

Schema description coverage is 0%, and the description provides no parameter-level detail. The schema lists five required parameters (targets, scanners, history, policy, now) with generic types (array, object, string), but the description does not explain what any of them mean or how they relate to the plan generation. With zero coverage and no compensation in the description, the agent cannot infer parameter semantics.

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

Purpose3/5

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

The description states a specific verb ('generate') and resource ('scan plan'), and adds meaningful qualifiers: 'deterministic', 'capacity-safe', 'risk-weighted'. This distinguishes it from generic 'create plan' tools, but it does not explicitly differentiate it from the sibling tools scan_analyze_coverage and scan_compare. The qualifiers hint at what the plan optimizes for, but the core purpose is somewhat abstract without more context.

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?

No guidance is provided on when to use this tool versus the siblings. The description does not mention alternatives, exclusions, or conditions. The qualifiers 'deterministic', 'capacity-safe', and 'risk-weighted' imply a planning use case, but the agent is left to infer when this is appropriate compared to scan_analyze_coverage or scan_compare.

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. 3 tool updatesv1.0.0
    • First observedscan_analyze_coverage
    • First observedscan_compare
    • First observedscan_plan
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

B3.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool maps to a distinct stage of the scan-coverage workflow: analyzing blind spots, generating a plan, and comparing sealed plans. There is no meaningful overlap that would cause an agent to pick the wrong tool.

Naming Consistency4/5

All tools share a clear scan_ prefix and use snake_case action-oriented names. scan_plan is slightly less explicit than the verb_noun pattern of the others, but the convention is still easy to predict.

Tool Count5/5

Three tools is at the lower end of the ideal range but is well-scoped for the server's narrow autopilot purpose. Each tool earns its place and no tool feels redundant.

Completeness4/5

The set covers the core cycle of analyzing, generating, and comparing scan plans. There are minor gaps, such as no explicit plan listing or management operation, but the primary workflow is supported without dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • pentest-mcp-server

    Dr-yato
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables authorized penetration testing and security assessments with CVE monitoring, vulnerability scanning, and reporting features.
    MIT

  • mcp-security-server

    Balckers
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides AI agents with standardized security scanning capabilities for authorized assessments, including host detection, port scanning, service fingerprinting, web vulnerability scanning, CVE verification, and report generation, all with unified JSON output and strict compliance controls.
    -

  • dsh-vulnerability-remediation

    dongsheng123132
    A
    license
    Not graded
    quality
    C
    maintenance
    Offers proof-only tools to inspect and verify remediation closure receipts, deterministically confirming asset coverage, fixed artifact deployment, rescanning, deadline compliance, and zero-residual closure without executing scans or touching live systems.
    MIT

  • TARA

    hbapuram
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables users to trace regulatory rule changes to affected parties and required actions through deterministic safety gates, returning dated action plans and hash-linked evidence records. Supports 12 MCP tools over stdio or streamable HTTP for source comparison, obligation decomposition, scope assessment, planning, and evidence validation across multiple domain packs.
    MIT