Fissuredocumentation v5.3.1
On this page

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 from path / uri / url / request_uri / request / http_uri (a full URL is reduced to its path, a GET /a HTTP/1.1 request line is split); method from method / verb / http_method / request_method; source from source / 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:

  1. 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-1 must not be satisfied by run-12.
  2. 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=1 says nothing.
  3. The exact path, query included.
  4. 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:

  1. Type a run name and press Set run.
  2. Leave Tag each probe on (or turn it off to test detection of unlabelled traffic).
  3. 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.
  4. 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.
  5. 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.
  6. 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 gate

fissure 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 a delta[] row per technique with was_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