Starting and using Fissure
This is the entry-point guide: every way to launch Fissure and what
each mode is for. Fissure is one binary (fissure) that runs
in several modes depending on the subcommand you give it. The desktop
GUI is the default; the same engine also runs headless for CI, as a
daemon that serves a REST control API, a browser dashboard (the web
portal), and the MCP endpoint an AI agent drives.
Read this first, then follow the cross-links into the mode-specific docs.
Choosing a mode
| You want to... | Run | Mode |
|---|---|---|
| Use the full desktop app (proxy, scanner, workshops, reports) | fissure |
GUI |
| Scan a target from a script or CI and get a report | fissure scan <URL> [opts] |
Headless scan |
| Regenerate a report from a saved session | fissure report --session <file> |
Headless report |
| Run the engine with no GUI, exposing the API + web portal + MCP | fissure serve [opts] |
Engine daemon |
| Call one control-API route without running a server | fissure api <METHOD> <ROUTE> |
One-shot API |
| Reconcile a purple-team run from the command line | fissure purple <subcommand> |
Purple-team CLI |
| List or install the OSS-tool plugins without the GUI | fissure plugins list / install --all |
Plugin management (section 7) |
| Drive the engine from an AI agent (Claude, ChatGPT) | fissure serve + the MCP bridge |
MCP (see 13) |
fissure --help prints the authoritative option list for
every subcommand; fissure --version prints the build
version. With no subcommand and no option, Fissure launches the GUI.
Only test systems you are authorized to assess. On first run the GUI
shows an authorization banner you must acknowledge; acceptance is
remembered in a marker file (authorized.ack) under the
config directory (see "Files and environment" below). The engine
enforces the scope allowlist, the safe/aggressive toggle, and the
authorization requirement in every mode, not just the GUI.
1. The GUI (default)
fissure
Launches the native desktop application: the intercepting proxy, the website scanner, Intruder, Repeater, the token/encoding/hash workshops, the OAST collector, the findings store, the report generator, and the plugin host, all in one window. This is the mode for interactive, exploratory testing.
- First run: acknowledge the authorization banner, then install the
generated CA in your browser/system trust store so HTTPS interception
works (the CA is created once per install and never shared; export it
from Settings or with
--selftest-export-ca <path>). - The GUI can also turn on the control API in-process (Settings >
Control API), so the web portal and the MCP endpoint are available while
the desktop app is running, without a separate
fissure serve. See section 4.
2. Headless scan
(fissure scan)
fissure scan https://app.example.com --scope app.example.com --active --oast 19000 -o report.md
Crawls the target, audits the discovered endpoints, and writes a
report. This is the CI / scripting mode: no GUI, deterministic exit
codes, report to stdout or a file. The most common option groups (see
fissure --help for the full list):
- Depth and breadth:
--quick,--profile <name>,--families <csv>,--points <csv>,--depth <n>,--max-pages <n>. - Scope and safety:
--scope <csv>,--exclude <csv>,--active,--aggressive,--delay <ms>,--threads <n>,--rps <n>,--max-time <sec>. - Authentication:
--login <config.json>,--cookie <string>,--crawl-post-url <url>,--header "Name: Value",--http-auth user:pass,--auth-check <url>(verify a session works, then exit without scanning). - Out-of-band confirmation:
--oast <port>,--oast-domain <domain>. REQUIRED for the SSRF family and the blind halves of injection and XXE; without a collector those checks probe nothing and the report reads like a clean target. - TLS:
--ca-file <pem>(trust a private CA with verification left on),--verify-tls,--insecure(the default). - Report options:
--format html|markdown|json|sarif|csv|burp,-o <file>,--min-severity <sev>,--source <src>,--exclude-triaged,--no-redact,--fail-on <sev>(exit 1 when a finding at or above that severity is present, for a CI gate). Add--save-session <file>to keep the run for later.
Ctrl+C asks a running scan to stop and still writes the report for what it audited; press it twice to force. The scanner itself is documented in 05_WEBSITE_SCANNER.md, reporting in 06_REPORTING.md.
3. Headless report
(fissure report)
fissure report --session run.fsn --format html -o report.html
Regenerates a report from a session file saved earlier (by a GUI
session save or fissure scan --save-session), without
re-running any traffic. Takes the same report options as
fissure scan. Use it to re-render an old run in a different
format, at a different --min-severity, or with
--no-redact.
4. Running
the engine without the GUI (fissure serve)
fissure serve --host 127.0.0.1 --port 8777 --api-key <your-token>
Runs the engine as a daemon with no GUI and keeps it running. This one process exposes three faces on the same host and port:
- The REST control API (every engine capability as an HTTP route).
- The web portal (a browser dashboard served at
/). - The MCP endpoint (the port the MCP bridge connects to on behalf of an AI agent).
Serve options:
--host <addr>/--port <n>: bind address and port (default127.0.0.1:8777). The API binds loopback by default.--api-key <key>: require this token on every request (X-API-KeyorBearer). On a loopback bind you can omit it; one is generated and printed for the run.--max-jobs <n>: how many control-API jobs run at once; the rest queue.--tls-cert <pem> --tls-key <pem>: serve over TLS. Off loopback the token crosses the wire on every request, so encrypt it (a self-signed pair is fine for a private deployment).--insecure: serve with NO authentication. Required to bind a non-loopback address without--api-key, because the control API can scan arbitrary targets, run plugin binaries, evaluate scripts, and write files. Keep the token secret: it grants full control of the engine.
Verify it answers (status needs no token):
curl -s http://127.0.0.1:8777/api/status
4a. The web portal (browser dashboard)
With the engine daemon running (or the GUI's control API enabled), open:
http://127.0.0.1:8777/
The same page is served at /, /ui, and
/index.html. It is a self-contained browser dashboard over
the control API: scope, scan, proxy history, findings, reports, and the
workshops, from any browser without the desktop app. It carries no data
of its own; every action is a control-API call, so the
--api-key token and TLS settings above apply to it too. The
dashboard and its tabs are described in 11_CONTROL_API.md.
The dashboard shows the control session, which is the one an AI agent drives through the MCP bridge: what the agent captured and configured is what you see. The Status tab's workspace overview names the active project, the scope, the proxy state and the traffic and job counts; each tab loads its data when you open it. Proxy lists the captured flows (click one for its request and response), Traffic lists every request every tool sent, Scope edits the active lists and the named scopes, and Projects lists, creates, activates and deletes projects. The API tab lists every control route with its documented request body, so anything the agent can call you can call from the browser too.
4b. The control API
The full route list and semantics are in 11_CONTROL_API.md. Every capability the
GUI and the MCP bridge have is reachable over the API, so a script,
curl, or the pure-standard-library client
bridge/fissure_control_client.py can drive the same
tools.
4c. The MCP endpoint (AI agent)
fissure serve is step 1 of connecting an AI agent. A
thin MCP bridge (bridge/fissure_mcp_bridge.py) turns each
control-API route into one MCP tool and runs as a stdio subprocess
launched by the MCP host (Claude Code, Claude Desktop, ChatGPT). The
bridge reads SUITE_API_URL and SUITE_API_TOKEN
(or the FISSURE_API_URL / FISSURE_API_TOKEN
aliases) to reach the daemon. The full setup, including the
fissure_bug_bounty skill, is in 13_MCP_AND_SKILL_SETUP.md.
5. One-shot API call
(fissure api)
fissure api GET /api/status
fissure api POST /api/scope '{"allow":"example.com"}'
fissure api POST /api/scan --data-file body.json
Calls any control-API route in-process, without a server running. Use
it for scripting a single action, or to test a route from the shell.
--data-file <path> reads the JSON body from a file
(or - for stdin). Exit code: 0 on a 2xx reply, 1 on any
other status, 2 on a usage error. The route list is the same 11_CONTROL_API.md.
6. Purple-team CLI
(fissure purple)
fissure purple status
fissure purple import defender_log.json
fissure purple reconcile --window-ms 60000
Subcommands: status (the default when none is given;
coverage is an alias), import <file>
(with --source <name> and
--kind <kind>), reconcile,
findings (with --format <fmt> and
-o <file>), baseline, diff,
clear, marker.
reconcile --window-ms <ms> sets the time window the
path-based match uses; it defaults to 300000 ms (five minutes), which 0
or omitting it also selects. These drive the purple-team reconciler from
the command line; a scan records its requests as probes with
fissure scan ... --purple <run>, then you reconcile
the run against the defender's telemetry. The full workflow is in 15_PURPLE_TEAM.md.
7. Installing plugins headlessly
Fissure wraps external OSS tools (nuclei, ffuf, httpx, subfinder,
sqlmap, and more) as plugins; each is optional and detected by the
presence of its binary. The fissure plugins subcommand
lists them and installs them without the GUI.
fissure plugins list # id, category, installed, name
fissure plugins install --all # install every tool not already present
fissure plugins install nuclei ffuf # install the named plugins
fissure plugins install --all --dry-run # print each install command, run nothinglistshows every bundled plugin and whether its tool is present.install --allinstalls only the tools that are missing. An explicitinstall <id>...(re)installs the named plugins, matched by plugin id or by dependency id, so a deliberate upgrade or reinstall is possible.--dry-runprints the command for each target without running it.- Exit code: 0 on success, 1 if any install failed, 2 on a usage error
(an unknown id, a missing operation, or install with no target). A tool
with no automatic recipe is reported to install by hand and does not
fail the run under
--all.
Install recipes come from resources/dependencies.json
and shell out to system package and toolchain managers (apt, go install,
pip, a GitHub release download, git clone), so you are running
third-party installers; use --dry-run first, or review that
file, if that matters to you. This is the headless equivalent of the GUI
Plugins view's "Install all". Because detection is by binary presence,
installing the underlying tools by their own means (your package
manager, go install, and so on) works just as well; Fissure
picks them up with no further step.
Over the control API and MCP
The control API and its MCP tools expose the same plugin data, but
with one deliberate difference from the CLI and GUI: they do NOT execute
installers. GET /api/plugins (MCP plugins)
lists the plugins with an installed flag, and
POST /api/plugins/install {"tool":"<id>"} (MCP
plugin_install) returns the shell command that would
install a tool rather than running it. The engine never runs a
third-party installer on behalf of a remote API caller; running the
installer stays a local, explicit action (the
fissure plugins CLI or the GUI button). An agent can
therefore surface install commands, which you or the CLI then execute.
See 11_CONTROL_API.md and 13_MCP_AND_SKILL_SETUP.md.
If you would rather script it against a running daemon, this loop
reproduces install --all from the API responses:
# Install every missing plugin tool from the control-API responses.
fissure api GET /api/plugins \
| jq -r '.plugins[] | select(.installed == false) | (.dependency // .id)' \
| sort -u \
| while read -r tool; do
[ -n "$tool" ] || continue
cmd=$(fissure api POST /api/plugins/install "{\"tool\":\"$tool\"}" | jq -r '.command')
[ "$cmd" = "null" ] || [ -z "$cmd" ] && { echo "$tool: no recipe, skipping"; continue; }
bash -c "$cmd"
doneFiles and environment
- Config directory (Linux):
~/.config/fissure(honorsXDG_CONFIG_HOME). Holds the per-install CA, the authorization acknowledgement marker (authorized.ack), the control-API token, settings, projects, scope, the cookie jar, and saved sessions. - Control-API client env:
SUITE_API_URL(defaulthttp://127.0.0.1:8777) andSUITE_API_TOKEN, withFISSURE_API_URL/FISSURE_API_TOKENas aliases;SUITE_API_TIMEOUT(aliasFISSURE_API_TIMEOUT, default 600s) bounds how long the bridge waits for one reply. Used by the MCP bridge and the Python client. - AI-provider env (for the in-app AI assistant):
FISSURE_AI_PROVIDER,FISSURE_AI_BASE_URL,FISSURE_AI_API_KEY,FISSURE_AI_MODEL. - Default ports: control API 8777, proxy 8080, OAST collector 19000, HTTP/3 MITM proxy 8446.
See also
- 11_CONTROL_API.md: the control API, the web dashboard, and every route.
- 13_MCP_AND_SKILL_SETUP.md: connecting an AI agent over MCP with the skill.
- 04_NETWORK_AND_PROXY.md: the proxy and CA.
- 05_WEBSITE_SCANNER.md: the crawler and checks.
- 06_REPORTING.md: report formats and generation.
- 15_PURPLE_TEAM.md: purple-team mode.
- FEATURES.md: the full capability inventory.