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'sn_dns. - SMTP (
fissure_oast_start_smtp, TCP): a minimal SMTP server that reads the token fromRCPT 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 orFissureIast.sink("exec", cmd)around aRuntime.exec. The beacon carries a JavaClass.method(File.java:line)instack, so the finding names the exact vulnerable line, the strongest code location of any of the reference agents. Compile it with a plainjavac(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.AppAutomatic bytecode instrumentation (
-javaagent, no app change): build the agent jar withagents/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.jarFissureIastAgent(the jar'sPremain-Class/Agent-Class, withCan-Retransform-Classes) installs an ASMClassFileTransformerthat rewrites the app's own classes at load time, injecting aFissureIast.autoSink(value, category)call immediately before every CALL SITE of a known sink whose tainted value is the top-of-stackStringargument (Runtime.exec(String), JDBCStatement.execute*,Class.forName,Context/InitialContext.lookup,ScriptEngine.eval). The injected sequence is stack-neutral (DUPthe arg;LDCthe category;INVOKESTATIC autoSink), and ASM'sCOMPUTE_FRAMESrecomputes theStackMapTableso 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 manualFissureIast.sinkAPI.
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
sinkandargsplit out, and says how many of the recorded interactions carried no fields. - Control API:
GET /api/oast/beaconsreturns{"count","hits_total","beacons":[{token,detail,sink?,arg?,lang?,src,channel,created_us}]}.countis the beacon count andhits_totalevery interaction, socount < hits_totalmeans some callbacks were bare. - MCP: the
oast_beaconstool. - C:
fissure_oast_hit_detail(per hit, non-zero return means "not a beacon"),fissure_oast_beacon_count, andfissure_oast_beacon_fieldto read one field out of a detail string (values are URL-decoded).