Purple-team mode: measure the detection, do not evade it
Fissure's ethics mandate draws one hard line: no target-owner evasion. Nothing in the tool conceals, delays, obfuscates or misattributes the tester's activity to defeat the owner's own logging, monitoring or incident response. That boundary is deliberate and it does not move: a red team is measured by whether the blue team DETECTED it, so destroying the record defeats the exercise as well as the customer.
Purple-team mode is what sits on the other side of that line. Instead of hiding from the owner's monitoring, it measures it. Fissure records what every probe looked like on the wire; the operator brings back what the target's own logging and alerting produced over the same window; the two are reconciled; and what comes out is a per-technique detection coverage table, plus findings for the techniques nothing caught. "Did they see us" becomes a reported gap the owner can fix, which is worth more to a defender than a quiet test.
This document describes the model, the surfaces, and how to run one.
1. The model
1.1 A probe
While the mode is on, every request the transport engine puts on the wire is recorded as a probe:
| Field | What it is |
|---|---|
id |
probe number, unique within the run |
ts_ms |
when the request went out (epoch milliseconds) |
marker |
the correlation value on the wire,
<run>-<id>, or empty when unmarked |
tool |
which tool sent it (scanner, repeater, intruder, crawler, ...) |
technique |
the attack technique it carried (a check family, or
traffic) |
method, host, path |
what was requested |
url |
the full URL of this attempt |
wire |
the request bytes as sent, truncated to
FISSURE_PURPLE_WIRE_MAX |
status |
the response status, or 0 when the request failed before one arrived |
state |
the reconciliation outcome (below) |
detector |
the telemetry source that saw it, when one did |
Recording happens per ATTEMPT, not per call: a redirect hop is its
own probe, because it is its own request in the target's logs too. The
store is process-global (one purple run per Fissure process, like the
shared resource pools), mutex-guarded because scan workers record from
many threads, and bounded (the oldest probes drop past
FISSURE_PURPLE_PROBE_MAX), so a long run cannot grow
without limit.
1.2 How a probe gets its technique
An active check enters its family gate (chk_fam_on)
before it sends anything, so the gate tags the calling thread with that
family: sqli, xss, lfi, cmdi, ssti, crlf, redirect and the rest. The tag
is thread-local, because the audit runs one family per worker; a
process-global tag would attribute one worker's probes to whatever
another worker entered last.
A request sent outside a check has no tag, and is classified from its
own bytes by payload signature (fissure_purple_classify):
/etc/passwd and ../../ are lfi,
UNION SELECT and sleep( are sqli,
<script and onerror= are xss,
169.254.169.254 is ssrf, and so on. A request that carries
no attack signature is traffic.
Requests that are deliberately NOT attacks untag the thread first
(the crawl fetch, the scan's baseline page fetch, the session priming
POST), so plain navigation is filed as traffic rather than
inheriting the last check's label.
1.3 The correlation marker
With the marker on (the default), every recorded probe also carries a header:
X-Fissure-Probe: PT2026Q3-417
naming the run and the probe. It is inserted into the request bytes immediately after the request line, so nothing else about the request changes and no framing header has to be recomputed, and it goes on BEFORE the Logger captures the wire, because it is part of what the target receives.
The marker is deliberately identifying. It is the exact opposite of
the evasion Fissure does not do, and it is what makes "which of my
probes did you see" answerable rather than guessed: a log line carrying
PT2026Q3-417 is about one specific request, and the
reconciler needs no heuristic at all.
Turning the marker off asks the harder and often more interesting question: whether the defenders spot UNLABELLED attack traffic. Then reconciliation falls back to matching on the path within a time window, which is weaker, and the coverage number should be read with that in mind.
The run name prefixes every marker, so name the run something that means something in someone else's log pipeline (a ticket id, a date, an engagement code). Only letters, digits, dot and underscore survive, so the marker stays greppable through a shell, a CSV and a JSON string. Naming a run restarts the probe numbering: run plus number is the identity a marker carries.
1.4 Telemetry
What the defenders recorded is imported one record per line. Three shapes parse with no configuration:
JSON object lines. Time from
ts/time/timestamp/@timestamp/date/eventtime(an ISO-8601 string, or a number read as epoch seconds or milliseconds by magnitude); path frompath/uri/url/request_uri/request/http_uri(a full URL is reduced to its path, aGET /a HTTP/1.1request line is split); method frommethod/verb/http_method/request_method; source fromsource/src/product/log_source/logger/sensor/rule_id.Common / combined log format.
10.0.0.5 - - [26/Aug/2026:10:00:02 +0000] "GET /b?q=2 HTTP/1.1" 200 512: the bracketed date is read with its UTC offset, the quoted request gives the method and the path. Telemetry arrives either as text or as a file the Fissure host reads itself (the GUI's Import file, the API's{"file":...},fissure purple import <path>). The file route is the practical one for a real export: the control API caps a request body, so posting a multi-megabyte log meant splitting it, and reading it locally removes that loop.Free text. Anything else is kept verbatim, with an ISO-8601 or bracketed timestamp found anywhere in the line, and a path from a quoted request line, a
uri=/path=/url=key, or the first slash-token. When none of those is there because the line stores the URI percent-encoded (PHPIDS writes the whole thing that way, and so does many a SIEM field), the scan runs again over a decoded copy, which never changes the line the operator sees.
Each event is one of three kinds: a plain log record, an
alert the defender raised, or a block (a
refused request). The kind comes from the line's own words when it has
them (blocked, denied, rejected,
forbidden by, action=drop mean block;
alert, attack, malicious,
detected, signature, modsecurity,
critical, intrusion, anomaly,
threat mean alert) and from the caller's default otherwise.
A bare 403 is deliberately NOT read as a block: an ordinary
403 is not a detection.
Those words are looked for only in what the SENSOR wrote. The quoted
request line, and a JSON line's path value, are masked out of that scan
first, because they are what the CLIENT sent: an access-log line for
GET /x?q=<script>alert(1)</script> says "alert"
without anyone having raised one, and reading it as a detection would
credit the defenders with a catch they never made. An annotation the
sensor appended after the request ("... blocked by rule 942100") sits
outside the mask and still counts.
A line with no time is still usable: it is matched on its path alone.
1.5 Reconciliation and the three outcomes
reconcile walks the imported telemetry and ties each
event to at most one probe, taking the strongest evidence available:
- The marker. The event text carries a probe's marker
as a whole token. This is exact, and nothing else is consulted. The
token check matters:
run-1must not be satisfied byrun-12. - The payload. Failing that, the probe's query string
appears verbatim in the line. A sensor that logs request PARAMETERS
rather than headers (which is what an IDS does) records the payload
itself, and a payload is as identifying as a marker: no ordinary visit
to that page carries it. Short queries are skipped, since
id=1says nothing. - The exact path, query included.
- The path alone, query aside. Deliberately loose, because a log pipeline re-encodes a URI as it pleases; it is enough for the per-technique coverage this feeds, since the probes it can confuse are the neighbouring probes of the same check on the same path.
Ranks 2 to 4 apply only within the time window
(window_ms, five minutes by default) and only when the
methods agree (when both are known). Within a rank, an event prefers a
probe that no event from the SAME SOURCE has claimed yet, and then the
closest in time: N requests to a path produce N log lines, and without
that preference the closest probe absorbs the whole burst while its
neighbours read as unseen. Per source, because an access log and an IDS
legitimately both describe the same probe.
Every probe is reset and re-matched on each pass, so reconciling twice, or reconciling again after importing more telemetry, gives the same answer as reconciling once with everything. Each probe then ends in one of three states:
| State | Meaning |
|---|---|
unseen |
no imported telemetry mentions this probe at all |
logged |
the target recorded the request, but raised nothing about it |
alerted / blocked |
the defenders detected it (and, for blocked, acted on
it) |
The middle state is the one a plain detected/not-detected view loses, and it is the difference between "you have no evidence this happened" and "the evidence is sitting in your logs and nothing read it". Those are different findings with different fixes.
Events that matched nothing are kept and can be listed on their own. They are either the defenders reacting to something that was not the tester, or a correlation that failed; read them before quoting a coverage number.
One thing the reconciler cannot do for you: tell two of YOUR OWN runs
apart on the weak ranks. Import telemetry from a different window and,
if its lines name the same paths and fall inside window_ms,
they will match this run's probes and credit it with detections that
happened during another. The marker is what keeps runs apart, because it
carries the run name (PTA-7 never matches a
PTB probe); the payload and path ranks cannot. So slice the
export to the run's own window, and when two runs are minutes apart,
either keep the marker on or reconcile with a tighter
window_ms. Measured on the DVWA lab: two runs five minutes
apart, the second with the target's IDS switched off, and the first
run's alert log imported into the second showed sqli at 53% instead of
0%.
1.6 Coverage, and the finding
The coverage table is the per-technique rollup: probes sent, how many were logged, alerted on and blocked, and the percentage detected. In the GUI a row nothing caught is painted (red when the probes left no trace at all, orange when they were logged but silent).
Emit findings turns each undetected technique into a finding, so the gap is reported to the owner like any other issue:
- Category
Detection coverage, CWE-778, OWASP A09:2021 Security Logging and Monitoring Failures. - LOW severity when the probes left no trace at all, INFO when they were logged but never alerted on.
- Host-scoped, so a run against one host produces one finding per technique rather than one per URL.
- Evidence naming the run, the counts and the first probe's URL; remediation that covers the case where a rule exists but the traffic never reaches its sensor (a rule on a front end the traffic bypasses, sampling, or a log pipeline that drops the field the rule reads).
Techniques the defenders alerted on or blocked produce nothing: that
is coverage that works, and it is not a finding. Neither does the
traffic bucket (the requests that carried no attack: crawl
fetches, baseline requests), because a defender is right not to alert on
those and a finding saying otherwise would be noise in the report.
Reconcile before emitting, or every probe is still unseen
and every technique reads as a gap.
The finding describes the defenders, not the application. It says nothing about whether the attack would have SUCCEEDED, only that nothing raised it while it was happening, and the finding text says so.
2. Running one
2.1 In the GUI
Open Purple team (the Results category of the toolbar, or the command palette). Then:
- Type a run name and press Set run.
- Leave Tag each probe on (or turn it off to test detection of unlabelled traffic).
- Press Start recording, and do the work: scan, crawl, Repeater, Intruder. The panes refresh themselves every couple of seconds while the store is growing, so a scan in progress shows its probes arriving; Refresh forces one. The probe and telemetry grids list the newest few hundred rows and say so in the status line when there are more, because rebuilding thousands of rows on a live tick costs more than it shows. The tallies always count the whole run, and the whole set is in the store and over the API.
- Get the defenders' output for that window and paste it into the box (or Import file). Say where it came from (source) and what a line means when it does not say (log / alert / block), then Import.
- Reconcile. The coverage table fills in, the probe list shows each probe's state and which source detected it, and the telemetry list shows which probe each line was tied to.
- Emit findings to put the gaps in the Findings view and the report.
The run saves with the project
(<project>/purple.json), and opening the popup in a
later session reads it back on its own when nothing is recorded in
memory yet (a live recording is never overwritten by what is on disk);
Load re-reads it on demand.
2.2 Over the control API
| Method | Path | What |
|---|---|---|
| GET | /api/purple |
status: mode, marker, run, tallies, coverage table |
| POST | /api/purple |
{"op": ...}: start, stop
(record is an alias of start that honours an
"on" flag), marker, run,
import, reconcile, findings,
baseline, diff, save,
load, clear |
| GET | /api/purple/probes |
the recorded probes (limit, technique,
state) |
| GET | /api/purple/events |
the imported telemetry (limit,
unmatched=1) |
Every POST op answers with the full status object, so a caller never has to follow a mutation with a read. See 11_CONTROL_API.md for the field-level detail.
T=$FISSURE_API_TOKEN
curl -s -H "X-API-Key: $T" -H 'Content-Type: application/json' \
-d '{"op":"start","run":"PT2026Q3"}' http://127.0.0.1:8777/api/purple
# ... run the scan ...
curl -s -H "X-API-Key: $T" -H 'Content-Type: application/json' \
--data-binary @- http://127.0.0.1:8777/api/purple <<JSON
{"op":"import","source":"waf","kind":"alert","text":"$(sed 's/"/\\"/g' /var/log/modsec_audit.log | tr '\n' '@')"}
JSON
curl -s -H "X-API-Key: $T" -d '{"op":"reconcile"}' http://127.0.0.1:8777/api/purple
curl -s -H "X-API-Key: $T" -d '{"op":"findings"}' http://127.0.0.1:8777/api/purple(The import body takes the telemetry as a JSON string, so a real
caller builds it with a JSON encoder rather than a shell quote dance;
the MCP bridge and the GUI do exactly that. The control API caps a
request at 64 KB, so a large export is imported in chunks of a few
hundred lines; each import appends, so the chunking is invisible in the
result. Both stores are bounded, at
FISSURE_PURPLE_PROBE_MAX probes and
FISSURE_PURPLE_EVENT_MAX events, with the oldest dropping
past that: a run that sends more probes than the cap measures its most
recent window, not its whole self.)
2.3 From the command line
fissure scan records a run itself, and
fissure purple is the operator half. They compose across
processes because the store is the project's, the same file the popup
and the control API use.
# 1. record: every request this scan sends becomes a probe under the run name
fissure scan https://target.example/ --active --purple PT2026Q3 --format markdown -o report.md
# 2. bring back what the defenders recorded over the same window
fissure purple import /var/log/apache2/access.log --source apache --kind log
fissure purple import /var/log/waf/alerts.jsonl --source waf --kind alert
# 3. reconcile and read the table
fissure purple reconcile # or: fissure purple reconcile --window-ms 60000
fissure purple status # `coverage` is an alias of `status`
# 4. report the gaps (and any regression against the baseline)
fissure purple findings --format markdown -o coverage.md
# 5. keep this run as the baseline the next one is compared against
fissure purple baseline
# ... next engagement, after recording and reconciling again:
fissure purple diff # exit code 1 when a technique regressed, for a CI gatefissure purple reconcile --window-ms <ms> sets the
time window the path-based match ranks use (see section 1.5). It
defaults to 300000 ms (five minutes,
FISSURE_PURPLE_WINDOW_MS); omitting it, or passing 0 or a
negative value, uses that default. Tighten it when two runs sit minutes
apart in the same telemetry.
Recording starts AFTER the --login replay, deliberately:
the login POST carries credentials, and they have no business in a probe
store a report quotes from.
2.4 Over MCP, from an agent
Four tools: purple, purple_op,
purple_probes, purple_events. The engagement
loop is:
purple_op('start', run='PT2026Q3')
... scan / check / repeat ...
purple_op('import', text=<the defender's lines>, source='waf', kind='alert')
purple_op('reconcile')
purple() # the coverage table
purple_probes(state='unseen') # exactly which attacks nothing noticed
purple_op('findings') # report the gaps
The skill's references/mcp_tools.md carries the
argument-level catalog.
2.5 Comparing a run against the last one
One coverage number tells a defender where they stand. What they act on is whether it moved, and that is the one thing a single run cannot show: a rule that was working when it was last measured and is not working now points at something that changed on the defending side (a rule disabled or narrowed, a sensor that stopped receiving the traffic, a log pipeline that dropped the field the rule reads) rather than at anything the tester did.
So a run can be kept as a baseline: the per-technique coverage table, the run name and the time, and nothing else. A later run diffs against it, and every technique comes back as unchanged, improved, regressed, new (the baseline never saw it) or gone (the baseline had it and this run did not send it, which is not evidence of anything except that the comparison did not cover it).
- GUI: Baseline and Diff on the popup's bottom row.
- API:
{"op":"baseline"}and{"op":"diff"}; the diff adds adelta[]row per technique withwas_pct/now_pct. - MCP:
purple_op('baseline')/purple_op('diff'). - CLI:
fissure purple baseline/fissure purple diff, which exits 1 when something regressed so a scheduled run can gate on it.
A regressed technique becomes its own finding
(Detection regression: <technique> coverage fell from X% to Y%),
LOW when detection went to zero and INFO when it merely fell, filed by
the same findings op that files the gaps.
3. What this is not
- It is not a detection-evasion tool. Nothing here is designed to make a probe harder to see; the default behaviour makes probes EASIER to see.
- It is not a measure of the application's security. A technique nothing detected may still have failed against the application, and a technique everything blocked may still be exploitable another way. The two questions are independent, which is why the coverage findings are informational or low and say what they measure.
- It is not a substitute for the defenders' own testing. Fissure reconciles what the operator brings back; if the telemetry export is partial, the coverage number is partial with it, and the unmatched-events list is the first place to notice that.
4. Where it lives in the code
| File | What |
|---|---|
src/fissure_purple.c/.h |
the recorder, the classifier, the telemetry parser, the reconciler, the coverage table, JSON and persistence |
src/fissure_purple_report.c |
where a run meets the rest of Fissure: the store and baseline paths, the coverage-gap findings and the regression findings (kept apart so engine-only tests do not link the project and findings modules) |
src/fissure_cli.c |
fissure scan --purple <run> and the
fissure purple subcommand |
src/fissure_engine.c |
mint, mark, record: the two hooks in execute_once |
src/fissure_checks.c |
the family gate that tags the calling thread with the technique |
src/fissure_control.c |
the four routes |
src/fissure_gui_purple.c/.h |
the popup |
bridge/ |
the client functions and the four MCP tools |
tests/test_purple.c |
the whole loop offline |