Documentation

Documentation

Start from what you need to do, from your role, or from the full index of every sipnab page.

What is sipnab?

sipnab is a network analysis tool for Voice over IP.

  • It captures and decodes SIP signaling. SIP is the protocol that sets up, modifies, and tears down calls.
  • It also captures the RTP media streams carrying the audio.
  • It correlates the two. So you can see a call as a call rather than as a pile of packets.

It is one Rust binary. The same executable gives you:

  • an interactive terminal UI,
  • a headless CLI for scripts and CI,
  • a REST API,
  • and an MCP server for AI agents.

There is no daemon, no database, and no runtime to install.

Who it is for

  • VoIP engineers debugging call setup failures, one-way audio, and codec or NAT problems.
  • SRE and on-call teams who need either of these:
    • a fast answer from a pcap at 3 AM,
    • or a headless run that exits non-zero when the Call-ID they asked about is not in the capture.
  • Security teams auditing SIP-facing infrastructure for scanners, registration floods, toll fraud, and leaked credentials.

What it does

Capture and decode.

  • Inputs: live interfaces, pcap/pcapng files, or a HEP/EEP listener fed by Kamailio, OpenSIPS, or FreeSWITCH.
  • sipnab parses SIP over UDP, TCP, TLS, SCTP, and WebSocket.
  • This includes IP fragmentation and TCP stream reassembly.
  • All 19 compact header forms resolve. They come from RFC 3261 and the IANA registry.
  • So a message using f:/t:/i: is not a blind spot.

Cross-check the proxy against the wire.

  • One run can take a HEP mirror and a live interface at once.
  • It reports where the two disagree:
    • messages the proxy believes it sent that never reached the wire,
    • traffic on the wire the tracing never reported,
    • and messages both saw carrying different SDP.
  • A mirror answers “what does the proxy think it did”.
  • The interface answers “what actually left the box”.
  • Asking the suspect twice cannot tell you the proxy is misconfigured. See the Cookbook.

Correlate calls.

  • sipnab follows dialogs across their lifetime.
  • It links them to their media through SDP.
  • sipnab renders the result as a call list, a ladder-style call flow, and per-message detail.

Analyze media.

  • sipnab finds RTP streams in the packets themselves. So media is still analyzed when the signaling was never captured.
  • sipnab computes:
    • interarrival jitter (the RFC 3550 algorithm),
    • loss,
    • MOS estimates,
    • and a sequence-space loss map that distinguishes bursty loss from diffuse loss.
  • It decodes RFC 4733 DTMF.
  • It exports G.711 (PCMU/PCMA) and Opus streams as audio.

Decrypt.

  • With a TLS key log, sipnab decrypts TLS-carried SIP and SRTP in place.
  • So encrypted captures stay readable without terminating the session elsewhere.

Detect.

  • Opt-in detectors for:
    • SIP scanning (--kill-scanner),
    • registration floods (--reg-flood),
    • fraud heuristics (--fraud-detect),
    • and digest credential leaks (--digest-leak).
  • Alerts go to syslog, JSON, or an external command.
  • There is also a fail2ban-compatible output.

Integrate.

  • JSON/NDJSON for pipelines.
  • A REST API (--api).
  • A Prometheus endpoint (--metrics).
  • An MCP server (--mcp) over stdio or streamable HTTP. So an AI agent can query captures directly.

There is also a browser analyzer at /analyze/.

  • It runs the same parsing core compiled to WebAssembly.
  • It is a separate build from the CLI binary.
  • Your pcap never leaves your machine.

Quick start

Analyze a pcap file in the TUI:

sipnab -I capture.pcap

Capture live on eth0. Live capture needs packet permissions.

  • Run sudo sipnab --setup-caps once on Linux to grant them.
  • Drop the sudo afterwards:
sudo sipnab -d eth0

Headless, reporting only the calls that went wrong as NDJSON.

  • -N is headless mode.
  • --json emits one JSON object per line.
  • So this one drops straight into jq or a log pipeline:
sipnab -N -I capture.pcap --problems --json

What is in your build

sipnab’s optional subsystems are Cargo features. So what a given binary supports depends on how someone built it:

BuildIncluded
Official Linux (glibc) and macOS releasesEverything: TUI, TLS/SRTP decryption, HEP, REST API, MCP (stdio + HTTP), Prometheus metrics, audio playback
Static musl binaries and the -noaudio .deb / .rpmThe same, minus audio playback. Everything else, WAV export included, stays the same
cargo build from source with no flagsTUI, audio, and metrics only — no TLS decryption, HEP, REST API, or MCP. Use --features full for everything
Any build, plus --features pluginsWASM plugin host (--plugin). Off by default so a stock binary carries no interpreter — see WASM plugins
A build with --features bpf, on a BTF kerneleBPF TLS capture, which reads plaintext with no key and no certificate — see the uprobe walkthrough

sipnab --version prints the feature list compiled into your binary.

Where to go next

All docs