Fissuredocumentation v5.3.1
On this page

Fissure MCP bridge

An optional Model Context Protocol bridge that lets an MCP host (Claude Code) drive Fissure's local control API as an agent: check liveness, send a single request, run scans (poll-based), and read findings, with no point-and-click.

The bridge is a thin, stateless stdio process. All the real logic stays in the C engine behind the control API (see ../docs/11_CONTROL_API.md); the bridge only translates MCP tool calls into HTTP requests and returns the JSON.

Contents

  • fissure_control_client.py - a pure standard-library HTTP client for the control API (no third-party dependency). Importable and testable on its own, and usable directly from any Python script.
  • fissure_mcp_bridge.py - the FastMCP stdio server. One MCP tool per route.

Where to find it

You do not need a source checkout: every package ships this directory and the Claude skills next to the binary. With the .deb the bridge is /opt/fissure/bridge/ and the skills are under /opt/fissure/skills/; the Windows installer puts them in bridge\ and skills\ under the install directory; the AppImage carries them as usr/bin/bridge/ and usr/bin/skills/, which you copy out once with --appimage-extract. The exact commands are in step 1b of docs/13_MCP_AND_SKILL_SETUP.md. Below, <bridge-dir> is whichever of these directories you use (or <repo>/bridge in a checkout).

Prerequisites

  1. Enable the control API in Fissure: Settings -> Control API -> "Enable local control API" (or run fissure serve --api-key <token>). Copy the port and the token shown there.

  2. Install the MCP Python SDK into a virtualenv (the client itself needs no third-party package; only fissure_mcp_bridge.py needs the SDK). A venv keeps it isolated and gives you a concrete interpreter path to point the MCP config at:

    python3 -m venv ~/.venvs/fissure-mcp
    ~/.venvs/fissure-mcp/bin/pip install "mcp>=1.27,<2"

    v1.x is the stable line (tested with 1.28 and 1.30). If a stable v2 is out when you set this up and you prefer it, adjust the import (from mcp.server import ...) per its migration guide and pin accordingly. Either way, pin a bounded version.

Registering with Claude Code

Add the bridge as a stdio MCP server, passing the URL and token as environment variables (never hardcode the token). Point the command after -- at the venv's python (the interpreter that has mcp), not a bare python:

claude mcp add fissure-control \
  --env SUITE_API_URL=http://127.0.0.1:8777 \
  --env SUITE_API_TOKEN=<token-from-app-settings> \
  -- ~/.venvs/fissure-mcp/bin/python <bridge-dir>/fissure_mcp_bridge.py

(With the .deb: /opt/fissure/bridge/fissure_mcp_bridge.py.)

(Verify the exact flags with claude mcp add --help.) After this, the host sees the tools below. Rotating the token in the app means updating the env value in the MCP config; no code change.

Other clients (Claude Desktop, ChatGPT)

  • Claude Desktop launches the same stdio bridge from an mcpServers entry in its claude_desktop_config.json (command = the venv python, args = this script, env = SUITE_API_URL / SUITE_API_TOKEN).
  • ChatGPT needs a remote MCP server, not a stdio subprocess. Run the bridge with a network transport (FISSURE_MCP_TRANSPORT=streamable-http or =sse, optional FISSURE_MCP_HOST / FISSURE_MCP_PORT, default 127.0.0.1:8779) behind a trusted tunnel, and point the connector at the endpoint path: /mcp for streamable-HTTP, /sse for SSE (the bare host answers 404). The default is 8779, one above the control-driven proxy's default 8778 (POST /api/proxy/start without a port), so the two never collide. Alternatively, drive the HTTP control API directly from a Custom GPT Action.

Full step-by-step for all three clients (and installing the skills / methodology) is in docs/13_MCP_AND_SKILL_SETUP.md.

Verifying the bridge

With the control API running (fissure serve --api-key <token> or the Settings toggle), a quick end-to-end check before registering:

# the control API answers (no token needed for status)
curl -s http://127.0.0.1:8777/api/status

# the bridge's client drives the API end to end (health, findings, a request,
# an async scan). SUITE_TARGET_URL must be a SECOND control instance's status
# endpoint: the test asserts GET 200 and POST 404 on it and then scans it, which a
# control /api/status satisfies exactly, and it is a different accept loop than the
# one under test (the single accept loop cannot serve a request nested inside its
# own call). Start a throwaway second instance on another port and point at it:
fissure serve --port 8780 --insecure >/dev/null 2>&1 &   # tokenless, so a POST to its /api/status gives 404 not 401
SUITE_API_URL=http://127.0.0.1:8777 SUITE_API_TOKEN=<token> \
SUITE_TARGET_URL=http://127.0.0.1:8780/api/status \
  ~/.venvs/fissure-mcp/bin/python ../tests/mcp_bridge_smoke.py   # prints SMOKE OK

The authoritative way to run it is make tests (the C test test_mcp_bridge stands up both instances with the right target and runs this script); the recipe above is the manual equivalent.

The smoke test is a source-tree check: tests/mcp_bridge_smoke.py is not shipped in the installed layouts (the .deb, the AppImage and the Windows installer ship only the two .py files and this README under bridge/). From an installed package, verify with the client's health() call instead, run from the installed bridge directory (for example /opt/fissure/bridge):

SUITE_API_URL=http://127.0.0.1:8777 SUITE_API_TOKEN=<token> \
  ~/.venvs/fissure-mcp/bin/python -c \
  "import fissure_control_client as a; print(a.health())"
# {'status': 'ok', 'name': 'fissure', 'version': '<x.y.z>'}

or, once the bridge is registered, ask the MCP host to call the health tool.

Driving a whole engagement

The tools below are building blocks; to run a full bug-bounty engagement (scope, authenticated scan, manual confirmation, report) rather than a single call:

  • From Claude Code, use the shipped fissure_bug_bounty skill (../.claude/skills/fissure_bug_bounty/ in a source checkout; in an installed package it sits next to this directory, at ../skills/fissure_bug_bounty/). It drives these MCP tools with the right methodology (scope-first, the poll pattern, confirming scanner leads by hand, evidence-driven reporting). Claude Code auto-discovers skills in the .claude/skills/ of your working directory, so the skills are available whenever you run Claude Code inside the Fissure repo; to drive Fissure from another directory (say your target's own repo), or from an installed package, copy every skill folder into ~/.claude/skills/ (from a package: cp -r /opt/fissure/skills/* ~/.claude/skills/; from a checkout: cp -r .claude/skills/* ~/.claude/skills/). Register the bridge above, then just ask Claude:

    • Bug bounty / pentest: "test an authorized target" (the skill sets scope and confirms authorization before any active traffic).
    • CTF / lab: "solve this CTF" or "capture the flag at <url>", where the challenge itself is the authorization and the skill switches to flag-hunting mode (exploit to the flag; see the skill's references/ctf.md, which is ../.claude/skills/fissure_bug_bounty/references/ctf.md in a checkout and ../skills/fissure_bug_bounty/references/ctf.md when installed).
  • From a plain Python script, import fissure_control_client directly (it needs no MCP SDK):

    import sys, time; sys.path.insert(0, ".")
    import fissure_control_client as api        # SUITE_API_URL / SUITE_API_TOKEN from env
    api.set_scope(allow="target.test")          # authorized target only
    job = api.start_scan("http://target.test/", active=True)
    jid = job["job_id"]
    while api.get_scan_status(jid)["status"] not in ("done", "cancelled", "error"):
        time.sleep(1)
    print(api.report(fmt="markdown")["report"])

See the "Automating a bug-bounty engagement" section of ../docs/11_CONTROL_API.md for the curl / Python / Claude walkthrough.

Tools

Tool Control-API route Notes
health GET /api/status Liveness / connectivity check
send_request POST /api/request Send one request, return the response
start_scan POST /api/scans Returns {job_id}; optional login object for an authenticated scan
get_scan_status GET /api/scans/{id} Status + progress
get_scan_findings GET /api/scans/{id}/findings Findings once the job is done
cancel_scan POST /api/scans/{id}/cancel Request cancellation
get_findings GET /api/findings All control-API findings this session
transform POST /api/transform Multitool encode/decode/hash
smart_decode POST /api/smartdecode Auto-peel an encoding chain
compare POST /api/compare Line/word/byte diff + similarity
sequence POST /api/sequence Token randomness (shannon/monobit/chi2)
jwt POST /api/jwt JWT decode/verify/sign/crack
report GET /api/report?format= Export findings (+min_severity/host/source filters, risk score)
intruder POST /api/intruder Payload-position attack (sniper/.../grep)
discover POST /api/discover Content discovery (paths that exist)
get_scope GET /api/scope Read the scope allowlist
set_scope POST /api/scope Set the scope (applied to scans/intruder/discover)
graphql POST /api/graphql GraphQL argument workshop (count/arg/mutate)
cookie POST /api/cookie Signed-cookie workshop (detect/verify/sign/crack/decrypt)
saml POST /api/saml SAML workshop (decode/inspect/edit/strip/xsw/genkey/sign/verify)
inspect POST /api/inspect Decompose a request into headers/query/cookies/body
scope_import POST /api/scopeimport Parse H1/Bugcrowd/vendor/host-list scope text
js_transform POST /api/jstransform Run a user JavaScript transform over a string
bcheck POST /api/bcheck Compile a .bcheck into a QuickJS check
apispec POST /api/apispec Import an OpenAPI/Swagger/Postman definition
apispec_fetch POST /api/apispecfetch Probe a live target for a served OpenAPI/Swagger spec and import it
recon POST /api/recon Route recon-tool host/URL output into the inventory and scope
headless_crawl POST /api/headlesscrawl Headless JS-render crawl (katana -headless) routed into the inventory
jsmine POST /api/jsmine Mine endpoint URLs and secrets out of a JavaScript body
smuggle POST /api/smuggle Probe a URL for HTTP request smuggling (desync) by timing
massassign POST /api/massassign Probe for mass assignment (autobound privileged fields) + HTTP parameter pollution
storedxss POST /api/storedxss Stored/second-order XSS by write-then-read canary correlation
ssrf POST /api/ssrf Out-of-band blind SSRF, incl. gopher/dict alternate schemes (needs OAST)
paramminer POST /api/paramminer Mine hidden parameters the target reacts to
groupsend POST /api/groupsend Send a request group (seq/parallel/H2 race)
wsrepeater POST /api/wsrepeater Open a WS, send one frame, collect replies
jscheck POST /api/jscheck Run a scriptable (QuickJS) check vs a target
authmatrix POST /api/authmatrix Replay under N identities -> access verdicts
authz POST /api/authz Autorize-style access-control replay
rolediff POST /api/rolediff Offline diff of two role site-maps
plugins GET /api/plugins List bundled OSS-tool plugins + install state
plugin_run POST /api/plugins/run Run an installed plugin vs a target -> findings
plugin_install POST /api/plugins/install Build (not run) a dependency install command
oast_start POST /api/oast/start Start the out-of-band (OAST) listener
oast_stop POST /api/oast/stop Stop the OAST listener (hits stay readable)
oast_status GET /api/oast/status running/port/base_url/count
oast_mint POST /api/oast/mint Mint a canary {token,url} for a blind sink
oast_poll GET /api/oast/poll?token= Whether a canary was hit (out-of-band proof)
oast_history GET /api/oast/history All recorded OAST interactions
projects GET /api/projects List projects/workspaces + the active one
project_op POST /api/projects Create/delete/activate a project
env GET /api/env The per-project environment library
env_op POST /api/env Add/activate an env, set/remove a variable
env_expand POST /api/env/expand Expand {{vars}} in text
tags GET /api/tags Inline transform tags (custom + variables)
tags_op POST /api/tags Set/remove a custom tag or a variable
tags_eval POST /api/tags/eval Evaluate inline transform tags over text
organizer GET /api/organizer The per-project saved-request queue
organizer_add POST /api/organizer Stash a request (optionally in a collection)
organizer_remove POST /api/organizer/remove Remove a saved request by id
session_save POST /api/session/save Persist control findings to a named session
session_load POST /api/session/load Merge a saved session back into the store
report_pwndoc POST /api/report/pwndoc Push findings to a PwnDoc instance
report_pdf POST /api/report/pdf Render HTML + run a PDF command over it
proxy_start POST /api/proxy/start Start the control-driven intercepting proxy
proxy_stop POST /api/proxy/stop Stop the proxy (history stays browsable)
proxy_status GET /api/proxy/status running/host/port/flows/intercept
proxy_history GET /api/proxy/history Captured flows (newest window)
proxy_flow GET /api/proxy/history/{i} One flow's request/response
intercept_status GET /api/proxy/intercept enabled/pending + the held request
intercept_set POST /api/proxy/intercept Enable/disable interception
intercept_resolve POST /api/proxy/intercept/resolve Forward (opt. edited) or drop the held request

Scans use the poll pattern: start_scan returns a job_id, the agent calls get_scan_status until status is done, then get_scan_findings. Pass a login login-config object to start_scan for an authenticated scan (the job reports status error if the login fails); see resources/login/dvwa.json and docs/12_DVWA_LAB.md. Each tool call is short and the agent stays in control.

Configuration

Read from the environment (both SUITE_* and FISSURE_* names are accepted):

  • SUITE_API_URL / FISSURE_API_URL - base URL, default http://127.0.0.1:8777.
  • SUITE_API_TOKEN / FISSURE_API_TOKEN - the control-API token.
  • SUITE_API_TIMEOUT / FISSURE_API_TIMEOUT - seconds to wait for a control-API reply, default 600. Several routes block until an external tool or a multi-request campaign finishes, so keep it generous; a non-positive or non-numeric value falls back to the default.

The MCP transport is read by fissure_mcp_bridge.py only:

  • FISSURE_MCP_TRANSPORT - stdio (default), streamable-http (also accepted as http or streamable_http, served at /mcp) or sse (served at /sse).
  • FISSURE_MCP_HOST - bind address of a network transport, default 127.0.0.1.
  • FISSURE_MCP_PORT - its port, default 8779 (an invalid value falls back to it). It sits one above the control-driven proxy's default 8778 so both can run with defaults.

Errors

  • Connection refused -> the control API is off; enable it in the app settings.
  • 401 -> bad or missing token; update SUITE_API_TOKEN.
  • Other non-2xx -> the engine's JSON error is surfaced.

Scope

Only scan targets you are authorized to test. active/aggressive scans generate traffic and intrusive probes; the same scope rules as the interactive scanner apply.