Docs Add a detection with a WASM plugin
Add a detection with a WASM plugin
Add your own detection to sipnab's diagnosis without forking it: what a sandboxed WebAssembly plugin can and cannot do, what trusting one costs you, and a worked example from crate to finding.
On this page
Add your own detection to sipnab’s diagnosis, without forking it.
A plugin is a small WebAssembly module. It receives one reconstructed dialog and returns findings.
- Its findings appear in
--json-dialogsoutput, in aplugin_findingsarray on the dialog they describe. - The other surfaces (the report, REST, MCP, the TUI) do not show them yet.
When you want one
sipnab already lets you select dialogs:
- the filter DSL picks them by field,
- NDJSON pipes them anywhere,
--alert execreacts to them.
What none of those do is diagnose:
- express a site-specific fault pattern,
- and have sipnab report it as a finding, with evidence, on the dialog it
describes. Today that is the
--json-dialogsoutput only; see Known limits.
That is the one hole a plugin fills.
- If you can already answer your question with a filter or a
jqpipeline, use those. - They need no build step and no trust decision.
What it costs you to trust one
A plugin is a .wasm file. That is exactly the kind of artifact people copy
off the internet. So read this before loading one someone sent you.
A plugin has no imports at all. Not a restricted set — none.
- No WASI, no filesystem, no network, no clock, not even logging.
- The only things crossing the boundary are:
- integers,
- the bytes sipnab copies into the plugin’s own linear memory.
- A module that imports anything fails to instantiate.
| Bounded | How |
|---|---|
| CPU | Fuel metering. A plugin that loops forever gets cut off and reported as a plugin error, and the capture continues |
| Memory at run time | 16 MiB linear-memory ceiling, refused by the engine at the point of growth |
| Memory at load time | sipnab reads the .wasm file through a 16 MiB bound, so it never allocates a length the file chose |
| Output size | 4 MiB per reply |
| Blast radius | A trap, an exhausted fuel budget or a malformed reply fails that dialog’s plugin findings, and nothing else |
What is not bounded is what it reads.
- A plugin sees every dialog sipnab reconstructs. This includes
Authorizationheaders andMESSAGEbodies. - It cannot send them anywhere. It has no imports.
- But it can decide what to report. A finding’s
summaryis a string it chose. - Load a plugin the way you would run a script:
- from someone you trust,
- or after reading it.
Plugins need a build with --features plugins. That feature is not in the
default feature set.
- A stock binary carries no interpreter at all. So
sipnab --versiontells you whether the machine in front of you can load one. - These released builds include it:
- the Linux gnu tarballs,
- the
.deband.rpmpackages, - the macOS builds.
- These do not:
- the static musl tarballs,
- the gnu
-noaudiopackages.
Before you start
- A sipnab with the
pluginsfeature. Every release package has it.sipnab --versionlistspluginsamong the features. A source build needs--features pluginsor--features full. - Rust with the
wasm32-unknown-unknowntarget, to build a plugin:rustup target add wasm32-unknown-unknown. - Nothing on any other system. A plugin runs inside sipnab, on the dialogs sipnab already holds. It needs no SIP server, relay or network change.
- Where findings appear. Only
--json-dialogsprints them, as Known limits says.
Writing one, start to finish
The worked example is crates/sipnab-plugin-example.
It flags short answered calls. These are calls picked up and torn down
inside five seconds. Such a call means one of:
- a bad route,
- a codec the far end rejected,
- wangiri-style fraud dialing.
It is deliberately not a built-in.
- Whether three seconds is a problem depends entirely on your traffic.
- That is the shape a plugin is for.
A crate that builds to WASM
[lib]
crate-type = ["cdylib"]
Target wasm32-unknown-unknown. std works there.
- A
no_stdplugin is smaller. - But it needs its own allocator and panic handler.
- That is a lot of ceremony for a detection.
Three exports, and nothing imported
#[unsafe(no_mangle)]
pub extern "C" fn sipnab_plugin_abi_version() -> i32 { 1 }
#[unsafe(no_mangle)]
pub extern "C" fn sipnab_alloc(len: i32) -> i32 { /* host writes input here */ }
#[unsafe(no_mangle)]
pub unsafe extern "C" fn sipnab_analyze(ptr: i32, len: i32) -> i64 {
// read UTF-8 JSON at (ptr, len), return (out_ptr << 32) | out_len
}
There is no deallocator. That is deliberate rather than an omission.
- sipnab instantiates the module once per dialog.
- It drops the store when
sipnab_analyzereturns. - So the plugin’s entire linear memory goes with it. There is nothing left to reclaim.
- Both documents used to require a
sipnab_deallocthat the host never looked up.- So a plugin that omitted it loaded and ran anyway.
- A requirement nothing checks teaches an author to distrust the rest of the page.
sipnab checks the ABI version at load rather than on first use.
- A plugin built against a later ABI would misread its input and report confident nonsense.
- That is worse than not loading.
Read the input, return findings
Look at the input before writing code. It is the same per-dialog JSON
--json-dialogs emits, with the messages array alongside it:
sipnab -N -I capture.pcap --json-dialogs --no-cli-print | head -1
Return findings in this shape:
{ "findings": [ { "id": "short-answered-call",
"summary": "Call answered and torn down after 2.2s (under 5s) — check routing, codec negotiation, or dial fraud.",
"evidence": [3, 5] } ] }
evidence indexes the dialog’s own message list. It is mandatory.
- sipnab rejects a finding that leaves it empty.
- Every built-in detection names the messages behind it.
- A third-party finding answers to the same rule rather than entering as a lesser citizen.
Build and run it
# Run all of these, in order.
rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown -p sipnab-plugin-example
sipnab -N -I capture.pcap --json-dialogs --no-cli-print \
--plugin target/wasm32-unknown-unknown/release/sipnab_plugin_example.wasm
--plugin is repeatable.
- Each plugin gets its own sandbox.
- A failure in one never stops the capture or the others.
What it printed. On 2026-11-03, sipnab 0.5.232 read
tests/pcap-samples/sip-proxy.pcap with the example plugin. The call there
ends 2.2 seconds after its answer, so the plugin reported it:
sipnab -N -I tests/pcap-samples/sip-proxy.pcap --json-dialogs --no-cli-print \
--plugin target/wasm32-unknown-unknown/release/sipnab_plugin_example.wasm \
| jq -c 'select(.plugin_findings != null) | {call_id, plugin_findings}'
{"call_id":"proxied-call-synth@192.0.2.101","plugin_findings":[{"evidence":[6,9],"id":"short-answered-call","plugin":"sipnab_plugin_example","summary":"Call answered and torn down after 2.2s (under 5s) — check routing, codec negotiation, or dial fraud."}]}
A call the plugin reports nothing for carries no plugin_findings key.
When it does not work
A plugin that does not load does not stop the run. sipnab logs the reason,
reads the capture without that plugin, and exits 1. Every report the run
prints says so, for example --report:
INCOMPLETE RUN — this report does not describe the whole capture:
- 1 of 1 requested --plugin(s) did not load; findings they would have contributed are absent
| sipnab logs | Cause and fix |
|---|---|
plugin <path>: cannot read plugin: <path>: No such file or directory (os error 2) | The path is wrong. cargo build writes the module under target/wasm32-unknown-unknown/release/. |
plugin <path>: not a valid WASM module:, then the parser’s report | The file is not a WebAssembly module. Build with --target wasm32-unknown-unknown, and pass the .wasm file. |
Error: unexpected argument '--plugin' found, and exit 2 | The build left out the plugins feature, so the binary has no --plugin flag. sipnab --version lists the features. Every release package has plugins, through full. A source build needs --features plugins or --features full. |
A plugin that loads and then fails on one dialog drops only its findings for
that dialog, and the run goes on: see plugin {} on {}: {e} in
Error messages.
Where the findings come out
Under a top-level plugin_findings array, separate from signaling_diagnosis.
- Each finding carries the plugin’s own name.
- sipnab fills in that name from the file stem, never the plugin.
- So a plugin cannot attribute a finding to another plugin or to a built-in detection.
That separation is the point. A reader can always tell which findings sipnab stands behind and which came from third-party code.
Against
tests/pcap-samples/sip-over-tcp.pcap,
a call answered and hung up 2.2 seconds later, the example plugin reports:
sipnab -N -I tests/pcap-samples/sip-over-tcp.pcap --json-dialogs --no-cli-print --quiet --plugin target/wasm32-unknown-unknown/release/sipnab_plugin_example.wasm | jq -c 'select(.plugin_findings != null) | {call_id, plugin_findings}'
{"call_id":"over-tcp-synth@198.51.100.100","plugin_findings":[{"evidence":[3,5],"id":"short-answered-call","plugin":"sipnab_plugin_example","summary":"Call answered and torn down after 2.2s (under 5s) — check routing, codec negotiation, or dial fraud."}]}
A dialog the plugin has nothing to say about carries no plugin_findings.
Check that it worked
Three facts show that a plugin loaded and ran. Each check ran on 2026-11-11 with sipnab 0.5.245, from the repository root, after the build in Build and run it.
The log names each plugin that loaded. Run without --quiet, and keep the
log lines that say so:
sipnab -N -I tests/pcap-samples/sip-proxy.pcap --json-dialogs --no-cli-print --plugin target/wasm32-unknown-unknown/release/sipnab_plugin_example.wasm 2>&1 >/dev/null | grep 'loaded plugin'
INFO sipnab::app::batch: loaded plugin sipnab_plugin_example
The line starts with the time of the run. A plugin that did not load has no such line.
The findings carry the plugin’s ids. The call in this capture ends 2.2 seconds after its answer, so the example plugin reports it:
sipnab -N -I tests/pcap-samples/sip-proxy.pcap --json-dialogs --no-cli-print --plugin target/wasm32-unknown-unknown/release/sipnab_plugin_example.wasm | jq '.plugin_findings[]?.id'
"short-answered-call"
The exit status is 0. A run with a plugin that did not load exits 1, and
the next section lists the reasons.
When a plugin does not load
sipnab still reads the capture and prints every dialog, without the findings
that plugin would have added. It logs the reason, and the run exits 1. The
last line of --json-dialogs says so as well:
{"sipnab_run":{"archives":{"cut_short":false},"files":{"given":1,"not_reached":0,"read_in_full":1,"skipped":0,"stopped_early":0},"input_complete":false,"plugins":{"failed":1,"loaded":0,"requested":1},"port_gate":{"sip_outside_portrange":0,"sip_outside_ws_ports":0},"reasons":["1 of 1 requested --plugin(s) did not load; findings they would have contributed are absent"],"retention":{"messages_dropped":0}}}
| Logged reason | Cause | What to do |
|---|---|---|
plugin <path>: cannot read plugin: <path>: No such file or directory | The path is wrong | Give the path to the .wasm file |
plugin <path>: not a valid WASM module | The file is not WebAssembly, or a build for another target | Build for wasm32-unknown-unknown |
| An ABI version refusal | Someone built the plugin against another plugin ABI version | Rebuild it against the ABI this sipnab reports |
plugin <name> on <Call-ID>: <reason> | The plugin loaded, then trapped, ran out of fuel or memory, or returned the wrong shape for one dialog | That dialog prints without the plugin’s findings, and the other dialogs keep theirs. Fix the plugin |
sipnab refuses the command line, exit 2, at --plugin | A build without the plugins feature has no --plugin flag | Use a build that lists plugins in sipnab --version |
Error messages explains each message in full.
Known limits
- Findings reach
--json-dialogsonly. The report, REST, MCP and the TUI do not show them. - One hook point: post-dialog analysis.
- There is deliberately no packet-level hook.
- Handing every packet to an interpreter would undo the capture path’s performance, and the benchmarks with it.
- Plugins observe rather than mutate.
- A plugin that could rewrite a dialog would make every other surface’s output unattributable.
See also
- Design specification — the ABI in full, the safety model, and why WASM rather than an embedded scripting runtime.
- CLI reference — the
--pluginflag. - Installation — building with
--features plugins.