# Chokepoint Finder MCP Server

The engine behind the Chokepoint Finder method: a FastMCP server with ten tools
that turn thousands of findings into **the smallest set of remediation actions that
eliminates the largest share of risk**, with fail-closed pre-flight safety gates,
typed execution plans, and verification that refuses to report clean when it could
not actually look.

Part of the Chokepoint Finder family:
[chokepoint-finder](https://github.com/tarhou/chokepoint-finder) (the agent) ·
[chokepoint-finder-skill](https://github.com/tarhou/chokepoint-finder-skill)
(the portable method) ·
[chokepoint-finder-playbook](https://github.com/tarhou/chokepoint-finder-playbook)
(the cross-vendor chain).

## Quickstart (zero credentials)

```bash
uv sync
uv run python -m chokepoint_finder.demo     # the full loop in the terminal
uv run python -m chokepoint_finder.report   # a board-ready HTML report
uv sync --extra dev && uv run pytest        # 167 tests
```

The demo estate is deterministic (seeded): every run shows the same collapse —
3,734 findings across 783 assets reduced to **7 actions covering 74% of weighted
finding risk (1,700 findings) and severing all 22 known attack paths** — plus a
pre-flight refusal and a wave-by-wave simulated delta. Synthetic data,
reproducible numbers, labelled SIMULATED in every report it produces. The demo
can prove the mechanics but can never authorize a real change-record close.

## The ten tools

`chokepoint_setup` (guided plumbing, never asks for a secret in conversation,
defaults to the offline source so it cannot hang on a captive portal),
`chokepoint_ingest` (demo | tenable | aws | all), `chokepoint_rank` (greedy weighted
max-coverage, marginal ranking), `chokepoint_supply_evidence` (relay EDR or
change-freeze evidence in from another connected MCP server; coverage that could
clear a gate requires explicit human confirmation),
`chokepoint_preflight` (EDR silence, change freezes, blast radius → PROCEED /
REQUIRES_STAGING / HOLD_PARTIAL / HOLD), `chokepoint_payload` (CAB-ready change
request), `chokepoint_plan` (typed execution workflow routed to your MCP fleet,
per-step approvals, canary-first waves, CTI out-of-band handoff; pass
`json_output=true` for the complete canonical v3 manifest),
`chokepoint_mark_executed` (requires a matching plan hash, explicit confirmation,
the exact wave, a targeted-rescan digest, and a recent one-time approval receipt),
`chokepoint_verify` (fail-closed, plan/wave-bound delta; pass `json_output=true` for
the structured proof receipt),
`chokepoint_demo` (the whole wave-aware loop at once).

Five tools update only this process's session state: ingest, rank, evidence relay,
execution accounting, and verification. None holds credentials for, or calls, an
external write API. Planning, payload generation, setup, and the complete demo remain
read-only at the MCP annotation boundary.

```json
{
  "mcpServers": {
    "chokepoint-finder": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/chokepoint-finder-mcp", "chokepoint-mcp"]
    }
  }
}
```

## The safety model

Three properties, each enforced in code and asserted by tests in
`tests/test_failclosed.py` rather than promised in prose.

**Evidence that is missing is not evidence of safety.** Every gate reads typed
`Evidence` carrying its source, collection time and completeness. Evidence that is
unconfigured, failed, partial, truncated or stale reads as `UNKNOWN`, and `UNKNOWN`
produces `HOLD`. Forgetting to wire up a feed can only ever make the agent *less*
willing to act. An empty result from a healthy feed is a different thing —
`ABSENT` — and does clear the gate.

**Evidence composes, the same way execution does.** Chokepoint Finder holds no EDR,
SIEM or ITSM credentials and never will. It sees that telemetry anyway: your agent
queries whatever server provides it — CrowdStrike, SentinelOne, Splunk, Sentinel,
ServiceNow, a CTI platform — and relays the answer through
`chokepoint_supply_evidence` with its provenance intact. The trust rules do not
soften for relayed data: stale, partial or truncated input still reads `UNKNOWN` and
still holds, a future collection timestamp is rejected outright, and every verdict
built on relayed evidence prints `[RELAYED by the operator's agent]` next to its
source. Evidence that travelled through an agent is one link weaker than a direct
pull, and a human reading a HOLD deserves to know which one they are looking at.
The failure mode that matters — an agent queries an EDR, gets an error, and relays
nothing — leaves the channel `UNKNOWN`, so giving up produces a refusal rather than
a silent proceed.
Relayed evidence also carries an exact `covered_asset_ids` set. Free-text scope is
audit context only; if any proposed target is absent from that set, the gate holds.
The confirmation rule is asymmetric: adding detections or freezes inside coverage the
gate already has needs no confirmation because it can only make the decision more
cautious. Establishing, refreshing, replacing, or extending coverage can turn a HOLD
into PROCEED. The first call therefore refuses with a SHA-256 preview digest. The
agent must present the exact evidence and digest to a human, then retry with
`confirm=true`, that digest, a recent confirmer identity/time, and a one-time receipt
ID; it may not self-attest. Changing the payload changes the digest, and replaying the
receipt is refused.

**Honest relay limitation.** The same agent is still the transport. A human who
confirms a relay is attesting to the evidence the agent handed them, not to a direct
read of the EDR, SIEM, or ITSM console. `confirm=true` does not make the relay an
authoritative pull. What it buys is a deliberate control boundary: fabrication that
could widen action now requires active human affirmation instead of happening silently
inside one tool call.

**Verification re-queries the authoritative source and fails closed.**
`chokepoint_verify` runs a fresh collection and grades it: `VERIFIED`, `PARTIAL`,
`NOT_FIXED`, `UNKNOWN` or `ERROR`. Auth failure, timeout, malformed payload,
truncation, partial collection and stale evidence all resolve to `UNKNOWN`/`ERROR`,
and only a non-simulated, final-wave `VERIFIED` result permits closing a change
record. Verification also requires the re-query to match the baseline tenant/account,
credential principal, query and region scope. An empty result set against a
non-empty baseline is treated as a broken query unless the approved action was expected
to retire the entire baseline and the collector independently proves complete, exact
asset coverage. This prevents an outage from masquerading as a fix without making a
genuine all-clear impossible. In demo mode the re-query is a simulation, says so in its
status line, and can never authorize closure.

**Every external mutation requires approval bound to the exact plan.** Steps carry
a structural `mutates_external_state` flag, and the `Step` constructor refuses to
build one that mutates without requiring approval. "External" is drawn deliberately
wide: opening a change ticket, notifying a SOC, and launching a scan all count, not
just touching infrastructure. Approval binds to `ExecutionPlan.plan_hash`; change
the source scope, complete finding IDs, complete targets, exact mutation args, ordered
waves, or held assets and the full SHA-256 hash changes, voiding the earlier approval.
Each wave must be recorded and verified before the next becomes eligible. The server
holds no write credentials and calls no write API — execution
happens through the operator's own MCP servers, as a separate human-invoked phase.
The human Markdown is intentionally bounded and omits bulk identifier arrays; the full
v3 JSON manifest carries exact identifiers, mutation arguments, and ordered steps. For
a three-wave plan, target mutation, targeted rescan, execution receipt, and proof are
physically interleaved for wave 1 before any wave-2 target is touched. Proof binds to
the approved plan hash, exact wave, authoritative scope, and rescan receipt.

Attack-path credit is also evidence-bound. A fix severs a path only when the source
explicitly maps that remediation target to the path; mere overlap between a target
asset and a path node is not counted as disruption.

## How this is tested

167 tests, of which the load-bearing ones are in `tests/test_failclosed.py`:
they are written to fail if a safety claim stops being true, which is the only
reason a safety claim is worth making.

Each control was verified by reverting it and confirming the test catches it —
a regression test that passes against the broken code proves nothing. That
exercise found real gaps twice: an injection test that only checked the
sanitiser rather than the call sites, and an AWS fixture whose STS branch was
never reached.

What the suite covers: every way a re-query can fail (auth, timeout, malformed
payload, truncation, staleness, wrong scope) resolving to UNKNOWN or ERROR and
never to clean; unconfigured, stale or under-scoped evidence holding a gate;
approval bound to a plan hash and refused when the plan changes; wave ordering
that cannot skip ahead; coverage arithmetic that cannot exceed 100%; finding
identity stable under reordering; and prompt-injection payloads driven through
the real MCP tools — not the sanitiser in isolation — asserting no rendered
line can become a model instruction.

The attack-path collector was additionally verified against a live Tenable One
tenant: 2,285 vectors, 24 distinct remediations, with partial coverage and
unbound vectors counted and surfaced rather than silently dropped.

## The ranking, and what is actually guaranteed

The library default (`ranking_mode="risk"`, with both early stops disabled) is greedy
on marginal objective gain under
a cardinality constraint. The objective — covered finding risk plus a bonus per
newly severed attack path — is monotone and submodular, so the classical
(1 − 1/e) ≈ 63% approximation bound applies (Nemhauser, Wolsey & Fisher 1978), and
no polynomial algorithm does better unless P = NP (Feige 1998).

The MCP shortlist intentionally uses an early target-share stop and prints that the
classical guarantee does not apply to that run. More generally, the early stops
(`target_share`, `min_marginal_share`) trade that k-cardinality bound for a shorter
list, and the bound is over the objective, not over any single reported percentage.

`ranking_mode="effort_weighted"` divides marginal gain by `effort^exponent`. It is
useful and it carries **no approximation guarantee** — ratio-greedy under a
cardinality constraint can be arbitrarily bad. It is opt-in and named honestly
rather than sold under a theorem it does not satisfy.

**Coverage is reported as two numbers, never blended.** Finding-risk coverage has
total finding risk as its denominator; attack-path disruption has the path count.
Mixing them is how a tool reports more than 100% of something, so the code keeps
the path bonus out of every human-facing percentage.

## Live sources

Tenable Vulnerability Management via the export APIs
(`uv pip install ".[tenable]"`, `TENABLE_ACCESS_KEY` / `TENABLE_SECRET_KEY`), and
AWS via Security Hub + IAM + EC2 security groups (`uv pip install ".[aws]"`,
standard credentials, read-only, `SecurityAudit` suffices). Copy `.env.example` to
`.env`, or use the environment. Run `chokepoint_setup` first: it reports
READY / TO DO / FAILED per source with the exact next step.

Finding identity is derived from source-natural keys — `(asset uuid, plugin id,
port/protocol)` for Tenable, and the Security Hub finding ID plus every sorted resource
and vulnerability identity for AWS — never from
enumeration order, so a re-query that returns rows in a different order still
compares correctly against the baseline.

## Limitations

These are the things this tool does **not** do. They are listed because a security
tool that hides its edges is worse than one that has them.

- **The demo estate is synthetic.** Its numbers are illustrative, not benchmarks.
- **No bundled EDR/SIEM/ITSM collector, by design.** Evidence comes from the MCP
  servers you already have connected, relayed in through `chokepoint_supply_evidence`
  (see above). This tool holds no credentials for CrowdStrike, Splunk or ServiceNow
  and is not trying to. The consequence to be aware of: if nobody relays a channel,
  it stays `UNKNOWN` and the gates **hold**. Refusing is the safe direction, but an
  unattended run against live data will refuse a lot until the evidence path is
  wired up.
- **Attack paths need Tenable One APA.** The Tenable collector reads APA *vectors*
  -- what Tenable calls attack paths -- paginating to the tenant's reported total,
  and binds each to the plugin APA says severs it. Deliberately not the findings
  endpoint: a finding is a technique that can occur in many paths (one observed
  finding sat on 39 vectors), so counting findings as paths yields a denominator
  that is neither the path count nor a stable quantity. A path is credited only
  when APA names the remediation that breaks it; node overlap earns nothing.
  Without an APA licence -- and on the AWS collector, which has no equivalent
  surface -- zero paths are collected and the reason is recorded, rather than
  reported as "this estate has no attack paths". Unbound vectors, vectors
  referencing assets outside the ingest, and any short read are counted and
  surfaced, so partial coverage is never presented as complete.
- **Collectors are read-only and not load-tested** against very large tenants;
  exports are capped, and hitting the cap marks the collection truncated, which
  blocks verification rather than degrading it silently.
- **Ranking quality tracks metadata quality.** Findings with no fix-sharing key
  cannot converge into a chokepoint. Garbage in, defensible out — every ranking
  cites the evidence behind it, so a wrong answer is visible rather than opaque.
- **HTTP is loopback-only development transport.** It has no authentication or
  session isolation and uses one process-global state, so the CLI refuses non-loopback
  binds. Use stdio for real operator/tenant boundaries and a separate process per
  session.
- **Finding text is untrusted input.** Titles and remediation strings are normalized
  into bounded labels or escaped `<untrusted-scanner-data>` JSON, never interpreted as
  instructions; prompt-injection tests exercise the model-facing rendering boundary.

Authors: Zane K ([@zkilling](https://github.com/zkilling)), Tarek H ([@tarhou](https://github.com/tarhou)), AJ ([@Ethosmos](https://github.com/ethosmos)). MIT license.