Fissuredocumentation v5.3.1
On this page

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 (default 127.0.0.1:8777). The API binds loopback by default.
  • --api-key <key>: require this token on every request (X-API-Key or Bearer). 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 nothing
  • list shows every bundled plugin and whether its tool is present.
  • install --all installs only the tools that are missing. An explicit install <id>... (re)installs the named plugins, matched by plugin id or by dependency id, so a deliberate upgrade or reinstall is possible.
  • --dry-run prints 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"
  done

Files and environment

  • Config directory (Linux): ~/.config/fissure (honors XDG_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 (default http://127.0.0.1:8777) and SUITE_API_TOKEN, with FISSURE_API_URL / FISSURE_API_TOKEN as aliases; SUITE_API_TIMEOUT (alias FISSURE_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