Fissuredocumentation v5.3.1
On this page

IAST beacon protocol (out-of-band canary correlation)

IAST (interactive application security testing) patches the bytecode of the target application so that when a scanner payload carrying a unique canary reaches a dangerous sink (SQL exec, file open, command exec, deserialization, ...), the instrumented app reports back out-of-band, confirming an otherwise-blind vulnerability with no false positives.

The instrumentation agents are language- and runtime-specific (a JVM java.lang.instrument agent, a .NET startup-hook weaver, Node/Python/Ruby/PHP monkey-patches). Fissure ships three pieces: the collector (the OAST listener), an open beacon protocol an agent can target, and six reference agents under agents/ (Node.js, Python, Ruby, PHP, Java, .NET; see "Reference agents" below). The collector and protocol are independently useful for blind SSRF / XXE / RCE, where the target itself (not an agent) reaches back.

The collector

FISSURE_OAST (src/fissure_oast.c) mints unique per-probe tokens and records every callback that reaches it, correlated by the token (see docs/05_WEBSITE_SCANNER.md, the OAST helper). It listens on three channels, each recording the same token store so fissure_oast_token_seen correlates a hit regardless of how it arrived:

  • HTTP (always): a loopback (or bound-address) HTTP listener; the token is the first path segment.
  • DNS (fissure_oast_start_dns, UDP): answers a query for <token>.<domain> with an A record pointing at the listener host and records the token; catches blind bugs that only resolve a name (DNS exfil, some XXE/SSRF). The DNS wire codec is Nilorea's n_dns.
  • SMTP (fissure_oast_start_smtp, TCP): a minimal SMTP server that reads the token from RCPT TO:<token@domain>; catches email-triggering flows.

Start it from the toolbar OAST popup. Set an interaction Domain (persisted as oast_domain) to enable DNS/SMTP canaries and their channels; the popup's Mint button then emits an HTTP URL plus a DNS and an SMTP canary, and the interaction grid shows the channel (Chan column) per hit. For a remote target, bind to an address the target can reach; DNS/SMTP need their privileged ports (53/25, so CAP_NET_BIND_SERVICE or root) and the domain delegated to this host (an NS record for DNS, an MX record for SMTP). An aggressive scan borrows the running listener (fissure_gui_oast_handle) so the active checks can mint canaries and correlate callbacks (chk_oast in src/fissure_checks.c).

The canary

The scanner mints a canary URL per injectable point:

http://<oast-host>:<oast-port>/<token>

<token> is an opaque, unguessable string unique to that probe (fissure_oast_mint). The scanner injects the URL as the probe value and later asks fissure_oast_token_seen(token) whether a callback arrived. A plain blind SSRF/XXE/RCE makes the target fetch the bare URL, which is already proof.

When an interaction domain is configured, chk_oast additionally injects a DNS canary at each point: a URL whose host is <token>.<domain>. A resolve-only SSRF/XXE (egress firewalled, or the request validated after resolution) that never completes the fetch still triggers a DNS lookup, which the DNS channel records and correlates. The finding names the channel (HTTP or DNS) it fired on. SMTP canaries stay a manual Mint (they target email-sending flows, not injection-point probing).

The beacon (how an agent reports a sink)

An instrumentation agent that observes the canary token reaching a sink beacons to the canary URL with the sink details as query parameters:

GET /<token>?sink=<sink>&arg=<detail>[&stack=<frame>] HTTP/1.1
Host: <oast-host>:<oast-port>

Recommended fields (all optional except the token in the path):

Field Meaning
sink The sink category the canary reached, e.g. sql, exec, file, deserialize, ssrf.
arg A short detail: the tainted argument, table, path, or command fragment.
stack An optional top stack frame (class/method, and file:line where the runtime provides it) for triage, so the finding names the exact vulnerable line.
src An optional tainted-source name (e.g. param:q, header:Referer) when a front-end filter tags where the canary entered before it reached the sink.

The listener captures the whole query string as the interaction's structured detail (fissure_oast_token_detail), which the scanner surfaces in the finding evidence: the canary check emits a CERTAIN Server-Side Request Forgery finding (CWE-918) naming the injection point and, when present, the beaconed sink. The token in the path is what correlates the beacon back to the exact probe, so an agent needs only to echo the canary URL and append its fields. The DNS and SMTP channels record a channel-appropriate detail too: a DNS hit carries the resolved record type (qtype=<n>) and an SMTP hit the envelope sender (from=<MAIL FROM>).

There is no authentication or encoding requirement beyond a normal HTTP GET, so a minimal agent in any language can implement it in a few lines. Beyond the reference agents below, any agent that follows this contract works with the collector.

Reference agents

To make the contract concrete, the repository carries reference agents for the common server-side runtimes (the dynamic interpreters, the JVM and the CLR). They are plain source files, not shipped binaries, and Fissure never loads or runs them: you opt in by loading one into an application you are authorized to test. Each validates the beacon protocol end to end (the regression tests tests/test_iast_agent*.c drive them against a live FISSURE_OAST, as do tests/test_iast_java_auto.c and tests/test_iast_dotnet_auto.c for the automatic JVM and .NET modes, and skip cleanly when the interpreter or compiler is absent).

Every agent behaves the same way: on load it monkey-patches a small set of sinks and, when a value carrying a canary URL (the OAST base plus a token) reaches one, beacons the token with the sink category and a short argument detail, then calls through to the original. They observe only: they never alter the app's behaviour, and they are inert unless FISSURE_OAST_URL is set. FISSURE_IAST_DEBUG=1 logs each beacon to stderr.

Node.js (agents/nodejs/fissure-iast-agent.js)

Load it with --require (or NODE_OPTIONS) and point it at the listener's base URL:

FISSURE_OAST_URL=http://127.0.0.1:9000 \
  node --require ./agents/nodejs/fissure-iast-agent.js your-app.js
Sink group Patched functions Beacon sink
Command child_process exec / execSync / execFile / execFileSync / spawn / spawnSync exec
Filesystem fs readFile[Sync] / writeFile[Sync] / appendFile / open[Sync] / create{Read,Write}Stream file
Outbound http/https request / get ssrf
Code eval vm runInNewContext / runInContext / runInThisContext / compileFunction eval
SQL pg / mysql / mysql2 / sqlite3 / better-sqlite3 query methods (via a require hook) sql

Python 3 (agents/python/fissure_iast_agent.py)

Run a target under the agent (analogous to node --require), or import it first:

FISSURE_OAST_URL=http://127.0.0.1:9000 \
  python3 agents/python/fissure_iast_agent.py your_app.py
Sink group Patched functions Beacon sink
Command os.system / os.popen / subprocess.Popen (covers run/call/check_*) exec
Filesystem builtin open / os.open file
Outbound urllib.request.urlopen / http.client.HTTPConnection ssrf
Code eval builtin eval / exec eval
Deserialize pickle.loads / pickle.load / marshal.loads deserialize
SQL any DB-API connect() -> cursor execute/executemany (via an import hook) sql

Ruby (agents/ruby/fissure-iast-agent.rb)

Load it with the -r require flag (analogous to node --require):

FISSURE_OAST_URL=http://127.0.0.1:9000 \
  ruby -r ./agents/ruby/fissure-iast-agent.rb your_app.rb
Sink group Patched functions Beacon sink
Command Kernel#system / backtick / Kernel#exec / IO.popen exec
Filesystem File.read / File.open / File.write file
Outbound Net::HTTP#request ssrf
Code eval instance_eval / class_eval / module_eval eval
Deserialize Marshal.load / Marshal.restore deserialize
SQL sqlite3 / mysql2 / pg query methods (via a require hook) sql

PHP (agents/php/fissure-iast-agent.php)

Load it as an auto-prepended file (it runs before the app):

FISSURE_OAST_URL=http://127.0.0.1:9000 \
  php -d auto_prepend_file=agents/php/fissure-iast-agent.php your_app.php

PHP cannot intercept built-in functions from pure userland, so automatic hooking needs the uopz extension (or runkit7). With uopz loaded the agent hooks the sinks below; without it, auto-instrumentation is off but the agent still exposes fissure_iast_sink($sink, ...$args) for manual instrumentation (call it at a sink, e.g. fissure_iast_sink('sql', $query)).

Sink group Hooked functions (uopz) Beacon sink
Command exec / system / shell_exec / passthru / proc_open / popen exec
Filesystem file_get_contents / fopen / file_put_contents / readfile / file file
SQL mysqli_query / pg_query / PDO::query / PDO::prepare / mysqli::query sql
Deserialize unserialize deserialize

Java / JVM (agents/java/FissureIast.java + FissureIastAgent.java)

The Java reference has two modes, mirroring the PHP agent's uopz/manual split:

  • Manual (always available, no dependency): call FissureIast.sink(category, args) at a sink, e.g. FissureIast.sink("sql", query) around a JDBC call or FissureIast.sink("exec", cmd) around a Runtime.exec. The beacon carries a Java Class.method(File.java:line) in stack, so the finding names the exact vulnerable line, the strongest code location of any of the reference agents. Compile it with a plain javac (no external jars):

    javac -d out agents/java/FissureIast.java your/App.java
    FISSURE_OAST_URL=http://127.0.0.1:9000 java -cp out your.App
  • Automatic bytecode instrumentation (-javaagent, no app change): build the agent jar with agents/java/build.sh (needs a JDK + the ASM core library) and attach it:

    sh agents/java/build.sh fissure-iast.jar
    FISSURE_OAST_URL=http://127.0.0.1:9000 java -javaagent:fissure-iast.jar -jar yourapp.jar

    FissureIastAgent (the jar's Premain-Class/Agent-Class, with Can-Retransform-Classes) installs an ASM ClassFileTransformer that rewrites the app's own classes at load time, injecting a FissureIast.autoSink(value, category) call immediately before every CALL SITE of a known sink whose tainted value is the top-of-stack String argument (Runtime.exec(String), JDBC Statement.execute*, Class.forName, Context/InitialContext.lookup, ScriptEngine.eval). The injected sequence is stack-neutral (DUP the arg; LDC the category; INVOKESTATIC autoSink), and ASM's COMPUTE_FRAMES recomputes the StackMapTable so the class still verifies; the app runs the original sink unchanged. The JDK, ASM, and the agent's own classes are skipped. On any transform error the class is left untouched, so the agent never breaks the app. Multi-argument sinks (whose tainted value is not on top of the stack) stay on the manual FissureIast.sink API.

A servlet filter is the natural front end. agents/java/FissureIastFilter.java (a jakarta.servlet.Filter; change the imports to javax.servlet for the older namespace) scans each request's parameters and headers for a canary and calls FissureIast.noteSource("param:<name>") / noteSource("header:<name>"), so a later sink beacon carries src=param:q, naming where the canary entered as well as the sink it reached. The filter never beacons on its own and never alters the request or response; it needs the servlet API on its classpath to compile (the core FissureIast.java does not).

Sink group Where to call FissureIast.sink Beacon sink
Command Runtime.exec / ProcessBuilder.start exec
Filesystem new FileInputStream / Files.readAllBytes / file opens file
Outbound URL.openConnection / HttpClient.send ssrf
Code eval script engine eval (Nashorn / GraalVM / JEXL / SpEL) eval
Deserialize ObjectInputStream.readObject deserialize
SQL JDBC Statement.execute* / Connection.prepareStatement sql

.NET / CLR (agents/dotnet/FissureIast.cs)

The .NET reference mirrors the Java agent and, like it, is FULLY AUTOMATIC. Manual: call FissureIast.Sink("sql", query) at a sink. Automatic: set DOTNET_STARTUP_HOOKS to the built FissureIast.dll and the app needs no Fissure call at all.

The two runtimes reach that from opposite directions, because the CLR offers managed code no load-time class transformer. The JVM agent rewrites every CALLER of a sink as its class loads; FissureIastWeaver instead detours the SINK ITSELF, once, with a prefix that inspects the argument and then lets the original run. The observable behaviour is the same (the app is unchanged, the beacon carries sink, argument and frame) and it covers callers the JVM approach cannot, since an assembly loaded later is detoured too. Detouring needs a patch library (Harmony), which agents/dotnet/build.sh restores and which the weaver resolves by REFLECTION, so the manual half stays dependency-free and the automatic half simply reports itself off when the library is absent - the same shape as the JVM agent's dependency on ASM. Covered end to end by tests/test_iast_dotnet_auto, where the target calls Type.GetType(canary) and nothing else. See agents/dotnet/README.md.

Both fully-automatic modes ship and are regression-tested: the JVM java.lang.instrument transformer (agents/java/FissureIastAgent.java, built on ASM, tests/test_iast_java_auto.c) and the .NET startup-hook weaver (agents/dotnet/FissureIastWeaver.cs, loaded through DOTNET_STARTUP_HOOKS, tests/test_iast_dotnet_auto.c). Both follow the same beacon contract. See agents/README.md.

Limitations

  • Reachability: for a real remote target, the OAST listener must be bound to an address the target can reach (the same constraint as any OAST-style service); loopback works for lab and CTF targets.
  • The scanner waits only briefly after each injection (FISSURE_CHK_OAST_POLL_MS), which catches the common inline-fetch case; deferred/async callbacks that arrive much later are not correlated back to the probe (they still appear as generic interactions in the OAST popup).
  • DNS and SMTP OAST channels are supported (they need a delegated authoritative domain and privileged ports 53/25); HTTP callbacks work on loopback with no delegation.

Reading the beacons back

A beacon is recorded as an ordinary OAST interaction whose query string carries the agent's fields, so it lands in the same list as a bare SSRF or XXE callback. That list alone cannot tell the two apart, which matters: a bare callback proves something reached the collector, while a beacon names the sink the canary reached and its argument.

The beacons are therefore listable on their own, on all four surfaces:

  • GUI: the OAST popup's "IAST beacons" button lists them with sink and arg split out, and says how many of the recorded interactions carried no fields.
  • Control API: GET /api/oast/beacons returns {"count","hits_total","beacons":[{token,detail,sink?,arg?,lang?,src,channel,created_us}]}. count is the beacon count and hits_total every interaction, so count < hits_total means some callbacks were bare.
  • MCP: the oast_beacons tool.
  • C: fissure_oast_hit_detail (per hit, non-zero return means "not a beacon"), fissure_oast_beacon_count, and fissure_oast_beacon_field to read one field out of a detail string (values are URL-decoded).