CLI Reference - NormB/sipnab GitHub Wiki

Quick start: sipnab -I capture.pcap to analyze a file, or sudo sipnab for live capture on the default interface. Add -N for non-interactive output.

Complete flag reference for sipnab. This page groups flags by function.

A first run needs only a handful of these flags:

• -I, --input reads packets from a capture file, a directory of them, an archive of them, or a glob, instead of live capture. It reads stored vCon containers too.
• -d, --device names the network interface to capture on.
• -N, --no-tui turns on non-interactive mode, with no TUI. The batch and output flags require it.
• --report generates a summary report after capture completes. Requires -N.
• --json prints output as NDJSON, one JSON object per line. Requires -N.
• --filter takes a Filter DSL expression or a diagnostic alias name, such as codec-asym or late-media, and a named filter as @name.

The Since column names the first sipnab release whose command line accepted the flag. The flag may have its current name or one of its aliases.

• The column comes from src/cli.rs at each release tag, v0.3.0 onward.
• The pre-release tags v0.1.0-alpha and v0.2.0-beta do not count as releases.
• A release may remove a flag and a later release may restore it. That flag keeps the release it first appeared in.
• The changelog lists four version numbers that were never tagged or released: 0.3.1, 0.4.1, 0.5.76 and 0.5.111. A flag first added in one of them shows the next release.
• Unreleased means no release has the flag yet. It is in the source but not in a published version.

CLI flags always override config file values (see config-reference.md).

• Boolean flags default to off (false) unless otherwise noted.
• For task-oriented recipes rather than a flag catalog, start with examples.md.

A few flag combinations to get productive fast.

• For the full task-oriented collection, see the Cookbook. It covers triage, filtering, recording, security and HEP.
• For symptom-driven diagnostics, see Troubleshooting.
• This page is otherwise a flag reference (grouped below).

Start by listing every failed call in the pcap. The Call-IDs worth chasing come from this list.

sipnab -N -I capture.pcap --filter "state == 'Failed'"

With one of those Call-IDs in hand, print just that dialog's call flow.

• --no-cli-print is what makes it just that.
• On its own, --call-report appends the report to the whole capture's per-message dump.
• So without it, the report you came for arrives after every message in the file.

sipnab -N -I capture.pcap --call-report "abc123@host" --no-cli-print

When the finding belongs in a ticket, write the same report as Markdown to a file. Do not read it on the terminal.

• Keep --no-cli-print here too.
• Without it, report.md opens with hundreds of lines of raw SIP before its first heading.

sipnab -N -I capture.pcap --call-report "abc123@host" --markdown --no-cli-print > report.md

Watch live traffic for calls that are already degraded:

• MOS below 3.0, or
• audio flowing in only one direction.

sudo sipnab -N -d eth0 --filter "rtp.mos < 3.0 OR one_way == true"

Feed the same set of problem calls into a monitoring pipeline as NDJSON. Keep a copy on disk at the same time.

sudo sipnab -N -d eth0 --problems --json | tee /var/log/sipnab/problems.ndjson

Hand each quality drop to an external alerting script rather than reading it yourself.

• --exec-rate-limit bounds the invocations per second.
• So one bad trunk cannot fork a process per stream.

sudo sipnab -d eth0 --on-quality-exec "/usr/local/bin/pagerduty-alert.sh" \
  --quality-threshold 3.0 --exec-rate-limit 5

Find the calls whose setup took longer than three seconds. The output is NDJSON for whatever consumes it next.

sipnab -N -I capture.pcap --filter "pdd > 3.0" --json

The --slow-setup alias asks the same question against the run's own post-dial delay threshold.

• The threshold is 11 seconds, unless --pdd-threshold or [diagnosis] post_dial_delay_secs moves it.
• So a quick check needs no filter expression at all.

sipnab -N -I capture.pcap --slow-setup --report

Detect SIP scanning and append it in fail2ban's format to the log its jail reads.

• --kill-scanner is what detects.
• --fail2ban only chooses the format, so leaving it out leaves the log empty.

Every example below passes -N, and that is not a style choice.

• Only the headless single-capture path builds the detectors.
• Two paths run without them:
  • the interactive TUI (the default when you leave -N off),
  • the --cores N parallel reader.
• Ask for detection on either and sipnab warns at startup. The warning says it accepts the flag and ignores it.
• Without that warning, an empty finding list reads as an all-clear.

sudo sipnab -N -d eth0 --kill-scanner --fail2ban >> /var/log/sipnab/scanners.log

Before that log reaches a jail, run the same detectors over a capture of an ordinary hour. Read the list of addresses they would ban.

• On a carrier trunk it routinely names your own SBCs.
• The reason: the enumeration signature and a busy hunt group look alike.

sipnab -N -I capture.pcap --kill-scanner --fail2ban \
  | grep -oE 'src=[^ ]+' | sort | uniq -c | sort -rn

Audit a capture for digest credentials that went out where anyone could read them.

sipnab -N -I capture.pcap --digest-leak

Run the whole sweep at once: scanners, fraud heuristics, and registration floods. Alerts go to both syslog and structured JSON.

sudo sipnab -N -d eth0 --kill-scanner --fraud-detect --reg-flood \
  --alert syslog --alert json --syslog

Print a display filter to paste into Wireshark after opening the capture.

sipnab -N -I capture.pcap --wireshark

Or print a tshark-compatible filter string. Use this when the next step is a shell pipeline rather than the Wireshark GUI.

sipnab -I capture.pcap --tshark-filter 'sip.from.user == "1001"'

Audio export is a TUI workflow. See Keybindings.

Count failures by response code. The dominant one is then obvious.

sipnab -N -I capture.pcap --filter "state == 'Failed'" --json \
  | jq -r 'select(.is_request == false) | .status_code' \
  | sort | uniq -c | sort -rn

List every distinct User-Agent the capture saw. This finds the odd endpoint out.

sipnab -N -I capture.pcap --json \
  | jq -r '.ua // empty' | sort -u

Stop after a fixed packet count and summarize the capture.

sipnab -N -d eth0 -n 1000 --report

Roll to a new pcapng every 50 MiB. Then a long capture does not become one file too large to open.

sipnab -d eth0 -O /var/captures/sip.pcapng --pcapng --split filesize:50

Keep only the newest four of those files. Then a long capture fits a fixed amount of disk.

• --split-keep deletes the older files as rotation creates new ones.
• It deletes only the files this run wrote.

sipnab -d eth0 -O /var/captures/sip.pcapng --pcapng --split filesize:50 --split-keep 4

The drop user creates the output files. Run as root, sipnab does this:

• It opens the capture device.
• It drops privileges to nobody (or the --user you name) before it creates the -O file.
• It creates every --split file later still.
• Right after the drop, before it reads the first packet, it checks that the drop user can create these:
  • the -O file,
  • --export-vcon-dir,
  • --vcon-out,
  • --redact-map.

So a directory only root may write ends the run at startup with exit code 1. One example is a directory made with a plain sudo mkdir:

Failed to create output file '/var/captures/sip.pcapng': Permission denied (os error 13). sipnab dropped privileges to user 'nobody' before opening output; make the directory writable by that user (e.g. install -d -o nobody <dir>), pass --user <name> for a user that can write there, or --no-priv-drop.

There are three fixes:

• Give the directory to the drop user with sudo install -d -o nobody /var/captures.
• Pass --user naming an account that can already write it.
• Keep root for the whole run with --no-priv-drop.

--split-keep deletes capture files. sipnab deletes nothing unless you pass the flag. It deletes nothing at --split-keep 0. The reason: a capture is very often the only copy of the evidence.

• sipnab deletes only the files the running process created and named.
• It never lists the directory. So a file left beside them stays where it is:
  • a file from an earlier run, from another tool, or from you,
  • however closely its name resembles a rotation.

A run that dies mid-capture leaves behind whatever it had not yet deleted.

• The next run starts its own list and never adopts those files.
• sipnab names each file it deletes in the log.
• It counts them in the closing summary.

Capture across every interface at once. Timestamp each message relative to the one before it.

• On Linux the any pseudo-device is what makes this every interface.
• --multi-device is for naming a specific list, as below.

sipnab -d any --delta-time

Capture on two named interfaces instead, one libpcap handle each.

sipnab -d eth0,eth1 --multi-device --delta-time

Tip: Every output flag (--json, --report, --fail2ban, etc.) needs -N. Think of it as "non-interactive mode". It disables the TUI and writes to stdout instead.

The auto-generated filter looks through VLAN, QinQ, PPPoE and MPLS. With no filter of your own on a live capture, sipnab builds one from --portrange.

• It also matches SIP inside these, on Ethernet and on Linux cooked captures:
  • one VLAN tag,
  • QinQ,
  • PPPoE Session,
  • one or two MPLS labels.
• A bare portrange would match none of that traffic.
• See How the generated filter reaches encapsulated SIP for the offsets it probes and its two limits.

The auto-generated filter admits the media too. RTP travels on whatever ports SDP negotiated.

• So the filter admits UDP on any port whose first payload byte marks RTP version 2. This covers IPv4 and IPv6 without extension headers.
• Media inside a VLAN tag or a tunnel is not admitted. Name it in a filter of your own.
• With --no-rtp the filter stays signaling-only. Nothing would read the media.
• With --hep-listen as well as -d, the interface takes the media only.
  • The HEP mirror already delivers the signaling.
  • Taking it off the wire too would deliver every message twice.
• Up to 0.5.192 the filter admitted signaling only. A default live capture then measured no media at all.

UDP tunnels are opt-in. GTP-U, VXLAN and GENEVE are not covered by default, and sipnab says so at startup.

• BPF cannot parse a variable-length GTP-U extension-header chain to reach the inner port.
• So the only way to cover them is to capture everything on the port. See --capture-tunnels.

A filter you supply is never rewritten. It goes to pcap_compile exactly as typed. If it looks encapsulation-blind, sipnab says so once. It still uses your expression.

What you get when you omit -d. The default is not the same everywhere, and the difference decides whether you see loopback traffic:

Platform	Default	Scope
Linux	the any pseudo-device	every interface at once, loopback included
macOS / BSD	libpcap's default device, from the routing table; otherwise the first non-loopback interface	one interface

On Linux this default is deliberate.

• A SIP proxy often talks to itself over loopback. So capturing only eth0 silently misses it.
• Pass -d any to say so explicitly.
• Promiscuous mode does not apply to any. So --no-promisc changes nothing there.

On macOS you get a single interface.

• If SIP is not on the one libpcap picked, you see nothing.
• The capture then looks merely quiet.
• Name -d explicitly.

Reading a set of files: order comes from the packets, not the names.

• tcpdump -C 100 -W 10 writes a ring buffer, tg.pcap0 through tg.pcap9.
• It then wraps and overwrites the oldest file in place.
• A real set measured for this feature ran tg.pcap7, tg.pcap8, tg.pcap9, tg.pcap0 … tg.pcap6 in time order.
• The numeric suffix records where tcpdump was in its cycle. It does not record when the packets arrived.

So sipnab sorts by each file's first packet timestamp.

• Neither lexicographic nor natural-numeric filename order reconstructs that capture.
• Replaying it out of order corrupts every timing derivation. These all assume timestamps only move forward:
  • post-dial delay,
  • setup time,
  • retransmission detection,
  • the RFC 3261 Timer B/C/H bounds.

sipnab recognizes a capture by opening it, not by its extension.

• tg.pcap0 has the extension pcap0. Plenty of captures have none at all.
• It decompresses gzip members transparently. So a directory holding both .pcap and .pcap.gz needs nothing special.

A file you name directly with -I that sipnab cannot read is an error. sipnab may instead discover a file by expanding a directory or glob. It skips such a file with a warning, because directories hold other things.

Why it matters beyond tidiness: a call's INVITE may land in one file and its BYE in the next.

• Reading a split capture as a set is the only way to see that call.
• Analyzed one file at a time, that call appears as one that never ends plus a stray BYE. Neither half is the truth.
• On the 10-file, 921 MB set above, 2271 of 20512 calls (11%) spanned a boundary.

-I and -d are alternatives, not companions. sipnab accepts both, and the FILE wins.

• sipnab reads the file and never opens the interface.
• The output looks like a normal run.
• sipnab warns on stderr when you do this.
• To switch a file command to live capture, remove -I rather than adding -d beside it.

--portrange decides how much of the file you analyze. The default, 5060-5061, is narrow.

• SIP on other ports is ordinary. Carriers and SBCs use 5070, 5080 and others routinely.
• A capture from a real trunk commonly carries a large share of its signaling outside the default.

Reading a file, sipnab skips any SIP message whose source and destination ports both fall outside the range.

• A skipped message reaches no message count, no dialog, and no output format.
• So every total you read describes the range and not the capture. So does every ratio you compute from one.
• sipnab counts what it skipped. It says so on stderr and at the end of the run.
• It names the busiest ports, so there is something to widen to.
• --report names the count in its INCOMPLETE RUN block:

NOT ANALYZED: 1 further SIP message(s) were seen on ports outside --portrange
and are in none of the totals above. Busiest: 8090 (1). Re-run with
--portrange 1-65535 to include them.

--portrange 1-65535 analyzes everything the capture holds. Reach for it first on an unfamiliar capture. Narrow it once you know what is in there.

Live capture is different, and worse.

• With no explicit BPF filter, sipnab compiles the range into the filter.
• So the kernel drops the traffic before sipnab sees it.
• Nothing downstream, this counter included, can report what went missing.
• Set the range correctly before the capture, because no rerun recovers it.

NOT DECODED is the other line to read before the totals.

• --portrange is about SIP sipnab chose not to analyze.
• This line is about frames it could not read at all:
  • an unsupported link type,
  • an EtherType carrying no IP,
  • an IP protocol that is no transport,
  • a truncated frame,
  • a decode error.
• Such a frame counts as a packet (it arrived). It reaches no message, dialog or stream.
• So on its own, the summary reports the same thing in two cases: the capture held no SIP, or sipnab understood none of it:

NOT DECODED: 49 of 49 frame(s) (100.0%) produced nothing and are in none of
the counts above. Reasons: unsupported link type 0 (49). NOTHING IN THIS
CAPTURE WAS READ — every frame failed to decode, so the totals above describe
no traffic whatsoever and a zero among them is not evidence of absence.

Every reason carries the number that identifies it. That number is what you act on.

• unsupported link type 0 says the file is DLT_NULL.
• editcap -T ether in.pcap out.pcap converts it.

A small count is normal. ARP is undecodable by definition and appears on any Ethernet capture. So read the share, not the count.

When the share is high, sipnab additionally refuses to state "No SIP traffic found" as a finding. It has no basis for one. The same breakdown appears in two more places:

• as a NOT DECODED (capture-wide) section in --report,
• as sipnab_capture_undecodable_frames_total{reason} plus sipnab_capture_undecoded_fraction on /metrics.

docs/troubleshooting.md tables what each reason means and what to do about it.

Examples

• sipnab -N -I capture.pcap --sandbox best-effort --report — analyze a capture with the filesystem bounded to the input and the crash directory. On a kernel without Landlock this warns and analyzes anyway, which is the point of best-effort

• sudo sipnab -N -d eth0 -O /var/captures/live.pcap --sandbox required — refuse to capture at all unless the ruleset installed. Use this where an unsandboxed capture is worse than none. The run exits non-zero and names the reason rather than starting

• sipnab -N -I capture.pcap --seccomp log — read a capture with every system call recorded. The filter refuses nothing, so the analysis matches a run without the flag. What you get is the record of which calls a file-reading run makes

• sudo sipnab -N -d eth0 --count 5000 --seccomp log && auditctl -s — record the calls a LIVE capture makes, bounded by --count so the log cannot run away, then check where the records went. A connected audit daemon has them in ausearch -m SECCOMP. A pid of 0 means they are in dmesg

• sipnab -N -I capture.pcap --rtp --report — analyze the media too when your config file sets [capture] no_rtp = true

• sipnab -N -I capture.pcap --no-rtp --rtp --report — the last of the pair wins, so this run analyzes RTP

• sipnab -N -I capture.pcap -e INVITE udp port 5060 — the sngrep habit sngrep INVITE udp port 5060, written for sipnab: the match expression goes after -e and the words after the options are the capture filter

• sipnab -N -I 0192d6a4-1b2c-8d3e-9f40-5a6b7c8d9e0f.vcon.json --vcon-key recipient.key --json-dialogs — analyze an encrypted vCon sipnab wrote: decrypt it with the recipient's private key, verify its signature, and print its dialogs

• sipnab --mcp -N -I capture.pcap --vcon-key /etc/sipnab/vcon-recipient.key — serve the MCP tools with a key, so analyze_vcon and validate_vcon read encrypted containers an agent hands over

• sipnab -N -I signed.vcon.json --vcon-signer-ca signing-ca.pem --report — analyze a signed vCon only when the CA in signing-ca.pem issued its signing certificate

• sipnab -N -I sealed/ --vcon-key recipient.key --vcon-signer-ca system --json-dialogs — read a directory of encrypted vCons, each only when a CA in the host's CA bundle issued its signer

• sipnab -N -I signed.vcon.json --vcon-signer-sha256 40:97:43:61:0C:C7:47:BD:40:82:E2:28:1C:53:A6:54:88:74:EB:E7:A7:2B:E4:A3:C8:CB:1B:CA:C8:97:BC:D6 --json-dialogs — analyze a signed vCon only when one known certificate signed it

• sipnab -N -I sealed.vcon.json --vcon-key recipient.key --vcon-signer-ca signing-ca.pem --vcon-signer-sha256 409743610cc747bd4082e2281c53a6548874ebe7a72be4a3c8cb1bcac897bcd6 --report — require both: the signing certificate chains to signing-ca.pem and has this fingerprint

• sipnab -N -I signed.vcon.json --vcon-x5u-ca system --json-dialogs — analyze a signed vCon whose signature names its certificate chain only by an x5u URL: fetch the chain over HTTPS from a server the host's CA bundle trusts

• sipnab -N -I signed.vcon.json --vcon-x5u-ca pki-ca.pem --vcon-signer-ca signing-ca.pem --report — fetch the x5u chain from a server the CA in pki-ca.pem issued, and read the vCon only when its signer chains to signing-ca.pem

• sudo sipnab --device eth0 --output capture.pcap --portrange 5060-5080 --count 10000 — record up to 10000 packets from eth0 into a pcap, watching a widened SIP port range

• sudo sipnab --device eth0 --buffer 16 --buffer-budget 128 --snaplen 2048 --quiet-bad-parse — live-capture a busy link with bigger kernel and queue buffers, a capped snapshot length, and parse-error notices silenced (the CLI matcher -x)

• sudo sipnab -N -d eth0,eth1 --multi-device --output capture.pcap --autostop filesize:100 — capture on two named interfaces at once, headlessly, stopping once the output file reaches 100 MiB. --multi-device needs the list. Without one it is a no-op

• sipnab -N --input capture.pcap --replay --no-rtp — replay a pcap at its original timing with RTP capture and analysis disabled

• sudo sipnab -N -d eth0 --capture-profile signaling --output signaling.pcap — record signaling on a busy link: 1500 bytes keeps every SIP header whole while dropping the bulk of each RTP packet, which is where the ring pressure comes from. Check sipnab_capture_snapped_frames_total afterwards to see how many frames arrived short

• sudo sipnab -N -d eth0 --capture-profile signaling --snaplen 4096 — the explicit number wins over the profile, for a trunk carrying INVITEs too large even for one MTU (deep Record-Route sets, ISUP encapsulation). Use --capture-profile full instead when you need --retain-audio, WAV export or a faithful -O re-emit, all of which need RTP payload

• sipnab -N --input /var/captures/ --json-dialogs --no-cli-print — read every capture in a directory as one timeline, so a call split across the ring buffer resolves to one dialog instead of two fragments

• sipnab -N --input /var/captures/ --recursive --input-name '*.pcap.gz' --json-dialogs --no-cli-print — descend into per-day subdirectories and read only the compressed archives

• sipnab -N --input 'captures/tg.pcap[0-4]' --report — analyze the first five members of a ring buffer with a glob sipnab expands itself, no shell needed

• sipnab -N --input session.tgz --report — analyze every capture in an archive as one timeline without unpacking it, each member not read named with the reason

• sipnab -N --input a.pcap --input b.pcap --json-dialogs --no-cli-print — read two named captures as a single set, ordered by their packets

• sipnab -N --input /var/captures/ --input-name 'edge1-*' --recursive --json — pick one host's captures out of a tree holding several

• sipnab -N --input capture.pcap --limitlen 512 --no-reassembly --quiet-bad-parse — scan a pcap quickly: parse only the first 512 bytes of each packet, every packet standalone (no reassembly), without parse-error noise

• sudo sipnab --device eth0 --bpf-file sip.bpf --no-promisc --duration 5m — capture for 5 minutes using a BPF filter read from sip.bpf, without putting the interface into promiscuous mode (the CLI matcher -p)

• sudo sipnab -N --device eth0 --capture-tunnels --buffer 64 --duration 5m — capture SIP traveling inside GTP-U, VXLAN or GENEVE as well as the encapsulations the auto-filter already covers. This takes every packet on ports 2152, 4789 and 6081, so the same command widens the kernel buffer. Check the drop counters in the summary before trusting a long run

• sudo sipnab -N --device eth0 --capture-tunnels=8472 --portrange 5060-5080 --report — cover a Linux VXLAN fabric on its pre-IANA port 8472 instead of the three defaults, across a widened signaling range

• sudo sipnab --device eth0 --portrange 5060-5090 --buffer 8 --buffer-budget 256 --duration 1h — monitor an hour of traffic across a wide SIP port range with enlarged capture buffers

• sipnab -N --input capture.pcap --replay --limitlen 1500 --no-rtp — replay signaling only from a pcap, parsing at most 1500 bytes of each packet

• sudo sipnab --device eth0 --bpf-file sip.bpf --no-promisc --snaplen 9000 --count 500 — stop after 500 packets that pass the sip.bpf filter, non-promiscuous, with the snapshot length sized for jumbo frames

• sudo sipnab -N --device eth0 --output capture.pcap --autostop duration:60 --no-reassembly — write a one-minute capture that treats every packet standalone (IP-fragment and TCP-segment reassembly off)

• sipnab -N --input webrtc.pcap --ws-portrange 8081-8081 --portrange 1-65535 --json-dialogs --no-cli-print — a WSS listener behind a reverse proxy that forwards to 8081: without the range the entire WebRTC signaling leg is invisible, and sipnab reports how many messages it skipped and on which port

• sudo sipnab -d eth0 --ws-portrange 1-65535 --portrange 1-65535 — unwrap SIP-over-WebSocket wherever it appears on a box whose WSS port you do not know yet, then read the skip line to learn which ports were carrying it

Point -I at a .tar, a .tgz, a .tar.gz or a .zip, and sipnab reads it the way it reads a directory. See Archives for password-protected ones.

• Every capture inside joins the set, in capture order, alongside anything else -I named.
• Nobody has to unpack it first.
• The answer matches what reading the unpacked directory gives.

The rules:

• Layers nest. These unwrap on the way to the capture, up to four layers deep:

  • a gzip-compressed member such as ring-3.pcap.gz,
  • a tar inside a .tgz,
  • or both.

  sipnab identifies each layer by its first bytes, never by its name. So a gzip file named c.pcap still opens.

• sipnab accounts for every member. A member that is not a capture gets a Skipping line naming it and the reason. The reasons are:

  • empty,
  • not a capture (with its first four bytes),
  • a link,
  • a device node,
  • a sparse file,
  • a format sipnab does not unwrap, such as 7-Zip, zstd, xz or bzip2.

  The closing -I resolved to line counts them.

  A member may have a link type sipnab does not decode, such as an LTE MAC log.

  • It gets a line naming it.
  • Its frames count as not decoded.
  • A BPF filter that cannot compile against that link type skips the member. It does not end the run.

• Names come from the archive, paths never do.

  • sipnab writes each member to a file it names itself, in a private directory under $TMPDIR.
  • It deletes that directory when the run ends.
  • A member called ../../etc/x lands in that directory like any other.
  • Output, logs and frame pointers name a member <archive>/<member>. For example: session.tgz/ring/a.pcap#12.
  • --show-frame reads that member straight back out of the archive.

• Inflation stops at a ceiling.

  • Every byte any gzip layer produces counts against --max-gunzip-bytes. sipnab sums the count across the layers of one input.
  • One archive may hold at most 10,000 entries.
  • An archive cut short, or stopped at a ceiling, keeps what arrived. It marks the run incomplete:
    • exit status 1,
    • archives.cut_short in the sipnab_run record.

• --input-name filters members by file name, the same way it filters a directory's files. On a single compressed capture it still refuses. There is nothing to choose between.

• Decryption works on members exactly as on plain files. Each of these decrypts a member the same way:

  • --keylog,
  • the secrets a pcapng embeds,
  • SDES keys in the SDP,
  • --dtls-keylog.

  It does not matter whether the member arrived plain, gzip-compressed, in a tar, in a .tgz, or gzip-compressed inside a .tgz.

A run may die without cleaning up, from a crash or kill -9.

• It leaves its directory behind, holding a lock that died with it.
• The next run that unpacks an archive removes it.

Captures often travel as password-protected ZIP files. They carry subscriber identities, numbers and credentials.

• Unpacking one by hand leaves a decrypted copy on disk. That defeats the password.
• Point -I at the ZIP instead. sipnab then:
  • opens it,
  • reads the captures inside,
  • deletes its own owner-only copy of each member when the run ends.
• A ZIP reads like a .tgz. So everything in Archives read like directories applies to it.
• A ZIP nested in a tar, or a tar in a ZIP, unwraps too.

Builds with the archive feature read ZIP and 7z files. These include it:

• the full build,
• every release binary, the static musl tarballs and the -noaudio packages among them.

Where a password comes from, best first. sipnab tries every source you configure, in this order, before it gives up on a member:

• --archive-password-file, for scripts and services.
• --archive-password-command.
• --archive-password-stdin.
• The systemd credential archive-password.
  • When $CREDENTIALS_DIRECTORY/archive-password exists, sipnab reads it like a password file.
  • So LoadCredential=archive-password:/etc/sipnab/pcaps.pw or LoadCredentialEncrypted= in the unit is all it takes.
  • Writing --archive-password-file %d/archive-password in the unit works too.
• The SIPNAB_ARCHIVE_PASSWORD environment variable. It ranks below every source above because a process's environment leaks:
  • child processes inherit it,
  • systemd and OWASP both advise against secrets there.
• --archive-password, which warns on every use.
• The prompt. When no configured password opens a member, sipnab asks on the terminal, the way ssh and sudo do: Password for evidence.zip (member voip/call3.pcap, attempt 1 of 3):.
  • It reads /dev/tty, not stdin. So it still asks with stdin redirected.
  • It echoes nothing.
  • Each archive gets three attempts.
  • An empty entry, or Ctrl-D, skips that archive's locked members.
  • Ctrl-U clears the line.
  • Ctrl-C stops the run.
  • sipnab restores the terminal on every one of those paths.
  • Sometimes it never asks and never waits. Locked members then count as encrypted_no_password. This happens:
    • with no terminal, as in cron, CI or a detached agent,
    • or with --no-password-prompt.
  • A TUI run asks here for the archives -I names, before it draws.
  • A capture opened inside the TUI asks in its own window, described in Archive password popup.

How sipnab tries them.

• The password that opened one member of an archive goes first for that archive's other members.
• It never goes to another archive unless you configured it.
• ZIP never records which encoding its creator typed the password in. So sipnab also tries a non-ASCII password in these forms:
  • its NFC and NFD forms,
  • the CP437, CP850 and CP1252 code pages that unzip and 7-Zip fall back to.
• All of those spellings count as one attempt.
• Passwords may be up to 4096 bytes. sipnab refuses a longer one whole rather than cutting it short.

What it reads.

• ZIP members stored or deflated:
  • unencrypted,
  • encrypted with WinZip AES (128, 192 or 256-bit),
  • or encrypted with the legacy ZipCrypto.
• 7z archives compressed with LZMA or LZMA2:
  • unencrypted or AES-256,
  • with or without an encrypted member list.
• A 7z password covers the whole archive. The format stores it as UTF-16 text. So sipnab tries its NFC and NFD forms but no code pages.
• A 7z sets how much work deriving its key takes.
  • sipnab refuses one asking for more than 7-Zip's own ceiling of 2^24 rounds, as bound_exceeded (7z key derivation).
  • The reason: a crafted archive could otherwise make one attempt take hours.

sipnab reads ZipCrypto and warns once per archive that it protects nothing.

• The bkcrack tool recovers its keys from 12 known bytes.
• A capture's first bytes are predictable.
• A wrong password fails the format's own check.
• One wrong password in 256 slips past ZipCrypto's check byte. For that one, the member's CRC fails instead, and sipnab moves on to the next candidate.

What it reports. Each member sipnab does not read gets a Skipping line with the reason. The reason is one of these:

• encrypted, and no password was supplied,
• encrypted, and no password supplied opens it,
• a format it cannot decrypt.

You may name an archive with -I and sipnab may read nothing from it.

• That fails the run with exit status 1.
• It names each member with its reason code, such as evidence.zip/call3.pcap: encrypted_no_password.
• If some members open, the run succeeds. The closing -I resolved to line counts the rest.

Where the password never goes. No log line at any level contains it. No error message, output format or export contains it either.

• A run that holds a password turns core dumps off.
• --allow-coredump warns that a dump would contain it.

Exports carry the data out unencrypted.

• These each warn once that they write that data unencrypted, when they write from a member decrypted out of a password archive:
  • -O,
  • --strip-secrets,
  • --write-annotated.
• The section comment of a --write-annotated copy says so too. It names no password.

Examples

• sipnab -N -I evidence.zip --archive-password-file ~/.config/sipnab/pcaps.pw --report — read a password-protected ZIP with the password in an owner-only file
• sipnab -N -I evidence.zip --archive-password-file <(pass show pcaps/lab) --json-dialogs --no-cli-print — take the password straight from a password manager through a pipe, so it never touches the disk
• sipnab -N -I evidence.zip --archive-password-command 'pass show pcaps/lab' --report — let sipnab run the password manager itself
• printf '%s\n' "$PCAP_PW" | sipnab -N -I evidence.zip --archive-password-stdin --report — pass a password a CI job holds in a masked variable
• sipnab -N -I evidence.zip --archive-password-file pw.txt --archive-password-encoding cp437 --report — try only the DOS code page, for an archive you know an old Windows tool made
• sipnab -N -I evidence.zip --archive-password-stdin --archive-password-encoding cp1252 --json-dialogs --no-cli-print < pw.txt — read the password from a redirected file and try only the Windows code page
• sipnab -N -I 'captures/*.zip' --archive-password-command 'op read op://lab/pcaps/password' --json-dialogs --no-cli-print — open every ZIP a glob finds with one password from 1Password's CLI
• sipnab -N -I evidence.zip --archive-password 'correct horse' --report — a throwaway lab archive only: the password lands in ps and your shell history, and sipnab warns
• sipnab -N -I lab.zip --archive-password "$LAB_PW" --report — the same trade-off from a variable, which still shows in ps; prefer --archive-password-stdin
• sipnab -N -I evidence.zip --report — no password configured: sipnab asks on the terminal for each locked archive, three tries each
• sipnab -N -I evidence.zip --no-password-prompt --json-dialogs --no-cli-print — in a script that must never wait on a keyboard: sipnab skips and counts the locked members instead
• sipnab -N -I 'drop/*.zip' --archive-password-file pw.txt --no-password-prompt --report — try the configured passwords and nothing else, even from a terminal

Examples

• sipnab --no-tui -I capture.pcap --calls-only — analyze a pcap headlessly, showing only calls (dialogs an INVITE started), without OPTIONS pings, registrations or subscriptions
• sudo sipnab --no-tui -d eth0 --telephone-event — headless live capture that decodes DTMF and logs each event with its duration and SSRC, digit value masked
• sipnab --no-tui -I capture.pcap --calls-only --telephone-event — read a capture headlessly, report only calls, and log how many DTMF events each one carried
• sipnab --no-tui -I lab.pcap --telephone-event --dtmf-cleartext — read a capture you own and disclose the digit values. Also set SIPNAB_LOG=debug, or the run prints nothing but the mask
• sudo sipnab --no-tui -d eth0 --telephone-event --dtmf-cleartext 2>dtmf.log — capture live and steer the cleartext digits into a file whose permissions you control instead of a shared terminal or journald. Again needs SIPNAB_LOG=debug

Read this before using --dtmf-cleartext. DTMF digits keyed after answer include:

• PINs,
• calling-card numbers,
• account numbers,
• credit-card numbers with their CVVs.

RFC 4733 carries them in the clear no matter how well the signaling layer protected the call. So -t alone logs everything you diagnose with, with the digit value replaced by x:

• that an event arrived,
• its duration,
• its SSRC,
• its timestamp.

DTMF digit='x' duration=200ms ssrc=0xdeadbeef

--dtmf-cleartext adds a second line carrying the value. It is not a display setting.

• It puts a caller's PIN wherever this run's log goes:
  • your terminal,
  • a redirected file,
  • journald,
  • every aggregator downstream of journald.
• Turning it on takes two deliberate acts. sipnab writes the cleartext line at debug while the masked line stays at info. So:
  • pass the flag and
  • raise the level.
• Either one alone shows you nothing but the mask. Both, in one copyable line:

SIPNAB_LOG=debug sipnab --no-tui -I lab.pcap --telephone-event --dtmf-cleartext 2>dtmf.log

Where the events go. sipnab writes one masked line per decoded event and keeps a count. Nothing else carries the digits: no report, no JSON field, no MCP tool.

Two consequences follow, and both bite the obvious command lines.

• Adding -t to a TUI session shows you nothing. TUI mode floors the log level at error to keep the alternate screen intact.
• Adding --quiet also hides them. It floors the level at warn.
• Use -N without --quiet.

SIPNAB_LOG=info does override the TUI floor. But sipnab sets that floor to stop log lines corrupting the alternate screen. So redirect stderr if you do.

Examples

• sipnab -N -I capture.pcap --match "[email protected]" --ignore-case — show every dialog that mentions [email protected], case-insensitively (dialog-following payload match)
• sipnab -N -I capture.pcap --match "486 Busy Here" --word --single-line — whole-word match for 486 rejections, preventing . from spanning header lines
• sudo sipnab -d eth0 --match "REGISTER" --invert — live view of everything except REGISTER traffic (inverted match)
• sudo sipnab -d eth0 --ua "friendly-scanner" --contact "203\.0\.113\." --ignore-case — flag scanner traffic live: a known scanner User-Agent (any case) with a Contact pointing into 203.0.113.0/24
• sipnab -N -I capture.pcap --ua "sipcli" --contact "192\.0\.2\." --single-line — filter a pcap by User-Agent and a Contact in 192.0.2.0/24, restricting payload regex dots to a single line
• sipnab -N -I capture.pcap --match "OPTIONS" --word --invert — suppress keep-alive noise: show messages that do not contain the whole word OPTIONS
• sipnab -N -I capture.pcap --report --since 2026-10-09T10:00:00Z --until 2026-10-09T11:00:00Z — report only the calls that started between 10:00 and 11:00 UTC

A query flag answers one question about the capture and exits.

• Each one prints the same answer as the REST route and the MCP tool for that question. All three call the same function.
• The output is:
  • a table by default,
  • Markdown with --markdown,
  • with --json, one JSON object on the last line of stdout, in exactly the shape the REST route returns.
• Every query honors --filter and the time window below.

--since and --until keep the dialogs whose first message falls in the half-open window [--since, --until).

• A dialog at exactly --since is in.
• A dialog at exactly --until is in the next window.
• So adjacent windows never count a call twice.
• Either bound alone leaves the other side open.
• Values are RFC 3339 instants. sipnab converts an offset other than Z to UTC.

The window is the one every surface applies, under three spellings:

The CLI cannot use REST's names. -A/--after already sets the context lines printed after a match.

The window joins --filter and the diagnostic alias flags in one compiled filter. So these all see the same dialogs:

• --report,
• --json-dialogs,
• --analyze,
• the per-message stream,
• --export-vcon-when,
• every query.

--call-report and --export-vcon name one call by Call-ID and are not narrowed.

A window may hold none of the capture's dialogs.

• The run exits 0 with empty listings.
• It says so on stderr, naming the window and the span the capture's dialogs cover.

These exit 2:

• an --until that is not after --since,
• a value that is not RFC 3339.

The flags need -N. In the TUI, set the time range in the call list's filter dialog. Examples

• sipnab -N -I capture.pcap --json-dialogs --no-cli-print --since 2026-10-09T10:00:00Z --until 2026-10-09T11:00:00Z — one JSON line per call that started between 10:00 and 11:00 UTC
• sipnab -N -I capture.pcap --report --filter "state == 'Failed'" --since 2026-10-09T10:00:00Z — the failed calls that started at or after 10:00 UTC

See the Name Resolution keys for in-TUI naming (N) and persistence.

Examples

• sipnab -N -I capture.pcap --no-reverse-dns — make no DNS queries when your config file sets [names] reverse_dns = true

• sipnab -N -I capture.pcap --reverse-dns --no-reverse-dns — the last of the pair wins, so sipnab makes no lookups

• sipnab -N -I capture.pcap --no-resolve — show raw addresses when your config file turns names on, through [names] enabled, a hosts file or [names.manual]

• sipnab -N -I capture.pcap --resolve --no-resolve — the last of the pair wins, so addresses print as addresses

• sudo sipnab -d eth0 --resolve --names /etc/sipnab/hosts.map — live capture with name resolution from a static hosts-format mapping file

• sipnab -N -I capture.pcap --resolve --names /etc/sipnab/hosts.map --names ~/.config/sipnab/lab-names — annotate an offline pcap with names, preloading two mapping files on top of /etc/hosts

• sudo sipnab -d eth0 --reverse-dns — live capture that also resolves captured IPs via reverse DNS (PTR) lookups

• sipnab -N -I capture.pcap --reverse-dns --names ~/.config/sipnab/lab-names — replay an offline pcap and resolve its addresses with reverse DNS, supplemented by a local mapping file

• sudo sipnab -N -d eth0 --reverse-dns --dns-cache-entries 65536 — a peering point or carrier edge, where a capture touches far more than four thousand hosts: the wider cache stops sipnab re-resolving addresses it already knows, and the worker queue widens with it

• sipnab -N -I lab.pcap --reverse-dns --dns-cache-entries 256 — the opposite, for a small lab capture on a memory-tight box, where a few hundred entries cover every host in the file

Note: with resolution active, sipnab saves name mappings into a pcapng Name Resolution Block.

• This happens on both the TUI save path and the headless -O --pcapng export (whenever --resolve/--names apply).
• Headless pcapng exports also describe themselves:
  • the Section Header Block records the producing application (sipnab <version>) and OS,
  • the Interface Description Block records the capture source as the interface name.
• Opening a pcapng reads embedded NRB names and DSB TLS secrets back. sipnab decrypts with them.
• See the design doc.

Examples

• sipnab --show-frame 'capture.pcap#41@6f3a1c02b8d4e795' — print the frame a dialog opened in, verifying the capture has not changed since
• sipnab --show-frame 'capture.pcap#41' — same frame, printed as UNVERIFIED because the short form carries nothing to check against
• sipnab -N -I capture.pcapng --strip-secrets clean.pcapng — write a sanitized copy of a pcapng with every Decryption Secrets Block removed
• sipnab -N -I tls-call.pcapng --strip-secrets tls-call-clean.pcapng — strip embedded TLS secrets from a decrypted-session capture before sharing it in a support ticket

A note is a remark a person writes about one SIP message. It travels to the person who opens the capture next.

• sipnab writes each note into a pcapng packet comment. Wireshark shows it beside the frame.
• sipnab never reads a packet comment back. A note is output, never part of the analysis.

Examples

• sipnab -N -I call.pcap --notes call.notes.jsonl --write-annotated call-annotated.pcapng — hand a carrier the call with your notes on the frames they are about, readable in Wireshark
• sipnab -N -I ticket-4711.pcapng --notes ticket-4711.notes.jsonl --write-annotated ticket-4711-for-vendor.pcapng — annotate a copy of a pcapng from a ticket without touching the original, which keeps its decryption secrets and the copy does not
• sipnab -I call.pcap --notes call.notes.jsonl — open the call in the TUI with the notes you saved last time, and save new ones back to the same file

Shortcut flags that expand to predefined filter DSL expressions. See filter-dsl.md for the exact expansion of each alias.

Multiple diagnostic flags combine with OR.

• Adding --filter ANDs its expression with that selection.
• For example, --problems --filter "from.user == '1001'" selects only problem calls from user 1001.

Examples

• sipnab -N -I capture.pcap --short-calls --one-way — flag completed calls under 3 seconds and calls with suspected one-way audio in a capture
• sudo sipnab -d eth0 -N --one-way --nat-issues — live-monitor for one-way audio and NAT-rewritten media sources
• sipnab -N -I capture.pcap --short-calls --report — summarize short completed calls from a capture in a post-run report

Examples

• sipnab -N -I capture.pcap --no-delta-time — print absolute times when your config file sets [display] delta_time = true

• sipnab -N -I capture.pcap --delta-time --no-delta-time — the last of the pair wins, so times print absolute

• sipnab -N -I calls.pcap --lint --no-cli-print — run the RFC conformance linter over every dialog in a capture and print each finding with the rule identifier and the RFC section it reads from. Informational: it leaves the exit code alone

• sipnab -N -I calls.pcap --export-vcon-when "state == 'Failed'" --export-vcon-dir out --redact --redact-keep-prefix 4 --no-cli-print — hand a vendor every failed call with keyed tokens standing in for the subscriber numbers and the area code intact, so they can still see which route the failures came from

• sipnab -N -I calls.pcap --export-vcon call-1 --vcon-out out.vcon --redact --redact-key-file team.key --redact-map out.map --no-cli-print — a stable key, so today's tokens join against last week's, and the reversal table written beside the container at 0600

• sipnab -N -I calls.pcap --export-vcon-when "state == 'Completed'" --export-vcon-dir out --redact --redact-keep-prefix 3 --redact-map out.map --no-cli-print — export every completed call, keep the NANP area code readable so a route analysis still works, and write the reversal table beside the export. Three digits is a choice about a real subscriber number, not a default sipnab can make for you: a country code is one to three digits and a national destination code is anything

• sipnab -N -I calls.pcap --export-vcon-when "state == 'Failed'" --export-vcon-dir out --redact --redact-key-file team.key --redact-keep-prefix 0 --no-cli-print — the shape to send outside the team, here for every failed call. A shared key still joins a subscriber across exports, no digits survive in the clear, and with no --redact-map written nothing anywhere reverses the tokens

• sipnab -N -I calls.pcap --lint --lint-fail-on error --no-cli-print — the CI gate. Exits 3 when any finding is at or above error, so a pipeline stops on a non-conformant capture. Exit 3 is not 1 or 2, so a failing gate is distinguishable from a failing tool and from a bad invocation

• sipnab -N -I calls.pcap --lint --lint-fail-on warning --no-cli-print — a stricter gate: stop on warnings as well as errors, for a pipeline that treats interop degradation as a build failure rather than a note

• sipnab -N -I capture.pcap --json-dialogs --no-cli-print --plugin ./short-calls.wasm — run a custom detection over every dialog and emit its findings beside sipnab's own

• sudo sipnab -d eth0 -N --json-dialogs --no-cli-print --plugin ./site-rules.wasm --plugin ./fraud.wasm — stack two site-specific detections over live traffic. Each plugin is sandboxed and a failure in one never stops the capture

• sipnab -N -I capture.pcap --stun --no-cli-print — read what NAT traversal actually achieved: which probes drew an answer, what public address came back, and which drew nothing. A capture holding only failed STUN is not an empty capture, it is the cause of a one-way-audio complaint

• sipnab -N -I relay.pcap --stun --markdown --no-cli-print — the same tables as Markdown, for pasting into a ticket. On a capture that went through a TURN relay this adds the allocations section, where a LAPSED status means the relay tore the allocation down while media was still crossing it

• sipnab -N -I capture.pcap --json-stun --no-cli-print | jq 'select(.record == "transaction" and .responded_at == null)' — every transaction nothing answered, as JSON

• sipnab -N -I relay.pcap --json-stun --no-cli-print | jq 'select(.lapsed == true)' — the relay allocations that ran out under live media, which no SIP message anywhere reports

• sipnab -N -I capture.pcap --analyze --no-cli-print — one ranked list of everything wrong with the file, worst first, with the evidence for each finding

• sipnab -N -I capture.pcap --analyze --filter "state == 'Failed'" --no-cli-print — narrow the DIALOG findings to failed calls. The capture-level evidence (undecodable frames, discarded ports, dropped records) is deliberately not narrowed, because it bounds every count in the report

• sipnab -N -I capture.pcap --json-analyze --no-cli-print | jq '.findings[] | select(.severity == "critical")' — the critical findings only, for a pipeline

• sipnab -N -I capture.pcap --json-analyze --no-cli-print | jq '.complete' — whether the capture decoded fully. false means every count in the analysis is a floor, so do not trust a clean-looking verdict

• sipnab -N -I capture.pcap --yang-analyze --no-cli-print > analysis.json — the capture analysis as a YANG instance document. yanglint -t data [email protected] analysis.json validates it

• sipnab -N -I capture.pcap --json-analyze --yang-analyze --no-cli-print — both encodings of ONE analysis, one line each: the same findings, the same counts, the same rank order

• sipnab --print-yang-module > [email protected] — save the YANG module this build's RFC 7951 export validates against, under the file name RFC 7950 gives it, for yanglint or pyang

• sipnab --print-yang-module | pyang -f tree — the shape of the capture analysis as a YANG tree: every node, its type, and which are lists

• sipnab -N -I capture.pcap --json-dialogs --no-cli-print --quiet | jq -c 'select(.state == "Failed")' — one line per failed call, each carrying the code that failed it, instead of every message of every failed dialog

• sudo sipnab -d eth0 -N --json-dialogs --no-cli-print --line-buffer > calls.ndjson — record one summary object per call from live traffic, flushed per line for a downstream collector

• sudo sipnab -N -d eth0 --node-name sbc-edge-1 --mcp --mcp-transport http — one node of a federated setup, naming itself so an agent can attribute each answer to this box rather than another

• sudo sipnab -N -d eth0 --node-name pbx-core-2 --report — override the hostname on a box whose real name should not travel, while still labeling the capture

• sipnab -N -I capture.pcap --json-pretty --payload-limit 1000 > messages.json — export every SIP message from a capture as pretty-printed JSON, truncating displayed payloads to 1000 bytes

• sudo sipnab -d eth0 -N --json-pretty --group-by method --line-buffer > live.json — stream live SIP traffic as pretty-printed JSON grouped by method, flushing after each line for downstream tooling

• sipnab -N -I capture.pcap --text-dump --hexdump --proto-number --color never — dump raw SIP text with hex payloads and IANA protocol numbers, uncolored for log archiving

• sudo sipnab -d eth0 -N --match REGISTER --after 2 --text-dump --line-buffer --color always — follow live REGISTER traffic in real time, printing raw text plus 2 messages of context after each match

• sipnab -N -I capture.pcap --show-empty --delta-time --hexdump --group-by call-id — review a capture with per-message delta times, empty-bodied messages included, and hex dumps grouped per call

• sudo sipnab -d eth0 -N --match OPTIONS --after 5 --show-empty --proto-number --payload-limit 256 — inspect OPTIONS keepalives with 5 messages of trailing context, empty bodies shown, and display capped at 256 payload bytes

• sudo sipnab -N -d eth0 --from-to-mode host-port --wireshark — capture live with host:port From/To columns and print a Wireshark display filter when capture ends

• sipnab -I capture.pcap --from-to-mode user-host-port — browse an existing capture in the TUI with full user@host:port From/To columns

• sipnab -N -I busy-day.pcap --group-by call-id --max-groups 250000 --no-cli-print — group a capture holding more calls than the shipped 100000-key cap, instead of taking the first hundred thousand and a warning naming how many keys sipnab turned away

• sipnab -N -I busy-day.pcap --group-by from --max-grouped-messages 2000000 --json — regroup a large capture by caller with room for every message, keeping the output one valid JSON object per line

• sipnab -N -I untrusted.pcap --group-by call-id --max-groups 500 --max-grouped-messages 5000 --no-cli-print — group a capture from outside your network under a tight pair of caps, so an attacker-chosen Call-ID cannot buy more memory than you allowed

• sipnab -N -I capture.pcap --export-vcon '[email protected]' > call.vcon -- hand one observed dialog to a conversation-data pipeline in the interchange format it already reads, instead of a sipnab-shaped JSON nobody else parses. The container names sipnab as an observer party and carries what this capture missed, so a consumer weighs it as an observation rather than as a recording

• sipnab -N -I capture.pcap --export-vcon '[email protected]' --vcon-out ./call.vcon --no-cli-print -- the same container to a file, with the run otherwise silent. Use this spelling in a script: the exit code is the whole answer, and a path sipnab cannot write fails the run rather than leaving an operator to discover the missing file later

• sipnab -N -I capture.pcap --export-vcon-when "state == 'Failed'" --export-vcon-dir ./failed/ --content-deny-header X-No-Record -- the same failures, minus any call whose signaling asked sipnab to leave it alone. A switch that marks sensitive calls can keep them out of an export without sipnab needing to understand why

• sipnab -N -I ./captures --export-vcon-when 'duration > 30' --export-vcon-dir ./long/ --content-deny-header Privacy -- presence is the whole rule, so Privacy: none suppresses exactly as Privacy: id does. If you do not understand a deny flag, denying is the only safe reading of it

• sipnab -N -I capture.pcap --export-vcon-when "state == 'Failed'" --export-vcon-dir ./failed/ -- one container per failed dialog, for handing a morning's failures to a conversation-data pipeline without naming each Call-ID by hand. A capture where nothing failed writes nothing and says so on stderr, which is the answer an operator needs rather than an empty directory

• sipnab -N -I ./captures --export-vcon-when "duration > 30 and rtp.codec == 'PCMU'" --export-vcon-dir ./long-g711/ --no-cli-print -- the predicate is the filter language, so the same conditions that narrow a report also choose a container set. The containers carry the same ICMP media evidence the report shows, because both go through one selection path

• sipnab -N -I ./captures --export-vcon '[email protected]' --vcon-out ./captures/1-1966.vcon -- refused before anything opens a writer. --vcon-out goes through the guard -O does, so a container cannot land inside a directory this run reads: a name that is free today becomes an input on the next run, and the container would then overwrite the evidence it summarizes

• sipnab -N -I capture.pcap --export-vcon '[email protected]' | jq -r '.analysis[0].body.capture_completeness.note' -- read the caveat before the contents. The analysis body declares encoding: "json", so it is the JSON object itself and jq indexes into it directly. The note comes from this run's own counters and says what sipnab READ and dropped. It never says the call was short, silent or broken, because none of that follows from a capture that missed something

• sipnab -N -I ./captures --export-vcon-when 'duration > 30' --export-vcon-dir ./long/ --vcon-max-inline-media 64 -- carry audio the shipped 5 MiB budget would refuse. One store answers HTTP 204 and then drops the payload in its file spool, telling the producer nothing, and that measurement set the default -- so raise it only when you know what reads your containers

• sipnab -N -I ./captures --export-vcon-when 'response_code >= 200' --export-vcon-dir ./calls/ --vcon-max-inline-media 0 --retain-audio -- keep the containers and inline none of the audio. 0 says "never inline media" without turning the exporter off, and the refusal still appears in the completeness caveat rather than passing as a call that had no audio

• sipnab -N -I ./captures --export-vcon-when "state == 'Failed'" --export-vcon-dir ./failed/ --content-deny-header X-No-Record --content-deny-tombstone -- write an identity-only container for each denied dialog instead of nothing, so a consumer can tell a call that was deliberately withheld from one that never happened. It carries no message trace, no media and no bodies, and declares redacted with type alone, because no fuller version of the container exists anywhere to point at

• sipnab -N -I capture.pcap --export-vcon-when 'duration > 0' --export-vcon-dir ./out/ --content-deny-header Privacy --content-deny-tombstone -- off by default for a reason worth stating: a tombstone reveals that the call EXISTED. If the header means "this call must leave no trace", leave the flag off and let the dialog produce nothing at all

• sipnab -N -I ./captures --export-vcon-when 'duration > 30' --export-vcon-dir ./long/ --vcon-digest > SHA256SUMS -- record what sipnab wrote. The digests go to stdout in sha256sum format while the progress summary stays on stderr, so the redirect captures the one and not the other

• sipnab -N -I capture.pcap --export-vcon-when 'duration > 0' --export-vcon-dir ./out/ --vcon-digest | tee ./out/SHA256SUMS -- keep the digests beside the containers they describe, so the spool carries its own manifest. The name in each line is the bare file name rather than a path, so a spool that is later moved or mounted elsewhere still verifies from inside its own directory

• cd ./long/ && sha256sum -c ../SHA256SUMS -- verify later with the standard tool and no glue. This is a digest, not a signature. A signature over sipnab's bytes could never verify against the object a store holds, because a conserver adds fields on ingest. What the digest buys is binding an emission to a store's own ledger entry out of band

• sipnab -N -I capture.pcap --tshark-filter 'sip.Method == "INVITE"' — print a tshark-compatible display filter for the INVITE traffic in a capture. sipnab hands the expression to tshark's -Y verbatim, so it takes WIRESHARK display-filter syntax rather than sipnab's --filter DSL: sip.Method, not method. Quote the whole expression in single quotes so the inner double quotes survive the shell

branch counts transactions, not calls.

• RFC 3261 gives the ACK to a 2xx a new branch (RFC 3261 section 17.1.1.3). It gives the BYE another.
• So one ordinary call appears as three or more units.
• That is the transaction view working as intended.
• Use it when a capture reuses one Call-ID across many transactions, such as load generators or proxies under test.
• Note that --limit then counts transactions too.

Examples

• sipnab -N -I loadtest.pcapng --dialog-track branch --report — per-transaction view of a load-generator capture that reuses one Call-ID
• sipnab -N -I loadtest.pcapng --dialog-track call-id --report — same capture as dialogs (the default), for a per-call view
• sudo sipnab -d eth0 --limit 5000 --rotate — monitor a busy proxy with a tight 5000-dialog memory bound, explicitly evicting the oldest dialog at capacity
• sipnab -N -I capture.pcap --limit 20000 --no-rotate — analyze a capture keyed by Via branch, dropping new dialogs (instead of evicting old ones) past 20000 tracked
• sipnab -N -I capture.pcap --tag 1928301774 --rotate — show only dialogs carrying a specific From/To tag, with explicit LRU rotation
• sudo sipnab -d eth0 --tag as7d60e14a --no-rotate — live-follow dialogs matching a tag while refusing new dialogs once the tracker is full
• sipnab -N -I capture.pcap --no-dialog — scan a capture message-by-message with dialog tracking disabled entirely
• sudo sipnab -d eth0 -N --no-dialog — watch raw live SIP messages on an interface without keeping any per-dialog state
• sipnab -N -I sbc.pcap --leg-correlation-window 8000 --mcp — correlate the two legs of a call across a B2BUA that dips an ENUM or LNP database before placing the outbound leg, which the shipped two seconds cannot reach
• sipnab -N -I gateway.pcap --leg-correlation-window 500 --report — a PBX that places the outbound leg immediately, where a tighter window stops a busy server's unrelated calls turning into one
• sudo sipnab -N -d eth0 --metrics 127.0.0.1:9090 --active-idle-window 14400 — a contact center parking callers on hold for hours: at the shipped hour the active-call gauge stops counting them, and four hours covers the queue
• sudo sipnab -N -d eth0 --metrics 127.0.0.1:9090 --active-idle-window 300 — a trunk where every call refreshes on a short session timer, so five minutes of silence already means the BYE went missing and counting it longer only inflates the gauge

Examples

• sudo sipnab -d eth0 --quality-threshold 3.5 --max-streams 10000 — monitor live RTP with MOS alerts below 3.5. sipnab reports stream statistics once, at end of capture. There is no periodic interval report
• sipnab -N -I capture.pcap --max-streams 100000 — batch-analyze RTP streams with a raised stream cap. The statistics arrive once, when the capture ends
• sipnab -N -I long-call.pcap --max-lost-sequences 100000 --json-dialogs --no-cli-print — keep every loss from a half-hour call that an operator escalated, so the Packet Loss Map covers the whole call and the burst count is the real one rather than the tail's
• sudo sipnab -d eth0 --max-lost-sequences 200 — watch a busy trunk on a small box, holding a fifth of the shipped loss history per stream. The map still shows where loss is landing right now and marks itself truncated
• sipnab -N -I dead-air.pcap --quality-interval 1 --json-dialogs --no-cli-print — one snapshot a second on the call somebody complained about, so a half-second dropout appears as its own degraded interval instead of disappearing into a five-second mean
• sudo sipnab -d eth0 --quality-interval 30 --max-streams 20000 — the other direction, on a busy trunk where twenty thousand streams each holding 720 snapshots is memory better spent elsewhere. Thirty seconds still covers the retained hour, in 120 entries per stream
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 — start capturing on a proxy that shares a host with rtpengine, and ask the relay once, at startup, which calls are already up. Streams whose offer happened before sipnab started get a Call-ID, where otherwise sipnab would report them as orphans
• sudo sipnab -N -d eth0 --rtpengine-control 192.0.2.50:22222 --max-streams 10000 — the relay on its own host: same question, over the network to its ng control port. sipnab sends only list and query, and asks again only when a stream turns up that the signaling does not explain — each socket once, under a ceiling it reports when it reaches
• sipnab -N -I capture.pcap --rtpengine-control 127.0.0.1:22222 — refused, and says so: reading a file, sipnab never transmits, and the relay's answer would describe today's calls rather than the capture's
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats — capture live and print the relay's own counters at startup: packets relayed, sessions held, its own loss. The header marks them relay_reported, because the relay reports on itself rather than sipnab measuring the wire
• sipnab -N -I capture.pcap --relay-stats --rtpengine-control 127.0.0.1:22222 — refused, and says why: asking a relay transmits, and a file-backed run may not, so it prints not_permitted rather than talking to an address a capture named
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-call [email protected] — the relay's own packet and byte counts for one call, by Call-ID, relay_reported. A header names the call and the moment asked
• sipnab -N -I capture.pcap --relay-stats-call [email protected] --rtpengine-control 127.0.0.1:22222 — refused on a file run for the same reason the relay-wide form is: asking transmits, so it prints not_permitted
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-list — ask the relay which statistics it knows, listed by name and not by value, so a caller learns what it can ask for before a request fails on a name this build does not have. The header says the relay listed them, rather than sipnab guessing from a table
• sipnab -N -I capture.pcap --relay-stats-list --rtpengine-control 127.0.0.1:22222 — refused on a file run like the other relay-stats forms: listing asks the relay, and asking transmits, so it prints not_permitted rather than talking to an address the capture named
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-compare [email protected] — after capture, put the relay's own RTP packet count for the call beside sipnab's measured count, each labeled with its tier, with a match/differ verdict and a note explaining that an ordinary gap is not a relay fault. It shows both counts and never sums them
• sipnab -N -I capture.pcap --relay-compare [email protected] --rtpengine-control 127.0.0.1:22222 — refused on a file run: comparing asks the relay for its side, and asking transmits, so it prints not_permitted rather than reaching an address the capture named
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-interval 30 — capture live and ask the relay for its own counters every thirty seconds, each reading marked polled with the interval so it reads as a timer's output rather than a one-shot answer. Stop it with Ctrl-C. Nothing keeps transmitting after the process ends
• sipnab -N -I capture.pcap --relay-stats-interval 30 --rtpengine-control 127.0.0.1:22222 — refused on a file run like every relay-stats form: polling asks the relay, and asking transmits, so it prints not_permitted rather than reaching an address the capture named
• sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats --json — the same relay counters as one JSON object instead of the table, each value carrying its tier and refusals listed separately with the relay's code. Both forms read the same data, so --json and the table cannot disagree about a number
• sipnab -N -I relay.pcap --rtpproxy-control 192.0.2.40:7722 --report — read a capture taken on an rtpproxy relay whose control socket is udp:192.0.2.40:7722. Each stream on a port rtpproxy opened gets the Call-ID from the SIP proxy's command, and the report lists those calls as named by a media relay instead of reporting their media as orphaned
• sudo sipnab -N -d eth0 --rtpproxy-control 127.0.0.1:22222 — capture live beside an rtpproxy started with -s udp:127.0.0.1, which listens on 22222. sipnab only reads the control traffic and never sends rtpproxy anything

The numbers the signaling and media checks compare against.

• Each decides whether a call that is working gets reported as broken.
• So the defaults are standards figures for the general case. Your own network beats them.
• Every flag has a config key under [diagnosis], and the flag wins.

Examples

• sipnab -N -I calls.pcap --json-dialogs --pdd-threshold 6 --no-cli-print — judge a capture you know is local traffic against E.721's local target rather than the international one the default assumes
• sipnab -N -I trunk.pcap --json-dialogs --late-media-ms 150 --duration-asymmetry-secs 0.5 --no-cli-print — a tight media audit for a trunk where a 150 ms media gap is already a clipped first syllable
• sipnab -N -I sat-trunk.pcap --json-dialogs --pdd-threshold 15 --late-media-ms 900 --no-cli-print — the other direction, for a satellite path where the shipped figures report every healthy call as slow
• sipnab -N -I proxy.pcap --json-dialogs --ack-timeout 8 --no-final-response-timeout 30 --no-cli-print — a proxy tap where the interesting window is far shorter than the RFC 3261 timers, so a stalled transaction shows up while the capture is still running
• sipnab -N -I trunk.pcap --json-dialogs --ack-timeout 64 --no-final-response-timeout 300 --no-cli-print — a lossy trunk where the RFC timers themselves fire too early, so only a genuinely dead transaction gets reported
• sipnab -N -I b2bua.pcap --json-dialogs --duration-asymmetry-pct 25 --duration-asymmetry-secs 5 --no-cli-print — a B2BUA capture where the legs never tear down together, so only a large gap is worth a line
• sipnab -N -I b2bua.pcap --json-dialogs --duration-asymmetry-pct 1 --duration-asymmetry-secs 0.2 --no-cli-print — the strict form of the same audit, for hunting a leg that drops media a fraction early
• sipnab -N -I volte-trunk.pcap --json-dialogs --cn-suppression-ratio 0.8 --no-cli-print — a mobile trunk whose voice-activity detection sends comfort noise on well over 30 percent of packets: at the shipped ratio sipnab treats that as the explanation for a one-directional flow and reports no one-way audio on any call
• sipnab -N -I pbx.pcap --json-dialogs --cn-suppression-ratio 0.05 --no-cli-print — the opposite, for a LAN PBX where a call carrying any comfort noise at all is still expected to be bidirectional

Where the quality color column turns yellow, and where it turns red.

• This is a different question from the diagnosis thresholds above.
• Those decide whether a working call counts as broken.
• These decide only what catches an operator's eye during triage.
• Every flag has a config key under [quality], and the flag wins.

The shipped figures suit a general-purpose trunk. The right values belong to the network you are watching.

• 30 ms of jitter is already a fault on a LAN PBX.
• 1 percent loss is unremarkable on an international one.
• A column tuned for neither is wrong in both directions.

These bands paint the TUI.

• A -N run prints the measurements themselves rather than a color.
• So sipnab validates a band set on a non-interactive run and then never consults it.

sipnab refuses a warn boundary that sits above its matching bad boundary. It does not silently reorder the pair.

• That pair leaves an unreachable middle. Nothing would ever render as a warning.
• Whoever wrote it would see green until the value was already bad.

A boundary that is not a finite, non-negative number fails for a worse reason.

• Every comparison against NaN is false.
• So a single one would paint the whole column green.
• It would report a healthy network in the middle of an outage.

Examples

• sipnab -I lan-pbx.pcap --jitter-warn-ms 10 --jitter-bad-ms 20 — a LAN PBX, where the shipped 30 ms boundary hides a fault worth chasing
• sipnab -I wifi-softphone.pcap --jitter-warn-ms 60 --jitter-bad-ms 120 — the other direction, for a Wi-Fi leg where the defaults paint every healthy call yellow
• sipnab -I intl-trunk.pcap --loss-warn-pct 2 --loss-bad-pct 8 — an international trunk, where 1 percent loss is a Tuesday rather than an incident
• sipnab -I strict-lan.pcap --loss-warn-pct 0 --loss-bad-pct 1 — the strict form: any loss at all takes a color
• sipnab -I sat-trunk.pcap --rtt-warn-ms 700 --rtt-bad-ms 1200 — a satellite path, where G.114's terrestrial figures report every call as bad
• sipnab -I campus.pcap --rtt-warn-ms 50 --rtt-bad-ms 150 — a campus network, where a 300 ms round trip is already an escalation
• sipnab -I hd-codec.pcap --mos-warn 4.3 --mos-bad 3.8 — a wideband codec deployment, where 4.0 is not the good score it is on narrowband
• sipnab -I gsm-gateway.pcap --mos-warn 3.6 --mos-bad 2.8 — a low-bitrate gateway, where nothing ever clears the shipped 4.0 warning
• sipnab -I triage.pcap --jitter-warn-ms 15 --loss-warn-pct 0.5 --rtt-warn-ms 120 --mos-warn 4.2 — one strict pass across all four columns, for a first look at a network you have not seen before

--alert accepts a channel or a threshold rule. Channels are syslog, json or exec.

• --syslog and --alert-json are the equivalent boolean forms. Naming the channel here does the same thing.
• A value containing : is instead parsed as an alert rule (<name>:<threshold>/<window>[:<cooldown>]). The window needs an s/m/h suffix.

Rule names are scanner, fraud, digest and reg-flood (also reg_flood).

• An unknown rule name exits 2 at startup.
• A rule counts detector findings, not raw packets.

An unrecognized bare word draws a warning naming the valid channels. It used to fail silently. So a documented --alert syslog enabled nothing at all.

Examples

• sipnab -N -I capture.pcap --no-fraud-detect --report — skip fraud detection for one run when your config file sets [security] fraud_detect = true

• sipnab -N -I capture.pcap --fraud-detect --no-fraud-detect --report — the last of the pair wins, so no fraud detector runs

• sipnab -N -I capture.pcap --no-kill-scanner --report — analyze without arming the scanner response that your config file's [security] kill_scanner = true would arm

• sipnab -N -I capture.pcap --kill-scanner --no-kill-scanner --report — the last of the pair wins, so sipnab arms no response

• sudo sipnab -d eth0 --kill-scanner --kill-ua 'friendly-scanner' --kill-response 486 --kill-spoof auto — detect SIP scanners (plus a custom UA pattern) and reply 486 with the victim's spoofed source

• sudo sipnab -d eth0 --kill-target 192.0.2.66:5060-5090 --kill-ua 'sipvicious' --kill-response 480 --kill-spoof raw — targeted kill of a scanning host across a port range, plus a second scanner UA, replying 480 via raw-socket spoof

• sudo sipnab -d eth0 --kill-target 198.51.100.77:5060 --kill-spoof ephemeral — kill requests from one more source port using a non-spoofed ephemeral reply

• sudo sipnab -N -d eth0 --reg-flood --digest-leak --fraud-detect --stir-shaken --alert json --alert-json --alert-exec '/usr/local/bin/notify.sh' — live security monitoring: registration floods, digest leaks, fraud, STIR/SHAKEN, with JSON alerts and an exec hook

• sipnab -N -I capture.pcap --stir-shaken --digest-leak --alert-json — offline audit of a pcap for digest leaks and STIR/SHAKEN attestation claims (as the originator presented them — sipnab checks no signature), emitting structured JSON alerts

• sudo sipnab -N -d eth0 --reg-flood --reg-flood-threshold 10 --fraud-detect --business-hours 8-18 --fraud-short-call 1 — tune the detectors to a small PBX: ten REGISTERs a second is a brute force here, calls outside office hours are worth a line, and a one-second call is the only one short enough to be a lure

• sudo sipnab -N -d eth0 --reg-flood --reg-flood-threshold 400 --fraud-detect --business-hours 22-6 — the carrier-registrar shape instead: only a genuine flood clears 400 REGISTERs a second, and the quiet window is overnight

• sudo sipnab -N -d eth0 --reg-flood --reg-flood-threshold 20 --reg-flood-window 60 — a slow credential-guessing run: twenty refused credentialed REGISTERs from one source inside a minute is a flood, even when no single second holds more than one

• sipnab -N -I registrar.pcap --reg-flood --reg-flood-transaction-timeout 64000 — a network whose phones run T1 at one second, so RFC 3261 Timer F is 64 seconds and a registrar challenge forty seconds after the REGISTER still answers an open transaction

• sipnab -N -I trunk.pcap --fraud-detect --fraud-short-call 6 --fraud-wangiri-calls 5 --fraud-sequential-calls 6 — audit a wholesale trunk where short calls are ordinary, so a lure needs five of them and a dial-plan walk needs six consecutive dead numbers

• sipnab -d eth0 -N --kill-scanner --evidence-out - — publish findings on standard output for a reader to consume: sipnab says what it saw, and whatever consumes the stream decides what to do about it

• sipnab -N -I trunk.pcap --kill-scanner --reg-flood --evidence-out findings.jsonl — replay a capture and collect every source-naming finding in one file, to read before you wire anything to a response

• sipnab -d eth0 -N --fraud-detect --fraud-destination DO,VG,MA — an SBC that never dials the Dominican Republic, the British Virgin Islands or Morocco, three destinations where premium-rate fraud concentrates. The first INVITE to any of them alerts on sight

• sipnab -N -I trunk.pcap --fraud-detect --fraud-destination CU,KP --json — replay a trunk capture and write every INVITE to an embargoed destination as one JSON line, for the audit that asked whether any call ever went there

• sipnab -N -I pbx.pcap --fraud-detect --fraud-wangiri-calls 2 --fraud-sequential-calls 2 --fraud-volume-multiplier 3 --fraud-volume-min-calls 4 — the sensitive form for a small PBX, where two short calls to one prefix and four calls in a minute are already unusual

• sipnab -N -I trunk.pcap --fraud-detect --fraud-volume-multiplier 20 --fraud-volume-min-calls 200 — a busy carrier trunk, where a spike has to be twenty times its own baseline and 200 calls a minute before it means anything

• sipnab -N -I trunk.pcap --fraud-detect --fraud-wangiri-window 900 --fraud-short-call 5 — hunt a paced lure: three short calls to one prefix over fifteen minutes, which the shipped sixty-second window forgets between calls

• sipnab -N -I pbx.pcap --fraud-detect --fraud-volume-window 5 --fraud-volume-min-calls 20 — catch a burst shorter than a minute, which a sixty-second window averages into the ordinary traffic around it

• sudo sipnab -N -d eth0 --fraud-detect --fraud-volume-window 300 --fraud-wangiri-window 300 — a low-volume site where five minutes is the shortest span that holds enough calls to say anything about either pattern

• sipnab -N -I sbc.pcap --kill-scanner --scanner-behavioral-probes 200 --scanner-enumeration-targets 60 — an SBC that fronts a whole site behind one address, where ordinary aggregated traffic clears the shipped ten probes and five extensions within seconds

• sipnab -N -I slow-sweep.pcap --kill-scanner --scanner-window 600 --scanner-enumeration-targets 8 — hunt a paced sweep across a ten-minute window: one probe every ten seconds never puts two inside the shipped five-second window, so widening the window is the only setting that reaches it

• sudo sipnab -N -d eth0 --kill-scanner --scanner-window 60 --scanner-behavioral-probes 40 --scanner-rejected-probes 20 — a busy registrar that refuses every unauthenticated first attempt, so refusals only count as evidence once there are twenty of them in a minute

• sipnab -N -I sat-trunk.pcap --kill-scanner --scanner-answer-grace 3000 --scanner-unanswered-probes 20 — a satellite trunk whose round trip runs well past RFC 3261's Timer T1, where the shipped 500 ms grace calls every probe still in flight unanswered

• sudo sipnab -N -d eth0 --kill-scanner --scanner-established-factor 1 --scanner-rejected-probes 8 — judge a registered endpoint like any other source, for a site hunting compromised handsets rather than outside scanners

• sipnab -N -I pbx.pcap --kill-scanner --scanner-answer-grace 1500 --scanner-established-factor 8 --scanner-unanswered-probes 10 — a small PBX on a slow access circuit, where a registered phone needs eight times the evidence and every probe gets a second and a half to draw a reply

• sudo sipnab -N -d eth0 --kill-scanner --kill-rate-limit 2 --findings-history 20000 — answer scanners at a deliberately small two responses a second while keeping a long detection history for an agent to read back

• sipnab -N -I capture.pcap --kill-scanner --recommend-block nftables — read a capture you already have and print an nft rule per accused source, with the evidence and the counter-evidence in the same block. sipnab prints. You decide and run it

• sipnab -N -I trunk.pcap --kill-scanner --reg-flood --digest-leak --recommend-block all --quiet > blocks.txt — every dialect for every accused source on a trunk capture, with the packet echo suppressed so the file holds nothing but the recommendation. Read blocks.txt before running any of it: an address that also completed a call is one a block disconnects, and the block says so

• sudo sipnab -N -d eth0 --kill-target 192.0.2.66 --kill-rate-limit 50 --findings-history 0 — a targeted response with a wider transmit budget and no findings retained in memory

• sipnab -N -I capture.pcap --json --run-provenance-file /var/log/sipnab-runs.jsonl — record the invocation beside the report, so a reader can trace the JSON above back to the capture, the filters and the build that produced it

• sudo sipnab -N -d eth0 --portrange 5060-5090 --report --run-provenance-file /var/log/sipnab-runs.jsonl — the case the record exists for: the port range decided what this run could see, and without the record a later reader cannot tell a narrow run from a complete one

• sipnab -I capture.pcap --tui-audit-file /var/log/sipnab-tui.jsonl — record which capture the analyst opened, what they filtered it down to and what they exported, for the review that opens with "who exported which calls"

• sudo sipnab -d eth0 --tui-audit-file /var/log/sipnab-tui.jsonl --run-provenance-file /var/log/sipnab-runs.jsonl — both halves on a live capture: one line saying how the session started, and one record per state-changing thing the operator then did

• sipnab -N -d eth0 --mcp --tfps-ctl /usr/local/bin/tfps_ctl — serve the MCP tools with TFPS named outright, so tfps_status and tfps_banned answer from that installation rather than whatever PATH finds

• sipnab -N -I trunk.pcap --api 127.0.0.1:8080 --api-key "$SIPNAB_API_KEY" --tfps-ctl /opt/tfps/bin/tfps_ctl — replay a capture behind the REST API and let GET /v1/tfps/labels fetch the verdict log the label harness scores it against

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-signing-key-file /etc/sipnab/api.key --allow-action tfps:rest — let a REST caller holding a token minted with --token-scope actions ask TFPS to ban and unban through POST /v1/tfps/ban and /unban, and back a ban out through POST /v1/actions/revert. Every other credential still reads the TFPS routes and gets 401 on those three

• sudo sipnab -N -d eth0 --mcp --allow-action tfps:mcp — let the local agent this process serves over stdio call tfps_ban, tfps_unban and actions_revert. Without the flag the three tools refuse and name it, and the handshake tells the agent this server changes no external system

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-signing-key-file /etc/sipnab/api.key --allow-action tfps:rest --journal-dir /srv/sipnab/journal — the same REST actions with the journal on a dedicated volume rather than under /var/lib

• sipnab -N -I capture.pcap --mcp --allow-action tfps:mcp --journal-dir "$HOME/.local/state/sipnab/journal" — try the MCP ban tools as an unprivileged user, with the journal in your home directory instead of the system one

• sipnab --journal-show — list the bans sipnab placed that are still in force, with the action ids --revert-actions takes

• sipnab --journal-show --journal-dir /srv/sipnab/journal — the same for a journal kept somewhere other than the default, while the sipnab that writes it keeps running

• sudo systemctl stop sipnab && sudo sipnab --revert-actions all — after a stolen token or a bad automation run: stop the service, then lift every ban sipnab placed, newest first. Run as root, because changing TFPS's blocks needs privileges the service gets from its unit

• sudo sipnab --revert-actions a-r-68d9c1f2-4412-3 --tfps-ctl /opt/tfps/bin/tfps_ctl — with the service stopped, lift one ban by the action id --journal-show printed, asking the TFPS installation named outright

What a hook receives. Every command gets the event as environment variables.

• --on-dialog-exec sets SIPNAB_CALL_ID, SIPNAB_FROM, SIPNAB_TO, SIPNAB_STATE, SIPNAB_METHOD and SIPNAB_JSON (the whole dialog).
• --on-quality-exec sets SIPNAB_SSRC, SIPNAB_SRC, SIPNAB_MOS, SIPNAB_JITTER, SIPNAB_LOSS and SIPNAB_STREAM_JSON. That last one is the stream object under its own name, never SIPNAB_JSON.
• Rule hooks add SIPNAB_RULE, SIPNAB_DETAIL and SIPNAB_VARIABLE.

A hook inherits sipnab's whole environment, credentials included.

• sipnab does not clear the environment before spawning.
• So a hook sees SIPNAB_API_SIGNING_KEY, SIPNAB_MCP_TOKEN and SIPNAB_HEP_AUTH if you set them there. Authentication recommends exactly that.
• This is deliberate:
  • a hook that must call back into the API needs the credential,
  • stripping the environment would break that without making anything safer, since a hook already runs as you.

It does mean a hook command is as trusted as the process.

• Do not pass one a string built from capture data.
• Do not run one you would not run by hand with your keys exported.

Hooks cannot gain privileges.

• sipnab sets PR_SET_NO_NEW_PRIVS at startup on Linux. It does so on every run, whether or not it is root.
• Every command it spawns inherits that flag.
• A hook may run anything you can already run.
• What it cannot do is get more than you have through a setuid or setgid helper. sudo, pkexec and ping start, then fail for want of the privilege they normally acquire.

A hook that needs to act privileged should ask something that already is, rather than trying to become privileged itself. For example:

• a socket to a daemon,
• a systemd unit it triggers.

Root runs have always behaved this way. Unprivileged runs (sipnab --setup-caps) now do too.

Examples

• sudo sipnab -d eth0 --on-dialog-exec 'logger sipnab $SIPNAB_CALL_ID' --exec-rate-limit 5 --exec-queue-depth 20 — a slow syslog hook on a busy trunk, where twenty concurrent children is the ceiling events actually meet rather than the five-a-second budget
• sipnab -N -I trunk.pcap --on-quality-exec 'curl -m 30 -X POST http://hook/quality' --exec-queue-depth 4 — a webhook that may take thirty seconds, held to four in flight so a stalled endpoint cannot fork the box flat

Examples

• sipnab -N -I capture.pcap --no-hep-parse --report — read HEP datagrams as plain UDP when your config file sets [capture] hep_parse = true

• sipnab -N -I capture.pcap -E --no-hep-parse --report — the last of the pair wins, so HEP is not unwrapped

• sudo sipnab -d eth0 --api 127.0.0.1:8080 --api-signing-key-file /etc/sipnab/signing.key --api-revoked-file /etc/sipnab/revoked.txt --api-token-ttl 7200 --api-max-conn 200 --metrics 127.0.0.1:9090 --metrics-auth alice:s3cret — live capture serving a signed-token REST API, a revocation list, and a Basic-auth'd Prometheus endpoint (loopback, so no TLS)

• sudo sipnab -d eth0 --api 0.0.0.0:8080 --api-signing-key-file /etc/sipnab/signing.key --api-token-ttl 3600 --api-max-conn 100 --metrics 127.0.0.1:9090 --metrics-auth bob:hunter2 — public-facing API tuned to 100 connections and 1h token TTL, with its own auth'd metrics endpoint

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-key s3cret --api-max-rows 100000 --api-rate-limit-per-peer 0 — a batch consumer's API: one GET /v1/dialogs?limit=100000 drains the whole store in a single page, and the per-peer cap is off so a scripted pager is not throttled against itself

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-key s3cret --api-max-rows 200 --api-rate-limit-per-peer 600 — the opposite, for a dashboard: short pages a browser can render, and six hundred requests a second per address, so a dozen browsers refreshing twice a second behind one office NAT share an allowance that fits them

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-key s3cret --rtpengine-control 127.0.0.1:22222 --api-allow-relay-query — a live capture whose REST clients may also ask the relay: GET /v1/relay/stats returns its counters as one JSON object with an outcome, transmitting once per request. Off without this flag, when those routes answer not_permitted

• sipnab -N -I capture.pcap --api 127.0.0.1:8080 --api-key s3cret --api-allow-relay-query --rtpengine-control 127.0.0.1:22222 — the relay routes still answer on a file run, but with outcome: not_permitted: a file-backed run holds no transmit permit, so no packet reaches the relay, and the addresses in a capture belong to third parties

• sipnab -N -I capture.pcap --config sipnab.toml --api 127.0.0.1:8080 --api-key s3cret --api-allow-vcon-fetch — REST clients may read one vCon by uuid with GET /v1/vcon/fetch/:uuid from the store [vcon_fetch] names; without the flag that route answers 503

• sipnab -N -I capture.pcap --config sipnab.toml --api 127.0.0.1:8080 --api-key s3cret --api-allow-vcon-fetch --mcp --mcp-transport http --mcp-allow-vcon-fetch — both doors, each opted in by its own flag and reading the one store [vcon_fetch] names

• sipnab -N -I today.pcap --api 127.0.0.1:8080 --api-key s3cret --api-file-root /srv/pcaps --archive-password-file /etc/sipnab/pcaps.pw — the compare route opens password-protected ZIPs under /srv/pcaps with the operator's passwords, and a local client may add one per request in the Sipnab-Archive-Password header

• sipnab -N -I today.pcap --api 0.0.0.0:8080 --api-key s3cret --api-file-root /srv/pcaps --api-accept-archive-passwords — behind a TLS proxy on another host: remote clients may send Sipnab-Archive-Password, which without the flag get 403 because the password would cross the network in the clear

• sipnab -N -I today.pcap --api 127.0.0.1:8080 --api-key s3cret --api-file-root /srv/pcaps --api-accept-archive-passwords --archive-password-file /etc/sipnab/pcaps.pw — both at once: configured passwords first, then the request's

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-key s3cret --api-file-root /var/lib/sipnab/captures — a live capture whose REST clients may also diff rotations: GET /v1/captures/compare?a=yesterday.pcap&b=today.pcap reads two files from that one directory and nothing outside it, ranking what moved. Off without the flag, when the route answers 503

• sudo sipnab -N -d eth0 --api 0.0.0.0:8443 --api-signing-key-file /etc/sipnab/signing.key --api-tls-cert /etc/sipnab/api.pem --api-tls-key /etc/sipnab/api.key — a public-facing API over HTTPS with no reverse proxy: signed tokens, a certificate whose key is chmod 600, and no plain-HTTP warning at startup

• sudo sipnab -N -d eth0 --api 127.0.0.1:8080 --api-key s3cret --api-allowed-host sipnab.example.com — behind a reverse proxy that forwards Host: sipnab.example.com unchanged: sipnab serves that name, while a page that rebinds any other name to 127.0.0.1 gets 403

• sudo sipnab -N -d eth0 --api 0.0.0.0:8443 --api-signing-key-file /etc/sipnab/signing.key --api-tls-cert /etc/sipnab/api.pem --api-tls-key /etc/sipnab/api.key --api-allowed-host capture.example.com:8443 — a public-facing HTTPS API reached by name on port 8443 only: sipnab serves Host: capture.example.com:8443 and refuses the same name on any other port. Clients reaching it by IP address need no entry on a wildcard bind

• sipnab -N -I today.pcap --api 127.0.0.1:8443 --api-key s3cret --api-tls-cert api.pem --api-tls-key api.key — HTTPS on loopback, for a client that insists on https:// even on the same host; api.pem must name 127.0.0.1 for the client to accept it

• sipnab -N -I today.pcap --api 127.0.0.1:8080 --api-key s3cret --api-file-root /srv/pcaps — the compare route works on a file-backed run too: it diffs the two NAMED files under /srv/pcaps, never the loaded today.pcap, so a monitoring box can poll one sipnab for a rolling day-over-day comparison

• sudo sipnab -N -d eth0 --metrics 127.0.0.1:9090 --metrics-max-conn 64 — an HA Prometheus pair, a federating parent, a remote_write shard and an alertmanager sidecar all scraping one sipnab: at sixteen slots a slow scrape turns the next one away with 503, and the hole in the series reads as a capture that died

• sudo sipnab -N -d eth0 --metrics 127.0.0.1:9090 --metrics-max-conn 2 — a single scraper on a small box, where two slots covers every client this endpoint has, and a third connection is something to turn away

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-auth-mode hmac --hep-hmac-window 120 — a collector whose agents run on hardware with a drifting clock: two minutes of tolerance keeps them heard while someone repairs the NTP problem

• sipnab -N -L 127.0.0.1:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-auth-mode hmac --hep-hmac-window 5 — the opposite, where every agent shares a local time source: five seconds narrows the replay window a captured packet stays valid in

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-silence-warn 300 — a collector fed by PBXes that go quiet overnight: five minutes without an admitted packet before the listener warns, so a site with no calls overnight does not fill the journal

• sipnab -N -L 127.0.0.1:9060 --hep-parse --hep-silence-warn 0 — a lab listener fed by hand, where long silences are normal and the warning would only be noise

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --duration 300 --hep-senders — five minutes of a collector's feed, then the roster: which proxies sent and how much, which went silent, and which addresses the listener turned away and why

• sipnab -N -L 127.0.0.1:9060 --hep-parse --hep-senders --count 5000 --json — the same roster as one JSON object on the last line of stdout, after the per-message lines, for a script to pick up with tail -1

• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 --mcp-token t0ken-alice --mcp-signing-key-file /etc/sipnab/mcp-signing.key --mcp-revoked-file /etc/sipnab/mcp-revoked.txt --mcp-token-ttl 1800 — loopback HTTP MCP server with a bearer token, file-loaded signing key, revocation denylist, and a 30-minute mint TTL

• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-bind 0.0.0.0:8731 --mcp-token t0ken-bob --mcp-signing-key-file /etc/sipnab/mcp-signing.key --mcp-revoked-file /etc/sipnab/mcp-revoked.txt --mcp-allowed-host mcp.example.com — non-loopback HTTP MCP server (token required) accepting an extra Host header for named clients

• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-bind 0.0.0.0:8731 --mcp-token-file /etc/sipnab/mcp.token --mcp-allowed-host mcp.example.com --mcp-tls-cert /etc/sipnab/mcp.pem --mcp-tls-key /etc/sipnab/mcp.key — a non-loopback MCP server serving HTTPS itself, with no nginx in front: the bearer token and every tool result cross the network encrypted

• sipnab -N -I today.pcap --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 --mcp-tls-cert mcp.pem --mcp-tls-key mcp.key — HTTPS on loopback, for an agent that insists on https:// even on the same host; mcp.pem must name 127.0.0.1 for the agent to accept it

• sudo sipnab -N -d eth0 --hep-send 192.0.2.10:9060 --hep-id 42 --hep-auth s3cr3t-homer-key — forward captured packets to a Homer collector, stamping capture-agent id 42 and an authenticate key

• sudo sipnab -N -d eth0 --hep-send 198.51.100.20:9060 --hep-id 7 --hep-auth homerkey2 — forward to a second collector under a different agent id and auth key

• sudo sipnab -N -d eth0 --hep-send 198.51.100.30:9060 --hep-auth-file /etc/sipnab/hep.key --hep-auth-mode hmac — replay-resistant forwarding to another sipnab: HMAC-token auth over an untrusted path (both ends must set --hep-auth-mode hmac)

• sipnab -N -I archive.pcap --hep-send 127.0.0.1:9060 --hep-id 9 — replay an archived capture into a collector on this host. sipnab warns at startup that the file's signaling leaves the machine, then forwards it

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-auth-mode hmac — the matching sipnab-to-sipnab HMAC collector: verifies the per-message token and rejects replays

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-allow 192.0.2.0/24 --hep-allow 198.51.100.20/32 --hep-rate-limit 20000 — run a HEP collector that parses incoming packets, only from two allowed CIDRs, capped at 20k pkts/sec

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-rate-limit 40000 --hep-rate-limit-per-peer 5000 — authenticated HEP collector on a routable address: incoming packets must carry the shared secret, with a 5k/s per-peer fairness cap

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth-file /etc/sipnab/hep.key --hep-allow-kill --kill-scanner — authenticated HEP collector that may also actively kill scanners seen in the HEP stream (only safe because the feed carries authentication)

• sipnab -N -L 0.0.0.0:9060 --hep-parse --hep-auth s3cr3t-homer-key --hep-rate-limit-per-peer 2000 --hep-allow-kill --kill-target 198.51.100.7 — inline HEP secret (visible in the process list. Prefer --hep-auth-file.) with a tight per-peer cap for a busy multi-proxy fleet

• sudo sipnab -N -d eth0 --hep-send 192.0.2.10:9061 --hep-send-transport tcp --hep-id 42 — forward to a collector that speaks HEP over TCP, so a busy collector orders and keeps the feed instead of losing datagrams

• sipnab -N -I archive.pcap --hep-send 127.0.0.1:9061 --hep-send-transport tcp — replay an archived capture into a local TCP collector. The stream is packets laid end to end, framed by each HEP v3 header's total length

• sudo sipnab -N -d eth0 --hep-send collector.example.com:9063 --hep-send-transport tls --hep-tls-ca /etc/sipnab/collector-ca.pem — encrypted forwarding across a path you do not control, verifying the collector against your own issuer

• sudo sipnab -N -d eth0 --hep-send homer.example.net:9063 --hep-send-transport tls --hep-tls-ca /etc/pki/tls/certs/homer-ca.pem --hep-auth-file /etc/sipnab/hep.key — the same, with the Homer authenticate key inside the session as well as the session around it

• sudo sipnab -N -d eth0 --hep-send collector.example.com:9063 --hep-send-transport tls --hep-tls-extra-ca /etc/sipnab/collector-ca.pem — encrypted forwarding to a collector whose certificate comes from a private CA, while the host's public roots still count: the sender accepts a certificate from either

• sudo sipnab -N -d eth0 --hep-send homer.example.net:9063 --hep-send-transport tls --hep-tls-extra-ca /etc/sipnab/homer-ca.pem --hep-auth-file /etc/sipnab/hep.key — the same with the Homer authenticate key inside the session; compare --hep-tls-ca, which would trust only homer-ca.pem

• sipnab -N -L 0.0.0.0:9061 --hep-listen-transport tcp --hep-parse --hep-auth-file /etc/sipnab/hep.key — an authenticated TCP HEP collector: several proxies connect at once and sipnab reads each connection as a stream of HEP v3 packets

• sipnab -N -L 127.0.0.1:9061 --hep-listen-transport tcp --hep-parse — the loopback version, for an agent mirroring to a collector on the same host over a connection rather than datagrams

• sipnab -N -L 0.0.0.0:9063 --hep-listen-transport tls --hep-tls-cert /etc/sipnab/collector.pem --hep-tls-key /etc/sipnab/collector.key --hep-parse --hep-auth-file /etc/sipnab/hep.key — a TLS HEP collector: agents reach it over an encrypted stream and still prove who they are with the shared secret

• sipnab -N -L 0.0.0.0:9063 --hep-listen-transport tls --hep-tls-cert /etc/sipnab/collector.pem --hep-tls-key /etc/sipnab/collector.key --hep-parse --hep-allow 192.0.2.0/24 — the same listener bounded by source address instead: TLS encrypts the path, and --hep-allow is still what says which addresses may speak on it

• sipnab -N -I capture.pcap --metrics 127.0.0.1:9090 --metrics-auth-file /etc/sipnab/metrics.cred — loopback metrics endpoint reading its Basic-auth credential from a file (keeps user:pass out of the process list)

• sudo sipnab -d eth0 --metrics 0.0.0.0:9090 --metrics-auth-file /etc/sipnab/metrics.cred — routable metrics endpoint (non-loopback requires auth) using a file-backed credential. Terminate TLS at a reverse proxy

• sudo sipnab -N -d eth0 --metrics 0.0.0.0:9090 --metrics-auth-file /etc/sipnab/metrics.cred --metrics-tls-cert /etc/sipnab/metrics.pem --metrics-tls-key /etc/sipnab/metrics.key — the same routable endpoint serving HTTPS itself, so the Basic credential crosses the network encrypted with no reverse proxy; Prometheus scrapes it with scheme: https and the issuing CA in tls_config

• sipnab -N -L 127.0.0.1:9060 --hep-parse --metrics 127.0.0.1:9443 --metrics-tls-cert metrics.pem --metrics-tls-key metrics.key — HTTPS on loopback, for a scraper on the same host that only speaks https://; metrics.pem must name 127.0.0.1 for the scraper to accept it

• sipnab --mint-token --token-id alice-2026 --api-signing-key-file /etc/sipnab/signing.key --api-token-ttl 3600 — mint a signed bearer token with a fixed id (for later revocation) and a 1-hour TTL, then exit

• sipnab --mint-token --token-scope metrics --token-id prom-scraper --api-signing-key-file /etc/sipnab/signing.key --api-token-ttl 86400 — mint a scrape-only token for Prometheus: it reaches /metrics, and every /v1/ route refuses it

• sipnab --mint-token --token-scope full --token-id ops-oncall --api-signing-key-file /etc/sipnab/signing.key — the default scope, stated explicitly: full access to the REST API surface

--hep-send <ADDR> forwards every SIP message and every RTCP report sipnab reads to the collector at <ADDR>. It forwards them byte for byte as the capture holds them.

On a live capture that matches what the flag sounds like. Traffic passes the interface, and a copy reaches Homer.

Each datagram's IP protocol chunk carries the transport the message arrived on:

• 17 for UDP,
• 6 for TCP, TLS and WebSocket,
• 132 for SCTP.

A collector filtering by transport finds a TCP trunk under TCP.

RTCP travels as HEP protocol type 5. That is what lets a remote collector report media quality (loss, jitter, MOS) rather than only whether calls connect.

RTP is never forwarded.

• RTCP is a control channel that RFC 3550 section 6.2 holds to a small fraction of session bandwidth.
• So it carries the quality summary at a rate a WAN link and a UDP feed can absorb.
• The media itself is the opposite on both counts.
• Forwarding it would make this a call recorder pointed at the collector.

On -I <file> the same sentence carries a sharper meaning.

• The messages sipnab reads come out of the capture file.
• So that file's signaling leaves the machine:
  • request lines,
  • headers,
  • URIs,
  • any message bodies it holds.
• sipnab redacts nothing. It drops nothing beyond what --portrange and the matching flags already exclude.
• Testing a HEP pipeline against a customer capture therefore ships that customer's signaling to whatever <ADDR> names.

sipnab announces this before it reads the first packet:

WARN sipnab::app::bootstrap: --hep-send collector.example:9060 forwards every
SIP message and every RTCP report this run reads to that address, and this run
is reading a capture FILE (customer.pcap). The signaling in those captures
leaves this machine ...

That line is a warning rather than a refusal, because you chose the destination. Replaying an archive into your own collector stays a supported workflow. Two habits keep it uneventful:

• Name a collector you control.
  • sipnab never takes the destination from the capture.
  • The address always comes from your command line or your config file.
  • No code path exists that turns a recorded address into an export target.
• Read the startup warning before you walk away. It names the flag, the destination, and the capture files.

The scanner-kill path works the other way round and refuses to run offline.

• It aims at addresses recorded inside the capture.
• Those belong to third parties who have nothing to do with your analysis.
• So -I file grants it nothing at all. See Security.

A HEP packet names the transport of the message it carries in its IP protocol chunk (0x0002).

• The HEP3 specification defines that chunk as the IP protocol ID.
• sipnab reads 17 as UDP, 6 as TCP and 132 as SCTP.

OpenSIPS and Kamailio also send a decrypted TLS or WebSocket message over HEP.

• Its payload is plain SIP.
• No IP protocol number means TLS or WebSocket. So both proxies put a fake number in the chunk.
• Neither number tells WS from WSS.
• Kamailio's does not even tell TLS from WebSocket.
• So sipnab reads the number first. It lets the message's top Via narrow it to WS or WSS:

The last row exists because of how Kamailio traces a message it sends.

• It uses the protocol of the socket it sends from.
• A WebSocket connection's socket is a TCP one.
• So a reply to a WS client arrives as 6, and only its Via says WebSocket.
• The Via only ever narrows to WS or WSS.
• A Via naming UDP never turns a TCP leg into UDP.

The sources:

• OpenSIPS modules/tracer/tracer.c and its own receiver modules/proto_hep/proto_hep.c,
• Kamailio src/modules/siptrace/siptrace_hep.c, siptrace.c and siptrace_send.c.

The top Via names the transport of the hop a message travels on.

• RFC 3261 section 18.2.2 has a response travel back over the transport its Via names.
• RFC 7118 section 5.1 defines WS and WSS as Via transports.

The transport field of each --json message carries the name. So jq 'select(.transport == "WSS")' picks these legs out of a run that also captures the wire.

A WebSocket leg captured from the wire itself reports:

• WS when it is plain,
• WSS when sipnab decrypted it with --keylog.

--hep-parse reads a HEP datagram it finds on the wire or in a capture file by the same rule. A datagram whose number names no transport counts in the NOT DECODED line by that number, as a listener does.

sipnab applies all of this to HEP input only. On a frame read from an interface or a file, as before:

• 50 is a real IPsec ESP packet,
• sipnab refuses 22,
• 6 is TCP whatever the payload says.

Any other number a HEP sender puts in the chunk stays in the NOT DECODED line, by number.

Run sipnab as a Model Context Protocol server so an AI agent can drive it.

• See MCP Server for the full guide.
• Network Listeners lists the --mint-token / --token-id pair that issues MCP bearer tokens. It serves the REST API too.

Examples

• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab-exports — let an agent save captures and audio, confined to one directory
• sudo sipnab -N -d eth0 --mcp --mcp-file-root /var/spool/sipnab-exports --mcp-allow-shutdown — a live capture an agent may export from and, deliberately, stop
• sipnab -N -I capture.pcap --mcp --mcp-sampling-budget 20 — let sipnab ask the connected client's model to characterize an alert in a sentence, at most twenty times an hour. No API key in the config and no weights in the binary: the client already has a model, and this borrows it
• sipnab -d eth0 -N --mcp --mcp-sampling-budget 0 — sampling explicitly refused rather than left unset, which is what to write when a policy forbids sending observations to a model at all. The difference from omitting the flag is that this states the decision
• sipnab -N -I capture.pcap --mcp --mcp-allow-shutdown — a replay session an agent may end when it has finished. Nothing to lose, since the file is already on disk
• sipnab -N -I first.pcap --mcp --mcp-transport http --mcp-file-root /var/spool/sipnab-captures --mcp-allow-open-capture — a long-lived service an agent may move through a corpus with, one capture at a time
• sudo sipnab -N -d eth0 --mcp --mcp-evidence-ring 256 — a live capture an agent can quote FROM. Without it sipnab refuses every pointer into eth0, honestly: it holds parsed messages and not frames, so nothing remains to seek to. 256 MiB buys a window. Outside it the refusal reports that the ring dropped the frame rather than that the frame never existed
• sipnab -N -I capture.pcap --mcp --mcp-evidence-ring 64 — harmless and pointless together, which is worth knowing: a reader can open a capture file again, so the ring keeps nothing and never spends the 64 MiB. It holds frames only from a source nothing can read twice
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab-captures --mcp-allow-open-capture --mcp-allow-shutdown — the same, plus the ability to end the session. Both opt-ins are separate on purpose
• sipnab -N -I capture.pcap --config sipnab.toml --mcp --mcp-allow-vcon-fetch — let an agent read a vCon by uuid with fetch_vcon from the store the config file's [vcon_fetch] section names; the agent gives the uuid and never a URL or key
• sipnab -N -I capture.pcap --config sipnab.toml --mcp --mcp-transport http --mcp-allow-vcon-fetch --mcp-tools vcon — the same over HTTP, with only the vcon bundle loaded, so the agent can fetch a stored call and run analyze_vcon on it
• sipnab -N -I capture.pcap --mcp --mcp-allow-save-findings — let an agent write its conclusions into the log while it works through a capture. Read them back with journalctl -u sipnab, never through a tool
• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-allow-save-findings — a live triage session whose findings survive in the journal after the agent disconnects, without granting it any other write
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab-exports --retain-audio — hold call audio in memory so an agent can export_audio a WAV of a problem call
• sudo sipnab -N -d eth0 "portrange 5060-5061 or portrange 10000-20000" --mcp --retain-audio --mcp-file-root /var/spool/sipnab-exports — live capture with media in scope AND retained. Without --retain-audio the same run measures quality but keeps no payload to export
• sipnab -N -I dead-air.pcap --retain-audio --call-report <call-id> --json — no MCP server involved: retain the samples so the media diagnosis can measure them, and read diagnosis.amplitude for dead-air spans and clip runs with the thresholds that produced them
• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 --mcp-max-concurrent 8 — a network-facing MCP server that runs at most eight tool calls at once and refuses the ninth with a retry-shortly error rather than queueing it
• sipnab -N -I capture.pcap --mcp --mcp-max-concurrent 0 — a stdio replay for one trusted agent with no concurrency cap (0 = unlimited)
• sipnab -N -I capture.pcap --mcp --mcp-tools core — a small-context agent: nine tools instead of the whole surface, so the schema block sipnab sends it before it asks anything is a fraction of the size
• sipnab -N -I capture.pcap --mcp --mcp-tools core,relay,get_sdp_timeline — a small-context agent that also chases relay-side media: the core set, the relay bundle and one signaling tool, rather than every bundle
• sipnab -N -I capture.pcap --mcp --mcp-output-schemas — the whole surface with its output schemas, for a client that validates each response against the tool's declared shape
• sipnab -N -I capture.pcap --mcp --config sipnab.toml --mcp-output-schemas=false — a host config that turns output schemas on, overridden for one client that does not validate responses
• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-tools full — the default written out, for a service definition that should say what it offers rather than leave it to whatever the next release registers
• sipnab -N -I capture.pcap --mcp --quiet --mcp-audit-file /var/log/sipnab-mcp.jsonl — record every tool call to a file that survives --quiet, for the question asked after the fact rather than at the console
• sipnab -N -I sat-trunk.pcap --one-way-delay 280 — score MOS for a satellite trunk, where the real one-way delay is 280 ms. Without it sipnab falls back to the trunk's own RTCP and, on a capture carrying none, to an assumed 100 ms that reports roughly a full point too high, because G.107's delay penalty has a knee at 177.3 ms the assumption never crosses
• sipnab -N -I lan.pcap --one-way-delay 5 — a LAN capture, where assuming 100 ms understates the score. The declared figure also beats any round trip the far end reports or sipnab derives from RTCP, since no packet on the wire can rewrite a config value
• sipnab -N -I capture.pcap --mcp --mcp-max-rows 50 — cap every list-style MCP response at fifty rows, for an agent whose context window a thousand-row page would swamp. A caller asking for more gets fifty
• sipnab -N -I capture.pcap --mcp --mcp-max-rows 5000 — raise the ceiling above the 1000 default for a batch client that pipes whole pages to a file, where the round trips cost more than the bytes
• sipnab -N -I capture.pcap --mcp --mcp-max-body-bytes 65536 — let an agent read a whole INVITE with a long SDP body rather than the first 4096 bytes of it, on a capture whose bodies are what the investigation is about
• sipnab -N -I capture.pcap --mcp --mcp-max-rows 20 --mcp-max-body-bytes 512 — a small-context agent: few rows, and each one short, so a page of hits fits the window it has to reason in
• sipnab -N -I capture.pcap --mcp --mcp-max-response-bytes 65536 — no answer larger than 64 KiB, however many rows the caller asks for or however long their bodies run; a page that would pass it ends early with truncated_by: "bytes" and a cursor to the rest
• sipnab -N -I capture.pcap --mcp --mcp-max-rows 5000 --mcp-max-response-bytes 4194304 — a batch client allowed five thousand rows per page, with each answer still held to 4 MiB, so a page of long SIP messages ends early with a cursor rather than growing without a bound
• sudo sipnab -N -d eth0 --mcp --mcp-max-wait-seconds 300 — let an agent sit on a live capture for up to five minutes per await_condition call, on a box watching for a fault that reproduces slowly
• sudo sipnab -N -d eth0 --mcp --mcp-max-wait-seconds 5 — hold every wait to five seconds, for a host where MCP slots are scarce and a stalled agent must not occupy one
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-max-files 40 — let one find_in_captures call sweep a spool that rotates forty files, so the sweep reaches a call in the oldest file
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-max-files 40 --mcp-sweep-deadline-ms 120000 — the same spool of large files, with two minutes for the sweep to read them
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-deadline-ms 5000 — end every sweep after five seconds, for a host where MCP slots are scarce and one sweep must not hold a slot for longer
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-max-running 1 — run one sweep at a time, for a host whose capture spool sits on a single slow disk that two concurrent sweeps would share
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-max-running 8 --mcp-sweep-max-held-results 32 — let an agent run eight sweeps side by side on a spool spread over several disks, and hold four uncollected results per running sweep, the ratio the defaults carry
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-max-held-results 4 — hold at most four uncollected results, for a host where memory is scarce and agents poll each sweep they start
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-result-retention-secs 3600 — keep a finished result for an hour, for an agent that starts long sweeps and returns to them later in the session
• sipnab -N -I capture.pcap --mcp --mcp-file-root /var/spool/sipnab --mcp-sweep-result-retention-secs 60 — drop a result one minute after its sweep finished, for a scripted client that polls at once and never returns to a job it abandoned
• sudo sipnab -N -d eth0 --mcp --mcp-transport http --mcp-rate-limit-per-peer 20 — a network-facing MCP server where any one client may make twenty tool calls a second. sipnab answers the twenty-first that second with a retry-shortly error instead of serving it
• sipnab -N -I capture.pcap --mcp --mcp-max-concurrent 8 --mcp-rate-limit-per-peer 0 — bound how many calls run at once but put no cap on the arrival rate (0 = unlimited), for a scripted client that sweeps a capture as fast as it can
• sipnab -N -I capture.pcap --tls-key /etc/sipnab/tls-rsa.key --keylog /etc/sipnab/keys.log --allow-coredump — decrypt TLS 1.2 RSA-key-exchange SIP from a pcap using an RSA private key, with core dumps left enabled
• sipnab -N -I capture.pcap --srtp-keys /etc/sipnab/srtp.keys --dtls-keylog /etc/sipnab/dtls.log — decrypt SRTP media in an offline pcap from an SRTP master-keys file plus DTLS-SRTP handshake keys
• sudo sipnab -d eth0 --tls-key /etc/sipnab/tls-rsa.key --srtp-keys /etc/sipnab/srtp.keys --keylog /etc/sipnab/keys.log --keylog-watch --allow-coredump — live decrypt both SIP (RSA key) and SRTP media, watching the key log for new PFS session keys
• sudo sh -c 'ecapture tls -m keylog --keylogfile=/dev/stdout | sipnab -N -d eth0 --keylog-fd 0' — read SIP over TLS with no certificate and no restart of the SIP daemon: an eBPF extractor pulls session secrets out of the running daemon's OpenSSL. It pipes them straight in, so nothing is ever written to disk. sipnab cannot launch the extractor itself, because every child inherits PR_SET_NO_NEW_PRIVS and so can never acquire CAP_BPF
• sudo sipnab -N -d eth0 --keylog-fd 3 --user sipnab 3< /run/sip.keys — take the secrets on descriptor 3 opened by the shell, then drop to an unprivileged user for the capture itself. The pipe is already open, so nothing has to be reachable from /run afterwards
• sudo mkfifo -m 600 /run/sip.keys && sudo sipnab -N -d eth0 --keylog /run/sip.keys --keylog-watch — the same idea through a named pipe rather than a descriptor, for a producer started separately by systemd. sipnab opens the FIFO while still privileged. It does so before it drops to an unprivileged user and can no longer reach /run
• sudo sipnab -N -d eth0 --keylog /run/sip.keys --keylog-watch --tls-lockon-window 8388608 — read a carrier trunk that has been up for days without restarting it. The record counter is not on the wire, so a capture joining an established connection has to find it. The default reaches about a day of a trunk at ten records a second, and this raises the ceiling to roughly a week
• sipnab -N -I trunk.pcap --keylog keys.log --tls-lockon-window 4096 — narrow the search when reading a capture whose key log holds secrets for many unrelated connections, so a session that can never match gives up sooner instead of spending the run's trial budget
• sudo sipnab --uprobe-list — run this first. Report which TLS libraries processes on this host are actually mapping, and exit without installing a single probe. Answers the only question that matters before starting: is the daemon you care about using a library sipnab can read?
• sudo sipnab --uprobe-list --uprobe-flavor wolfssl — the same listing narrowed to one flavor, so the output says what this command would probe rather than what merely exists
• sudo sipnab -N --uprobe-tls — read SIP over TLS with no certificate, no key and no restart of the SIP daemon. sipnab probes every mapped TLS library, so one command covers a host running OpenSSL for one daemon and wolfSSL for another
• sudo sipnab -N --uprobe-tls --uprobe-flavor openssl — probe only the OpenSSL side on a mixed host, when the wolfSSL processes are something else entirely and their plaintext is not yours to read
• sudo sipnab -N --uprobe-tls --uprobe-library /usr/lib/x86_64-linux-gnu/libssl.so.3 — skip discovery and probe one named library, which is how you attach to a daemon that has not started yet: discovery can only see what is already mapped
• sudo sipnab -N --uprobe-tls --uprobe-library /proc/$(docker inspect -f '{{.State.Pid}}' opensips)/root/usr/lib/libssl.so.3 — probe the OpenSSL inside a container. The path a container process sees names a different file from sipnab's namespace, so the probe must go through /proc/<pid>/root or it silently attaches to the host's copy and captures nothing
• sudo sipnab -N --uprobe-tls --uprobe-library /opt/vendor/libtls-custom.so --uprobe-symbol vendor_write — probe a library sipnab cannot classify by name. Without --uprobe-symbol it refuses rather than guessing which function to attach to
• sudo sipnab -N --uprobe-tls --uprobe-library /usr/lib/libssl.so.3 --uprobe-symbol SSL_write_ex — probe OpenSSL 3's newer write entry point instead of the default SSL_write, for a daemon built against it. The argument positions match, so the probe shape does not change
• sudo sipnab -N --uprobe-tls --json — the same capture as JSON. Dialogs from this source carry uprobe:<comm>/<pid> as their interface and unspecified addresses with port 0, because a uprobe sees the bytes an application handed its TLS library and nothing about the socket beneath. sipnab names the process rather than inventing a peer
• sudo sipnab -N --uprobe-tls --uprobe-backend bpf --portrange 0-65535 — read SIP over TLS with the peer addresses. Verified live: a REGISTER and its 200 OK came back as 127.0.0.1:36160 -> 127.0.0.1:15061 and the reverse, each connection carrying its own ephemeral port. Widen --portrange, because a TLS trunk on 5061 is the exception and the port a uprobe reports is whatever the socket used
• sudo sipnab -N --uprobe-tls --uprobe-backend tracefs — the default, spelled out. Use it on a kernel without BTF, where the bpf backend cannot run at all. Dialogs then name the process instead of a peer
• sudo sipnab -N -I done.pcap --mcp --mcp-allow-tls-capture — let an agent decide, mid-investigation, that the answer is in traffic it cannot see, and start reading TLS plaintext itself. Finish the file source first: sipnab's stores have one writer, and a uprobe capture is a live one
• sudo sipnab -N -I done.pcap --mcp --mcp-allow-tls-capture --mcp-allow-save-findings — the same, plus somewhere for the agent to record what it concluded. Without --mcp-allow-tls-capture the agent can still call list_tls_libraries and report what a capture would have seen

--user does nothing unless the process is root.

• sipnab skips the drop when geteuid() != 0. It says so only at debug.
• Take the recommended install (--setup-caps, then run without sudo):
  • clap parses the flag,
  • the log line goes where nobody watches,
  • the drop never arms.
• That is the intended behavior. An unprivileged process has nothing to drop.
• This note exists because the flag's presence otherwise reads as a guarantee.

The platforms also differ.

• On Linux, root plus --user drops to that user.
• On macOS, sipnab skips the drop even as root unless you pass --user. Dropping to nobody strands the process without a per-user login session. That crashes CoreAudio the moment anything touches it.

Examples

• sipnab -N -I capture.pcap --priv-drop --report — drop privileges as usual when your config file sets [privilege] no_priv_drop = true

• sipnab -N -I capture.pcap --no-priv-drop --priv-drop --report — the last of the pair wins, so sipnab drops privileges

• sudo sipnab -d eth0 --user sipnab — live capture that drops root to the sipnab service user once the capture device is open

• sudo sipnab -d eth0 --user nobody --chroot /var/empty — long-running monitor that drops to nobody and confines itself to an empty chroot

• sudo sipnab -d eth0 --chroot /var/empty --no-priv-drop — chrooted capture that keeps root privileges for the whole run

• sudo sipnab --setup-caps — grant the binary the capture capabilities (cap_net_raw,cap_net_admin) so future runs work without sudo, then exit

Examples

• sudo sipnab -d eth0 --max-reassembly 50000 — live capture on a busy TCP/TLS trunk with a raised reassembly-session ceiling
• sipnab -N -I capture.pcap --cores 4 --max-reassembly 2000 — offline reconstruction sharded across 4 cores, with a tight reassembly bound for an untrusted capture
• sipnab -N -I calls.pcap --lint --lint-max-per-rule 3 --no-cli-print — keep the lint output to three repeats of any one rule, so a capture full of retransmissions still shows what else it trips
• sipnab -N -I calls.pcap --lint --lint-max-per-rule 500 --no-cli-print — the opposite: every repeat, for counting how often one rule actually fires
• sipnab -N -I calls.pcap --lint --lint-fail-on error --no-cli-print — honors the .sipnablint sitting beside calls.pcap, and names it on stderr with a count of what it silenced. A short finding list always says why it is short
• sipnab -N -I calls.pcap --lint --lint-suppress-file ci.sipnablint --no-cli-print — a suppression list of the pipeline's own, for a CI job whose tolerances differ from the tree's
• sipnab -N -I calls.pcap --lint --lint-no-suppress --no-cli-print — the full catalog, ignoring every suppression file, for auditing what the project has agreed to live with
• sipnab -N -I ring-00042.pcapng --max-metadata-file-bytes 8589934592 --report — read the embedded names and TLS secrets out of an 8 GiB ring member you captured yourself, which the shipped ceiling refuses outright
• sipnab -N -I ring-00042.pcapng --max-metadata-file-bytes 8589934592 --strip-secrets sanitized.pcapng — the same file, sanitized for handover. The copy costs roughly twice the ceiling in memory, so raise it only for a file you trust
• sipnab -N -L 0.0.0.0:9060 --hep-allow 192.0.2.0/24 --config collector.toml --max-capture-sources 100000 — a HEP collector whose collector.toml sets [limits] max_tracked_peers = 100000 for a large agent fleet: at the shipped 65536 sipnab refuses to start, exit 2, because the table could not hold every sender the listener may admit
• sipnab -N -I a.pcap -I b.pcap --max-capture-sources 2 --report — the smallest table two input files can run with; one less and sipnab refuses to start, naming the setting
• sipnab -N -I archive.pcapng.gz --max-gunzip-bytes 8589934592 --strip-secrets sanitized.pcapng — sanitize an 8 GiB pcapng you compressed yourself, without spending the disk that decompressing it by hand would need
• sipnab -N -I from-customer.pcapng.gz --max-gunzip-bytes 268435456 --report — the opposite, for a file that arrived from outside: a quarter-gigabyte ceiling on the embedded names and secrets sipnab reads out of it, so a gzip bomb wearing a capture's name cannot take the box down
• sipnab -N -I isup-trunk.pcap --max-tcp-buffer 1048576 --json-dialogs --no-cli-print — a carrier trunk whose SIP/TCP messages carry encapsulated ISUP bodies past 64 KiB: at the shipped ceiling sipnab cuts each one in half and reports it malformed, and at 1 MiB the same bytes produce the call
• sudo sipnab -d eth0 --max-tcp-buffer 262144 — watch a live SBC that answers with long Record-Route sets, holding a quarter-megabyte per TCP direction so a large response frames whole instead of arriving as two malformed fragments
• sudo sipnab -N -d eth0 --reassembly-ttl 600 --max-reassembly 50000 — a persistent SIP/TLS trunk to a carrier that goes quiet overnight: ten minutes of patience keeps the half-read stream, so the first segment of the morning continues a message rather than landing in the middle of one
• sipnab -N -I untrusted.pcap --reassembly-ttl 5 --max-reassembly 2000 — the opposite, for a capture from outside: a five-second wait drops a half-sent stream almost at once, so a peer that opens streams and never finishes them cannot hold state
• sipnab -N -I calls.pcap --mcp --mcp-allow-save-findings --mcp-max-findings 20000 — a long agent session over a large capture, where a thousand annotations is a session doing its job and the journal on this box can take twenty
• sipnab -N -I calls.pcap --mcp --mcp-allow-save-findings --mcp-max-findings 25 — a scripted agent run on a box with a small journal: twenty-five annotations, then sipnab refuses further writes and says so rather than filling the disk

--vcon-forward runs sipnab as the process that delivers an --export-vcon-dir spool to a vCon store.

• It captures nothing.
• sipnab refuses it beside any capture source, listener or export flag.
• The other flags in this section need it, except --vcon-spool-status. That flag reads a spool's state and runs on its own.
• Each flag but --vcon-forward, --vcon-forward-once, --vcon-forward-auth and --vcon-spool-status has a [vcon_forward] key in the config file. The flag overrides the key.
• Needs the vcon Cargo feature.
• More: Deliver the spool to a store.

Examples

• sipnab --vcon-forward spool --vcon-forward-url 'http://127.0.0.1:8000/vcon/external-ingress?ingress_list=sipnab' --vcon-forward-auth-file vcon-forward.auth --vcon-forward-once — deliver what is in spool to a self-hosted conserver's sipnab ingress list once, and exit 0 when the conserver accepted all of it
• sipnab --vcon-forward spool --vcon-forward-kind vcon-store --vcon-forward-url https://api.vcon.store --vcon-forward-auth-file vcon-store.key — keep delivering to vcon.store until stopped: the kind adds /v1/vcons, and sends the key in the file as Authorization: Bearer <key>
• sipnab --vcon-forward spool --vcon-forward-kind conserver --vcon-forward-url http://127.0.0.1:8000 --vcon-forward-auth-file conserver.key --vcon-forward-once — deliver to a self-hosted conserver's sipnab ingress list once: the kind adds /vcon/external-ingress?ingress_list=sipnab and sends the key as x-conserver-api-token
• sipnab --vcon-forward spool --config /etc/sipnab/vcon-store.toml — take every forwarder setting from a config file's [vcon_forward] section
• sipnab --vcon-forward spool --vcon-forward-url http://127.0.0.1:8000/v1/vcons --vcon-forward-auth 'Authorization: Bearer test-token' --vcon-forward-once — a test against a store on this machine, with the credential on the command line, where every user of the host can read it in the process list; for anything else, export SIPNAB_VCON_FORWARD_AUTH instead
• sipnab --vcon-forward spool --vcon-forward-kind conserver --vcon-forward-url http://127.0.0.1:8000 --vcon-forward-auth test-key --vcon-forward-once — the same with a bare key, which the conserver kind sends as x-conserver-api-token: test-key
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-backoff-first 10 --vcon-forward-backoff-cap 600 — a store that recovers slowly: wait 10 s after the first failed try, doubling to at most 10 minutes
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-backoff-first 1 --vcon-forward-backoff-cap 30 --vcon-forward-once — retry quickly, never waiting more than 30 s between tries
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-max-error-body 65536 --vcon-forward-once — keep up to 64 KiB of each refusal's answer in its <name>.error.json record
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-max-error-body 512 --vcon-forward-max-response-head 16384 — keep 512 bytes of each refusal, and treat an answer whose headers exceed 16 KiB as no answer
• sipnab --vcon-forward spool --vcon-forward-url https://proxy.example.com/vcon --vcon-forward-auth-file vcon.auth --vcon-forward-max-response-head 131072 --vcon-forward-once — a store behind a proxy that adds large headers: read up to 128 KiB of them
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-ca store-ca.pem --vcon-forward-timeout 10 — a store whose certificate a private CA issued: trust only that CA, and give up on a silent store after ten seconds rather than thirty
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-ca store-ca.pem --vcon-forward-interval 60 --vcon-forward-timeout 120 — a store across a slow link: pass over the spool once a minute and wait up to two minutes for each answer
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-extra-ca store-ca.pem — a store whose certificate a private CA issued, on a host whose CA bundle should still count: trust that CA as well as the host's bundle
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-extra-ca /etc/sipnab/store-ca.pem --vcon-forward-once — deliver once to such a store and exit
• sipnab --vcon-forward /var/spool/sipnab-vcon --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-done /var/spool/sipnab-vcon-sent --vcon-forward-failed /var/spool/sipnab-vcon-held --vcon-forward-interval 2 — keep delivered and refused containers beside the spool rather than inside it, on the same file system, and pass every two seconds
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-replace-url 'https://vcon.example.com/v1/vcons/{uuid}' --vcon-forward-once — a store that answers 409 for a uuid it holds: PUT the rewritten container to the uuid's own URL instead of filing it as refused
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-replace-url 'https://vcon.example.com/v1/vcons/{uuid}' --vcon-forward-done sent --vcon-forward-failed held — the same, polling, with the delivered and refused containers in sent and held
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-scitt-url https://ts.example.com --vcon-forward-scitt-sign-key scitt.key --vcon-forward-scitt-sign-cert scitt.crt --vcon-forward-scitt-issuer https://pbx.example.com/sipnab — register vcon_created and vcon_sent with the transparency service at https://ts.example.com/entries for each container delivered
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-scitt-url https://ts.example.com --vcon-forward-scitt-auth-file scitt.auth --vcon-forward-scitt-ca ts-ca.pem --vcon-forward-scitt-sign-key scitt.key --vcon-forward-scitt-sign-cert scitt-chain.pem --vcon-forward-scitt-issuer urn:example:pbx-1 --vcon-forward-once — the same once, to a service that needs a credential and has a certificate from a private CA
• sipnab --vcon-forward spool --config /etc/sipnab/forward.toml --vcon-forward-scitt-auth-file scitt-rotated.auth --vcon-forward-scitt-ca ts-ca-2026.pem — take the other forwarder and SCITT settings from the config file, and replace its transparency service credential and CA for this run
• sipnab --vcon-forward spool --vcon-forward-url https://vcon.example.com/v1/vcons --vcon-forward-auth-file vcon.auth --vcon-forward-content-type application/vcon --vcon-forward-once — a store that wants the registered vCon media type: send each JSON container as application/vcon
• sipnab --vcon-forward /var/spool/sipnab-vcon --vcon-forward-kind conserver --vcon-forward-url http://127.0.0.1:8000 --vcon-forward-auth-file conserver.key --vcon-forward-content-type application/vcon+json — send each JSON container to a conserver as application/vcon+json; a gzip format container still goes as application/vcon+gzip
• sipnab --vcon-spool-status spool — print how many containers wait in spool, how many the forwarder delivered and refused, and the store's answer for each refusal
• sipnab --vcon-spool-status /var/spool/sipnab-vcon — the same for a spool given by absolute path; a spool the capture has not written yet prints zeros and "exists": false

--vcon-fetch runs sipnab as the process that reads stored vCons back from a store by uuid and writes each to a file.

• It captures nothing.
• sipnab refuses it beside any capture source, listener or export flag, and beside --vcon-forward.
• The other flags in this section need it.
• Each flag but --vcon-fetch, --vcon-fetch-out and --vcon-fetch-overwrite has a [vcon_fetch] key in the config file. The flag overrides the key.
• Needs the vcon Cargo feature.
• More: Fetch a stored vCon.

Examples:

• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind vcon-store --vcon-fetch-url https://api.vcon.store --vcon-fetch-auth-file vcon-store.key --vcon-fetch-out fetched — read one vCon from vcon.store: the kind adds /v1/vcons/{uuid}, sends the key as Authorization: Bearer <key>, and removes the _meta member the store adds
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-out fetched — read one from a self-hosted conserver: the kind adds /vcon/{uuid} and sends the key as x-conserver-api-token
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind vcon-mcp --vcon-fetch-url http://127.0.0.1:3000 --vcon-fetch-auth-file vcon-mcp.key --vcon-fetch-out fetched — read one from a vcon-mcp server's REST API: the kind adds /api/v1/vcons/{uuid}, sends the key as Authorization: Bearer <key>, and keeps the vcon member of the answer
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-url 'https://vcon.example.com/store/{uuid}' --vcon-fetch-auth-file vcon.auth --vcon-fetch-out fetched — a store of no listed kind: the URL template says where the uuid goes, and the auth file holds the full header line
• sipnab --vcon-fetch - --vcon-fetch-kind vcon-store --vcon-fetch-url https://api.vcon.store --vcon-fetch-auth-file vcon-store.key --vcon-fetch-out fetched < uuids.txt — read every uuid listed in uuids.txt, one per line
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-out fetched --vcon-fetch-overwrite — read it again, replacing the file an earlier run wrote
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-url 'https://vcon.example.com/store/{uuid}' --vcon-fetch-auth-file vcon.auth --vcon-fetch-ca store-ca.pem --vcon-fetch-timeout 10 --vcon-fetch-max-size 268435456 — a store whose certificate a private CA issued, holding containers up to 256 MiB: trust only that CA, and give up on a silent store after ten seconds
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-url 'https://proxy.example.com/vcon/{uuid}' --vcon-fetch-auth-file vcon.auth --vcon-fetch-max-response-head 131072 — a store behind a proxy that adds large headers: read up to 128 KiB of them
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --config /etc/sipnab/vcon-store.toml — take every fetcher setting from a config file's [vcon_fetch] section
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind vcon-store --vcon-fetch-url https://api.vcon.store --vcon-fetch-auth-file vcon-store.key --vcon-fetch-out fetched --vcon-fetch-overwrite --vcon-fetch-timeout 120 — replace an earlier copy across a slow link, waiting up to two minutes for each read
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url https://conserver.example.com --vcon-fetch-auth-file conserver.key --vcon-fetch-ca conserver-ca.pem --vcon-fetch-max-size 1048576 --vcon-fetch-max-response-head 16384 — a conserver whose certificate a private CA issued, holding containers without inline audio: refuse any answer over 1 MiB, or with more than 16 KiB of headers
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url https://conserver.example.com --vcon-fetch-auth-file conserver.key --vcon-fetch-extra-ca conserver-ca.pem — a conserver whose certificate a private CA issued, on a host whose CA bundle should still count: trust that CA as well as the host's bundle
• sipnab --vcon-fetch - --vcon-fetch-kind conserver --vcon-fetch-url https://conserver.example.com --vcon-fetch-auth-file conserver.key --vcon-fetch-extra-ca /etc/sipnab/conserver-ca.pem --vcon-fetch-out fetched < uuids.txt — fetch every vCon listed in uuids.txt from such a store
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-out fetched — read an encrypted vCon from a conserver, decrypt it with the recipient's private key, verify its signature, and write the unsigned vCon
• sipnab --vcon-fetch - --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-out fetched < uuids.txt — decrypt every vCon listed in uuids.txt, one uuid per line; the fetcher writes a container that is not encrypted as the store holds it
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-signer-ca signing-ca.pem --vcon-fetch-out fetched — decrypt a vCon and write it only when the CA in signing-ca.pem issued its signing certificate
• sipnab --vcon-fetch - --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-signer-ca system --vcon-fetch-out fetched < uuids.txt — decrypt every vCon listed in uuids.txt and write each only when a CA in the host's CA bundle issued its signing certificate
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-signer-sha256 40:97:43:61:0C:C7:47:BD:40:82:E2:28:1C:53:A6:54:88:74:EB:E7:A7:2B:E4:A3:C8:CB:1B:CA:C8:97:BC:D6 --vcon-fetch-out fetched — decrypt a vCon and write it only when one known certificate signed it
• sipnab --vcon-fetch 018bcfe5-6800-8a6b-a667-78f1c5213800 --vcon-fetch-kind conserver --vcon-fetch-url http://127.0.0.1:8000 --vcon-fetch-auth-file conserver.key --vcon-fetch-decrypt-key recipient.key --vcon-fetch-signer-ca signing-ca.pem --vcon-fetch-signer-sha256 409743610cc747bd4082e2281c53a6548874ebe7a72be4a3c8cb1bcac897bcd6 --vcon-fetch-out fetched — require both: the signing certificate chains to signing-ca.pem and has this fingerprint

--vcon-resign re-signs a signed vCon for a long-term archive, as draft-ietf-vcon-vcon-core-04 section 5.2.3 describes. It reads one file and writes one, and captures nothing.

Examples

• sipnab --vcon-resign signed/0158a120-0392-8337-ae55-829bc914b643.vcon.json --vcon-resign-key archive.key --vcon-resign-cert archive.crt --vcon-resign-out archived.vcon.json — re-sign one signed vCon with the archive's key before its signing certificate expires
• sipnab --vcon-resign archived.vcon.json --vcon-resign-key archive-2036.key --vcon-resign-cert archive-2036.crt --vcon-resign-out archived-2036.vcon.json — re-sign the archive again with the next key: the result nests three signed layers
• sipnab --vcon-resign signed.vcon.json --vcon-resign-key archive.key --vcon-resign-cert archive-chain.pem --vcon-resign-out archived.vcon.json --vcon-signer-ca signing-ca.pem — re-sign only a vCon whose signer the CA in signing-ca.pem issued
• sipnab --vcon-resign signed.vcon.json --vcon-resign-key archive.key --vcon-resign-cert archive.crt --vcon-resign-out archived.vcon.json --config /etc/sipnab/sipnab.toml — take the signer checks from the config file's [vcon_input] section

--vcon-audio-fetch reads back the audio a [[vcon.rule]] with audio = "url" wrote beside its container. It reads one container, fetches each recording the container names by url, and captures nothing.

• It reads the container in any form -I reads: unsigned, signed, encrypted or gzip. --vcon-key, --vcon-signer-ca and --vcon-signer-sha256, or their [vcon_input] keys, open it.
• sipnab refuses it beside any capture source, listener or export flag, and beside the forwarder, the fetcher, --vcon-spool-status and --vcon-resign.
• The other flags in this section need it. None has a config key.
• Needs the vcon Cargo feature.
• More: Fetch the audio a vCon names.

Examples

• sipnab --vcon-audio-fetch fetched/0158a120-0392-891a-9455-bc2e6fad94df.vcon.json --vcon-audio-fetch-out audio --vcon-key recipient.key — fetch, check and decrypt the audio of one encrypted vCon from the storage its url names
• sipnab --vcon-audio-fetch spool/0158a120-0392-891a-9455-bc2e6fad94df.vcon.json --vcon-audio-fetch-out audio --vcon-audio-fetch-local --vcon-key recipient.key — read the audio from the spool beside the container instead
• sipnab --vcon-audio-fetch call.vcon.json --vcon-audio-fetch-out audio --vcon-audio-fetch-ca media-ca.pem --vcon-audio-fetch-max-size 268435456 — storage whose certificate a private CA issued, holding recordings up to 256 MiB
• sipnab --vcon-audio-fetch call.vcon.json --vcon-audio-fetch-out audio --vcon-audio-fetch-extra-ca media-ca.pem — trust that CA as well as the host's bundle
• sipnab --vcon-audio-fetch fetched/0158a120-0392-891a-9455-bc2e6fad94df.vcon.json --vcon-audio-fetch-out audio --vcon-key recipient.key --vcon-audio-fetch-ca media-ca.pem — decrypt the audio of an encrypted vCon from storage whose certificate only that CA issued
• sipnab --vcon-audio-fetch fetched/0158a120-0392-891a-9455-bc2e6fad94df.vcon.json --vcon-audio-fetch-out audio --vcon-key recipient.key --vcon-audio-fetch-extra-ca media-ca.pem --vcon-audio-fetch-max-size 1073741824 — the same, trusting the host's bundle too, for a recording up to 1 GiB

Examples

• sipnab --config /etc/sipnab/sipnab.toml --dump-config — dump the effective configuration produced by a specific config file, then exit
• sipnab --no-config --dump-config — dump the built-in defaults, skipping any configuration file, then exit
• sudo sipnab -d eth0 --config ~/.config/sipnab/config.toml — live capture using a per-user configuration file
• sipnab -N -I capture.pcap --no-config — analyze an offline pcap with all configuration files ignored
• sipnab --completions bash > sipnab.bash — print a bash completion script into a file suitable for /etc/bash_completion.d
• sipnab --completions zsh > _sipnab — print a zsh completion script into a file suitable for the zsh fpath

• Output flags (--json, --json-pretty, --report, --hexdump, --fail2ban) require -N / --no-tui mode, unless --call-report is also specified.
• --kill-response accepts values 100-699 only.
• Feature-gated flags (tls, hep, api, mcp, mcp-http) produce startup errors when the required feature is not compiled in.
• --mcp is incompatible with stdout-writing flags. sipnab refuses to start.
  • The flags are --json, --json-pretty, --report, --call-report, --hexdump, --wireshark and --tshark-filter.
  • This holds on every transport, not just stdio.
  • Combine --mcp with --quiet to suppress text-mode capture output.
• HTTP MCP transport (--mcp --mcp-transport http) on a non-loopback --mcp-bind requires --mcp-token / --mcp-token-file / SIPNAB_MCP_TOKEN. Loopback binds need no token.

• sipnab -d eth0 — capture on eth0
• sipnab -I capture.pcap — read from pcap file
• sipnab -N --json -I capture.pcap — non-interactive JSON output
• sipnab --problems — show problematic calls
• sipnab --kill-scanner -d eth0 — detect SIP scanners
• sipnab --from alice --to bob — filter by From/To headers
• sipnab 'host 192.0.2.1 and port 5060' — BPF display filter
• sipnab --filter "method == 'INVITE' AND rtp.mos < 3.0" — advanced filter DSL
• sipnab -N -I capture.pcap --call-report "abc123@host" --markdown --no-cli-print — generate detailed report for a call (drop --no-cli-print and the whole capture's message dump precedes it)
• sipnab -d eth0 -H 192.0.2.50:9060 — capture with HEP mirror
• sipnab -d eth0 --keylog /tmp/sslkeys.log --keylog-watch — live TLS decryption

Scripts can rely on these:

Error messages lists the message sipnab prints with a non-zero exit code, what it means, and what to do.

A run may read its input in full and stop where you asked it to stop (-l/--limit, --duration). It still exits 0.

• The distinction is whether sipnab failed to do what you asked.
• It is not whether it read everything there was.

1 says something went wrong.

• It cannot say what.
• A consumer reading --json-dialogs on a pipe never sees it at all.

So a run that could not deliver the whole answer also says so in its output:

• --json-dialogs emits one extra NDJSON line, after the dialogs.
  • The line is under a top-level sipnab_run key that no dialog object has.
  • A clean run emits nothing extra. So runs with nothing wrong with them look exactly as they do today.
• --report ends with an INCOMPLETE RUN block naming each reason.

{"sipnab_run":{"input_complete":false,"reasons":["1 of 1 capture file(s) was not read to the end; every report from this run rests on a partial read"],"files":{"given":1,"read_in_full":0,"stopped_early":1,"skipped":0,"not_reached":0},"plugins":{"requested":0,"loaded":0,"failed":0},"retention":{"messages_dropped":0},"archives":{"cut_short":false},"port_gate":{"sip_outside_portrange":0,"sip_outside_ws_ports":0}}}

input_complete is the same predicate as the exit status. So a script reading stdout and a script reading $? cannot reach different verdicts.

archives.cut_short is true when sipnab could not unpack an archive -I named to its end. That happens when:

• the archive stops early,
• a header fails its checksum,
• or the walk reaches a ceiling.

Members past that point are in no report. That is data missing from the input. It fails the run like a truncated file does.

retention.messages_dropped counts captured messages that idle compaction discarded ([limits] idle_compact_after_secs).

• It appears because those ladders are short.
• It is deliberately NOT a failure. A retention policy doing what you configured it to do is not a run that went wrong.

port_gate counts SIP that sipnab did not analyze because of the port it used:

• sip_outside_portrange for messages with both ports outside --portrange,
• sip_outside_ws_ports for SIP over WebSocket on a port outside the WebSocket port set (--ws-portrange).

Like retention, it is not a failure, because the range is what you asked for. --report names either count in its INCOMPLETE RUN block. It uses the words the run summary uses on stderr:

INCOMPLETE RUN — this report does not describe the whole capture:
  - 12 SIP message(s) were seen on ports outside --portrange and were not analyzed; re-run with --portrange 1-65535 to include them