Volume V - Extending Fissure
Fissure becomes a platform when its built-in tools are not enough.
Where a mainstream web-security platform is extended with JVM extensions
and a proprietary extension API, Fissure is extended without
recompiling. The base surfaces are file-based, loaded from disk at
startup, all optional and offline: fs.* scripted checks,
transform/generator scripts, and OSS-tool plugin manifests. On top of
those, the Extension SDK packages the same capabilities
into installable, versioned bundles - an extension.json
manifest that contributes checks, GUI panels, inline tabs,
context/session actions, request hooks (scripts that rewrite outbound
proxy traffic), and message editors - managed from the
Extensions toolbar popup (enable/disable/reload, an
offline signed marketplace to install or remove bundles, and, for the
selected bundle, its tabs shown inline). There is no build step, no
account, and no network dependency. This volume is the Fissure
equivalent of extension development for a mainstream web-security
platform.
The reference is docs/EXTENDING.md (the file-based
surfaces) and docs/14_EXTENSION_SDK.md (the bundle
manager); this chapter is the guided tour.
Chapter 1 - Why and When to Extend
Extend Fissure to encode a repeated action, project-specific logic, or a custom check into a reusable tool inside the workflow: add an application-specific scanner check, transform a value the way the target expects, or wrap an external tool. Do not extend when a smaller path exists: a one-off request change belongs in the Repeater or a match-and-replace rule, a simple encoding belongs in the Multitool or an inline tag, and large-scale fuzzing belongs in the Intruder Script generator.
1.1 Design principles
The same principles that keep any tool extension safe apply here:
- Small first: implement the narrowest useful behavior.
- Safe by default: do not mutate traffic or send active probes unless enabled.
- Observable: log what the extension does; report results as findings.
- Scope-aware: respect the scope allowlist and the safe/aggressive toggle.
- Fail closed: an error should stop the automation, not spray requests.
- Evidence-oriented: make results easy to reproduce.
Chapter 2 - Scripted Checks (the fs.* API)
Scripted checks are JavaScript (QuickJS) run against captured or scanned responses. This is the programmatic-extension surface.
2.1 Where they live and when they run
Drop a *.js file under resources/checks/.
Fissure loads every script there at startup into three places: the Proxy
passive node (each newly captured response runs through the scripts as a
passive check), the Findings and Proxy right-click Run scripts action
(on demand against stored exchanges), and the scanner (alongside the
built-in active checks).
2.2 The fs object
A check is a plain script with no required entry function. It runs
with a global fs bound to the current exchange.
Read-only getters: fs.url, fs.method,
fs.status, fs.body, fs.time, and
fs.active (1 when request-mutating fs.send()
is permitted, 0 in a passive context, so guard active probes on it).
Methods: fs.header(name) and fs.headers();
fs.json() (the body parsed as JSON, or null);
fs.log(msg); fs.send(req) (send a follow-up
request and return {status, body, time, headers}, only when
fs.active, with a per-run call limit);
fs.sendraw(raw) (send a hand-built raw HTTP request string
byte-for-byte to the target's host/port and return the same parsed
response object, or null; also only when fs.active, sharing
the call limit); and fs.report(finding) (record a finding;
category and title are required, plus
severity, confidence, cwe,
owasp, description, evidence, and
remediation).
2.3 An example active probe
// resources/checks/active-reflection.js
if (fs.active) {
var marker = "fzz" + (fs.status || 0) + "rfl";
var sep = fs.url.indexOf("?") < 0 ? "?" : "&";
var r = fs.send({ url: fs.url + sep + "fzprobe=" + marker });
if (r && r.status === 200 && (r.body || "").indexOf(marker) >= 0) {
fs.report({
severity: "medium",
confidence: "firm",
category: "Reflected input",
title: "Parameter value reflected in response",
evidence: marker
});
}
}Findings are de-duplicated by
host|category|title|location, so a scripted check and a
native check describing the same issue do not double-report. A scripted
introspection check for GraphQL, for instance, will not double up with
the native GraphQL check.
2.4 Quality
A scanner check is a reusable hypothesis. Engineer it for signal quality: require multiple indicators rather than a single weak match, compare against a baseline, verify context for a reflected payload, and suppress duplicates. A small set of precise checks is worth more than a large set of noisy ones.
Chapter 3 - Transform and Generator Scripts
The second surface is short JavaScript snippets that turn one string
into another, or generate a list of payloads. They share the QuickJS
runtime with scripted checks but have a different shape:
input holds the text, and the return value is the
result.
- Payload processing: a Script step in the Intruder pipeline runs per
payload (
inputis the payload; return a value or definetransform(input)). - Multitool convert: the Multitool script editor applies a convert transform to the input the same way.
- Payload generation: the Intruder Script payload type is a generator whose return value is split by newlines into payloads (Volume II, Chapter 6).
- Inline tags: a custom JavaScript tag in the Tags popup wraps
inputand returns the transformed result (Volume III).
Runaway scripts time out rather than hang. Keep them small; a transform longer than the test it serves is a smell.
Chapter 4 - OSS-Tool Plugins
The third surface wraps an external command-line security tool in a JSON manifest that declares how to launch it and how to parse its output into findings, with no C code.
4.1 The plugin host
Open the Plugins popup (F7, or Plugins in the Config toolbar category). Wrapped tools include nuclei, ffuf, httpx, katana, dalfox, subfinder, waybackurls, and gau, plus the GraphQL fingerprinters graphw00f and clairvoyance, the port scanners naabu (unprivileged) and masscan (needs root/CAP_NET_RAW), the parameter finders arjun and paramspider, the WordPress scanner wpscan, and the DNS resolver dnsx. Pick a tool, set a target, and Run. Content and parameter tools (ffuf, gobuster, feroxbuster) also take a Wordlist path. Each run opens a tab in the Output pane; page through older tabs with Prev and Next. Add to report puts the shown output into the report as an Info finding, and Close deletes the selected output tab. Several plugins can run at once; the Running: N button opens a panel of active jobs with a per-job Cancel and Cancel all. Tabs are in-memory only and are discarded when Fissure exits. Recon all runs every installed recon-category tool (subfinder, gau, katana, httpx, and the like) against the target in one go and feeds what they find into the site map; with no recon tool installed it says so on screen.
External tools run as detached subprocesses, so a long-running tool does not block the GUI, and the plugin is optional: present if installed, gracefully skipped if absent.
4.2 The dependency manager
If a tool's binary is missing, Install fetches it per
resources/dependencies.json (a GitHub release download,
go install, pip, apt, a RubyGems gem install,
or git clone) into ~/.local/share/fissure/bin
or the usual user install directories, which Fissure also searches.
Install all installs every missing tool at once. Each install opens a
tab with its log, so a failure (for example a missing Go toolchain) is
visible. Install and run only against authorized targets.
The same installer runs headless from the CLI:
fissure plugins list # each tool and whether it is present
fissure plugins install --all # every tool not already present
fissure plugins install nuclei ffuf --dry-run # print the install commands only
--dry-run prints the command for each target without
running it, which is the way to review what an install would do on a
locked-down machine.
4.3 Writing a manifest
A plugin manifest declares the command, an argument template expanded
per run, and a parser that maps output records onto Fissure findings
(line-and-regex, or JSON). Mirror an existing manifest under
plugins/: the dalfox and sqlmap manifests show the common
shapes (the latter uses an interpreter such as python3). A
tool that reads its target from standard input rather than a flag (for
example dnsx) sets an optional "stdin" template (expanded
per run, e.g. "{{target_host}}") that the plugin host
writes to the child's stdin. Add a matching entry under
resources/dependencies.json so the dependency manager can
install the tool.
Chapter 5 - Importing Checks: BCheck, Nuclei, and Jaeles
The quickest way to bring a template in from the GUI is the Import
checks popup (Power-ups toolbar category, or the command palette). Pick
the source format (BCheck, nuclei, or Jaeles), paste the template into
Template source or press Load file, then Compile: the output pane shows
the resulting scripted check plus any clauses the compiler could not
express. Install writes the compiled check into your per-user checks
directory, so scans and the live Proxy passive pass run it from then on.
The sections below describe what each compiler understands; dropping the
file under resources/checks/ works too.
5.1 BCheck import
BCheck import reuses the scripted-check surface: drop a
.bcheck file next to your JavaScript checks under
resources/checks/, and Fissure compiles the common
single-probe shape (metadata plus given / send / if-condition / report)
into an equivalent scripted check that runs in the scan and the live
Proxy passive pass. A slice of the public BCheck library therefore runs
unchanged (Volume III, Chapter 3). Multi-step BChecks compile too: a
send request called <name> step with its own
method / path / body /
headers becomes that step's own request, so a
login-then-access flow issues distinct requests. This is the
lowest-effort way to bring an existing check into Fissure.
5.2 Nuclei template import
Nuclei YAML templates load the same way: drop a .yaml /
.yml template under resources/checks/ and the
offline importer compiles it into an equivalent fs.*
scripted check that runs once per host at scan time, with no nuclei
binary required. It handles the common HTTP-template shape:
- one or more
httprequest blocks (a method plus{{BaseURL}}paths, with theirbodyandheaders); a multi-request template runs every step in order, and a setup step that has a body or headers but no matchers (a PUT that uploads a file, a login) is fired for its side effect before the later matching request rather than dropped, so a two-step PUT-then-GET template detects; word/regex/status/size/xpath/binarymatchers on thebody,header, orcontent_typepart, combined bymatchers-condition(and/or), plus a subset ofdslexpressions (status_code,contains,len,regex);interactshout-of-band matchers (part: interactsh_protocol+{{interactsh-url}}): the check mints an OAST canary and confirms the finding when it is hit, so blind SSRF/RCE templates work (Volume II, the OAST chapter);regex/kval/json/xpathextractors: the captured value is added to the finding evidence, and aninternal: trueextractor is exported as a chaining variable a later request references by{{name}};payloads/ fuzzing (DAST) templates as a per-payload query-injection loop;raw:templates: the verbatim request block (request line, headers, body) is reconstructed and sent byte-for-byte viafs.sendraw, with{{Hostname}}/{{Host}}/{{Port}}resolved from the target origin, so a hand-crafted odd request (a malformed method, a duplicate header, an explicitContent-Length) runs offline too;workflows:documents are recognized, not refused: a workflow carries no requests of its own but declares which detection template gates which tags, so dropping one underresources/checks/installs those gates and a tagged check then waits for its detector to report on a host before it runs (the control API and the MCPnuclei_importreturn the parsedgateslist instead of a compiled check).
Two matcher types rely on engines built into the scripting runtime:
an xpath matcher selects a node in the HTML/XML body via a
libxml2 XPath engine (fs.xpath), and a binary
matcher searches for a hex byte sequence in the raw response body via
fs.bodyhex (byte-aligned and binary-safe, so a byte after
an embedded NUL - which the UTF-8 fs.body string would drop
- is still matched).
What the importer cannot compile - dsl extractors,
large-scale payload fuzzing, or a template with nothing usable - is
listed in its skipped notes rather than failing the whole
template. For those, for the full CVE library, and for large-scale
active fuzzing, run the bundled nuclei plugin instead
(Chapter 4 / the Plugins popup): it drives the real nuclei binary over
the whole template repository and parses its output back into
findings.
The importer is also on the control API
(POST /api/nuclei) and the MCP bridge
(nuclei_import), which return
{name, description, js, skipped}; feed the returned
js to jscheck (or
POST /api/jscheck) to run it against a target.
5.3 Jaeles signature import
Jaeles detection-signature YAML is the third format the offline
compiler understands. A signature is an id, an
info block (name / risk),
optional variables, and a requests list;
Fissure compiles it into an equivalent fs.* scripted check,
no jaeles binary required. It handles:
- every request in the list (
method/url/headers/body, with{{.BaseURL}}resolved to the target origin): the requests are sent in order and their detections ANDed, so a multi-step signature is a chained detection; variables: literalname: valuepairs substitute their text into{{.name}}placeholders, and theRandomString(n)/RandomNumbergenerators become a fresh per-run value (so a signature that plants a random marker and checks for its reflection works with a live canary);detections(a list, ANDed): theStatusCode()andContentLength()helpers in numeric comparisons,StringSearch(component, "text")(a case-insensitive contains), andRegexSearch(component, "regex"), over the componentscomponent.response/component.body/component.header, combined with&&/||/!;- a
type: passivesignature (or a top-leveldetections:block) compiles to a passive check that evaluates against the current response without sending.
A detection using an unsupported helper is dropped, and generator
functions other than the two above, request middlewares/chaining, and
non-scalar variables are recorded in the skipped notes.
Exposed over the control API (POST /api/jaeles) and the MCP
bridge (jaeles_import); feed the returned js
to jscheck. From the browser dashboard, the Import tab
compiles all three formats (nuclei / BCheck / Jaeles) and runs the
result.
Chapter 6 - The Control API
Beyond in-process extension, Fissure exposes an optional local HTTP control plane so an external peer (a script, a CI job, curl, or an agent) can drive the engine without the GUI. It is off by default, loopback only, and token-gated.
6.1 Enabling it
In Settings, under Control API, Enable local control API starts a
JSON HTTP server on 127.0.0.1 (default port 8777). A bearer
token, shown and regenerable, gates every route except the health check,
sent as X-API-Key or Authorization: Bearer.
The enabled state, port, and token persist and auto-start on the next
launch. The same surface runs headless via
fissure serve [--host <addr>] [--port <n>] [--api-key <key>].
6.2 The endpoints
| Method | Path | Auth | Action |
|---|---|---|---|
| GET | /api/status |
open | Liveness. |
| GET | /api/findings |
token | Findings from control-API scans, as a report. |
| POST | /api/request |
token | Send one request through the engine. |
| POST | /api/scan |
token | Run a scan synchronously; return the report. |
| POST | /api/scans |
token | Start a scan asynchronously (202, job_id). |
| GET | /api/scans/{id} |
token | Job status and progress. |
| GET | /api/scans/{id}/findings |
token | The job's findings once done. |
| POST | /api/scans/{id}/cancel |
token | Request cancellation. |
The surface is hardened: the request size is capped (413 over 64
KiB), a per-connection read timeout keeps a stalled client from pinning
the accept loop, and every command is audited to the log. It operates
its own findings store and does not mutate the interactive GUI tabs,
which keeps it thread-safe. Do not point POST /api/request
at the control API's own port: the single accept loop is busy serving
that request and cannot answer the nested one. See
docs/11_CONTROL_API.md.
6.3 The MCP bridge
Under bridge/, a thin FastMCP stdio server exposes one
MCP tool per route so an MCP host such as Claude Code can drive the
engine as an agent. The core tools are health,
send_request, start_scan,
get_scan_status, get_scan_findings,
cancel_scan, and get_findings, but the bridge
mirrors the whole control surface (well over a hundred tools): the
analysis workshops (jwt, cookie,
saml, graphql, smart_decode), the
recon loop (recon, reconchain,
assets), the intruder and group-send
(intruder, groupsend for the HTTP/2
single-packet attack), the persistent proxy match-and-replace ruleset
(matchrep, including regex $N capture-group
substitution), client-side DOM testing (domprobe,
dominvader), and the HTTP/3 tools (http3
fetch, http3_diff version differential,
h3proxy MITM listener). An authenticated scan takes a
login object with an optional
reauth_on_contains marker for mid-scan re-authentication.
The single source of truth for the catalog is
.claude/skills/fissure_bug_bounty/references/mcp_tools.md.
Configure the host:
claude mcp add fissure-control \
--env SUITE_API_URL=http://127.0.0.1:8777 \
--env SUITE_API_TOKEN=<token-from-settings> \
-- python /path/to/Fissure/bridge/fissure_mcp_bridge.py
The bridge needs the MCP Python SDK
(pip install "mcp>=1.27,<2"); its HTTP client is pure
standard library with no third-party dependency, and is independently
usable and tested. Scans use the poll pattern (start, then poll status
until done, then read findings) so each tool call stays short and the
agent stays in control. See bridge/README.md.
Chapter 7 - The Built-in AI Assistant
Chapter 6 opened the engine to an external agent. Fissure also ships its own, optional, LLM assistant so the reasoning happens inside the app. There are two surfaces, and they are deliberately different in power:
- the AI assistant popup, a request-contextual, one-shot helper that explains a request, triages a finding, drafts a proof-of-concept, or answers a question, and does nothing else; and
- the AI chat, an agentic assistant that can drive Fissure by calling its own tools over the control API, gated so it cannot act on traffic without your say-so.
Both are opt-in and both call a third-party endpoint you configure with your own key: the assistant sends the input you give it to that endpoint, so use it only on data you are comfortable sharing, and only against authorized targets. Neither is required to use Fissure; if you configure no provider, both simply tell you so.
7.1 The multi-provider config
One configuration serves both surfaces. Fissure speaks three wire protocols and maps every supported provider onto one of them:
- Anthropic Messages (auth header
x-api-key,content[]blocks); - OpenAI chat completions (auth
Authorization: Bearer,choices[].message); - Google Gemini generateContent (auth
x-goog-api-key,candidates[].content.parts).
Several named providers are just presets over the OpenAI chat-completions protocol; they differ only in endpoint URL and default model, so Mistral, DeepSeek, a local Ollama server, and any other OpenAI-compatible gateway all reuse that one code path. Fissure picks the right endpoint shape and auth header from the selected provider, so you never assemble the call yourself:
| Provider | Wire protocol | Default endpoint | Default model | Key |
|---|---|---|---|---|
| Anthropic | Anthropic Messages | https://api.anthropic.com/v1/messages |
claude-sonnet-4-6 |
required |
| OpenAI | OpenAI chat completions | https://api.openai.com/v1/chat/completions |
gpt-4o-mini |
required |
| Gemini | Gemini generateContent | https://generativelanguage.googleapis.com/v1beta/models |
gemini-2.5-flash |
required |
| Mistral | OpenAI-compatible | https://api.mistral.ai/v1/chat/completions |
mistral-small-latest |
required |
| DeepSeek | OpenAI-compatible | https://api.deepseek.com/v1/chat/completions |
deepseek-chat |
required |
| Ollama | OpenAI-compatible | http://localhost:11434/v1/chat/completions |
llama3.1 |
none |
| OpenAI-compatible | OpenAI chat completions | you supply it | you supply it | as needed |
For Gemini the base URL is the models endpoint; the model id and
:generateContent are appended at send time.
Configure a provider in Settings, under the AI assistant group:
- Click the Provider button to cycle through Anthropic, OpenAI, Gemini, Mistral, DeepSeek, Ollama, and generic OpenAI-compatible. The endpoint and model placeholders update to show that provider's defaults.
- Paste the API key. A local Ollama server needs none; every hosted provider does. Without a key (and a non-Ollama provider) both AI surfaces refuse to run and say so on screen rather than failing silently.
- Optionally set a model id; blank uses the provider default shown in the placeholder. For the generic OpenAI-compatible provider the model is required.
- Optionally set an endpoint URL; blank uses the provider default. The generic OpenAI-compatible provider requires you to supply one (for example a local gateway). TLS verification follows the default request-TLS setting.
The settings persist with the rest of your configuration.
The GUI popups read this configuration from Settings. The
headless / control-API AI path (the AI-assisted
variation source used by the Shadow Repeater route, see below) instead
reads its provider from the environment, so an automated run needs no
GUI: set FISSURE_AI_PROVIDER,
FISSURE_AI_API_KEY, FISSURE_AI_MODEL, and
FISSURE_AI_BASE_URL before launching
fissure serve or the process that hosts the control API.
When FISSURE_AI_PROVIDER is unset the headless AI features
stay off and the run remains fully deterministic.
7.2 The AI assistant popup
This is the everyday helper. Right-click any captured request in the Proxy, Findings, or Target views and choose AI assist. The popup opens pre-loaded with a dump of that request (method, URL, headers, body) in its Input pane. Because it needs a selected request it is reached only from the context menu, not the command palette; it is the one AI surface that is purely request-contextual.
Pick a task in the combobox:
- Explain request (the default): what the request does, its notable headers and parameters, and any security relevance.
- Triage finding: given a finding, whether it looks like a true or false positive, a justification for the severity, and concrete next steps.
- Draft PoC: a minimal, safe proof-of-concept for an authorized test (no destructive actions, exfiltration, or denial-of-service).
- Ask a question: your own free-form question in the Question field, answered using the Input pane as context (for example, "is this endpoint vulnerable to IDOR, and how would I confirm it?").
Press Run. The call happens on a worker thread so the GUI never freezes; the status line shows it is asking the assistant, the Run button disables while it works, and the answer lands in the Answer pane, selectable to copy. This surface is a single one-shot call: it reasons about the input you gave it and returns text. It does not send further requests, run checks, or change your workspace. For that, use the AI chat.
7.3 The agentic AI chat
Open AI chat from the toolbar (Power-ups category)
or the command palette (Ctrl+K). Where the popup answers, the chat
acts: it runs an agent loop that can call Fissure's own tools,
which are the very control-API routes from Chapter 6. It dispatches them
in-process through the same control handlers
(fissure_control_dispatch), so the control-API HTTP server
in Settings does not have to be enabled for the chat to work; the chat
is the in-app equivalent of the external MCP agent from 6.3, and it
drives the same engine.
Each turn, the loop renders the transcript, sends it to the provider with a system prompt that lists the available tools and the tool-call format, parses any tool directive out of the reply, runs it, appends the result, and repeats, up to a small step cap (eight tool calls per send) so a run always terminates. A long tool result is truncated in the transcript so it cannot balloon the conversation.
The tools the agent may call, and their read/write class:
| Tool | Class | What it does |
|---|---|---|
get_scope |
read | Read the current authorized scope allowlist. |
list_findings |
read | List all findings in the store. |
query |
read | Filter findings or captured traffic with the HTTPQL dialect (Volume VI). |
assets |
read | Read the recon host/asset inventory. |
list_workflows |
read | List the saved workflow pipelines. |
scan_status |
read | Read one scan job's status by job_id. |
scan_findings |
read | Read one scan job's findings by job_id. |
start_scan |
write | Start a scan of a URL (active:true generates attack
traffic). |
send_request |
write | Send one HTTP request through the engine (the Repeater primitive). |
workflow_run |
write | Run a workflow pipeline over a URL. |
The agent reads the scope with get_scope but cannot
change it: there is deliberately no set_scope tool. The
authorized scope is the operator's authorization boundary, set only in
the Scope editor and pushed into the agent's context before the loop
(7.5); if a host the agent needs is not in scope it must say so and
stop, not retarget.
The tool-call directive is provider-agnostic, so it works with every provider even when the provider has no native tool-calling API. To call a tool, the model replies with exactly one line and nothing else:
@@TOOL@@ {"tool":"NAME","args":{...}}
Fissure runs it and feeds the result back as the next turn; the model
then either calls another tool or, when it is done, replies with a
normal answer that has no @@TOOL@@ line. That plain reply
is the final answer for you.
7.4 An example conversation
Here the operator asks the chat to scan a target and summarize it. Aggressive write mode (7.5) is on, so the write tools run. The transcript reads:
Operator: Scan http://testphp.vuln.example/ and summarize the high-severity findings.
Assistant: @@TOOL@@ {"tool":"get_scope","args":{}}
Tool result: {"allow":"testphp.vuln.example","deny":"","active":true}
Assistant: @@TOOL@@ {"tool":"start_scan","args":{"url":"http://testphp.vuln.example/","active":true}}
Tool result: {"job_id":"a1b2c3","status":"running"}
Assistant: @@TOOL@@ {"tool":"scan_status","args":{"job_id":"a1b2c3"}}
Tool result: {"job_id":"a1b2c3","status":"done","done":true,"progress":{"percent":100}}
Assistant: @@TOOL@@ {"tool":"scan_findings","args":{"job_id":"a1b2c3"}}
Tool result: {"findings":[{"severity":"high","title":"SQL injection","location":"/artists.php?artist=1"}, ...]}
Assistant: The scan finished. One high-severity issue stands out: a SQL
injection in the artist parameter of /artists.php. Next I would confirm it
with a boolean or time-based payload and check whether it is authenticated.
The chat is equally a driven Repeater. Ask it to resend a request
with a change and it reaches for send_request:
Operator: Resend the login POST but set role=admin and tell me if the response differs.
Assistant: @@TOOL@@ {"tool":"send_request","args":{"url":"http://testphp.vuln.example/login","method":"POST","headers":"Content-Type: application/x-www-form-urlencoded","body":"user=alice&role=admin"}}
Tool result: {"status":200,"status_text":"OK","headers":[...],"body":"...","timing":{"total_us":142000}}
You continue the conversation by typing the next message; the same transcript carries forward. New clears it, and Save / Load (with the title field and the saved-conversation list) keep a conversation as a JSON file under your config directory so you can resume an engagement later.
7.5 The aggressive-write gate
The chat can drive active tools, so it observes the same
safe-by-default discipline as the rest of Fissure. Read-only tools (the
read rows in the table) always run automatically. The write tools
(start_scan, send_request,
workflow_run) are the ones that generate traffic or mutate
the workspace, and they are gated behind the Aggressive write
mode toggle:
With the toggle off (the default), the agent may still read freely, but when it emits a write directive the loop refuses to run it and appends a message the model can read:
Tool result: [gated] 'start_scan' is a write/active action; turn on the 'Aggressive write mode' toggle to allow it. Read-only tools still work.The system prompt tells the model up front that write tools need your approval, so a well-behaved agent asks you to flip the toggle rather than looping on a wall.
With the toggle on, write tools run automatically. The status line reflects the mode ("write tools allowed" versus "write tools gated") so the state is never hidden.
Even with the gate open, every action is still scope-enforced by the control handlers themselves. Before the loop starts, the chat pushes your configured scope allowlist and denylist into the control context, so an active scan or request the agent launches only touches in-scope, authorized hosts. The gate governs whether the agent may act; scope governs where. This is the same layered control that protects the GUI and the external control API.
For AI-assisted variation testing of a single request (an AI
proposing fuzzing values that are replayed and diffed against a
baseline), see the Shadow Repeater in Volume VI; it
uses the same provider config described in 7.1 (or the
FISSURE_AI_* environment variables on the headless path)
but is a request-level tool rather than a conversational agent.
Chapter 8 - Extending Lab
- Write a passive scripted check under
resources/checks/that reports an Info finding when a response carries a debug-style header, and confirm it fires on live Proxy traffic. - Add an active variant guarded on
fs.activethat sends one probe withfs.send()and reports on a reflected marker; run it via Run scripts. - Convert a public
.bcheckfile by dropping it in the same directory and confirm it runs. - Add a one-step Script transform to an Intruder pipeline and a one-line inline tag in the Tags popup.
- Wrap a small CLI tool in a plugin manifest with a line-and-regex
parser, add its
dependencies.jsonentry, Install it, and Run it so its output becomes a finding. - Enable the control API in Settings, then drive
GET /api/statusand one async scan with curl using the token. - Configure an AI provider in Settings, right-click a captured request, and use AI assist to Explain it. Then open AI chat and, with Aggressive write mode off, ask it to list your findings (a read tool runs) and to start a scan (see the write tool gated). Turn Aggressive write mode on and repeat to watch the scan run in scope.