sipnab

Read a SIP call and see why it failed. SIP is the signaling protocol that sets up and tears down voice calls. sipnab reads that signaling from a live network interface, a pcap (packet capture) file, or a HEP feed that your SIP proxies send (HEP copies each SIP message to a collector over the network). From an interface or a file it also reads the RTP audio packets underneath, and grades their quality. It shows you the call flow, the audio quality, and the security signals around each call.

sipnab is one binary with no database and no web UI to run. You can point it at one box's traffic, or have every proxy in a cluster send it HEP, so one listener sees calls across many nodes without anything installed on the production hosts. It keeps what it sees in memory and answers through its terminal view, a command line, a REST API, and an MCP server.

You can try it without installing anything: sipnab.com/analyze reads a pcap in your browser without uploading it. The full documentation lives at sipnab.com and in docs/. The Glossary defines the terms these pages use.

Install

On Linux (x86_64 or aarch64) or macOS:

curl -fsSL https://sipnab.com/install.sh | sh

The script picks the build for your OS, CPU and glibc, checks it against the release's .sha256 file, and installs it to /usr/local/bin (using sudo only if that directory is not writable). You can read the script first. To confirm the install, run sipnab --version: it prints the version and the features compiled in.

Other ways in:

You want	Do this
Homebrew on macOS	brew install NormB/tap/sipnab
A .deb or .rpm, including -noaudio builds for headless servers	Install with your package manager
A static Linux binary with no libpcap dependency (musl)	Release artifacts
To prove a download is genuine (checksums, build provenance, SBOM)	Verify a download is genuine
To build it yourself	Build from source, below

Your first ten minutes

Here are four common starting points. Each one ends with a link to the page that goes further.

1. Triage a capture file

Reading a file needs no root and no network interface, so it is the easiest place to start. This sample holds one completed call and four failed ones:

curl -LO https://github.com/NormB/sipnab/raw/main/tests/pcap-samples/sip-problem-call.pcap

Open it in the TUI (text user interface), the interactive full-screen view. Press F1 for the keys each view accepts. To quit, press q and then y to confirm, or Ctrl-C to quit at once:

sipnab -I sip-problem-call.pcap

Or stay on the command line. -N skips the TUI and prints to the terminal. List every call in the file, with its final status code, as a report table:

sipnab -N -I sip-problem-call.pcap --report --no-cli-print

Print only the messages of calls that failed or sounded poor, as JSON you can pipe into jq:

sipnab -N --json -I sip-problem-call.pcap --problems

Explain one call. A Call-ID is the SIP header that names a call, and the report table above lists them:

sipnab -N -I sip-problem-call.pcap --call-report 'busy-3a2b1c@192.0.2.30' --no-cli-print

Next: Triage a capture from the command line walks through these commands with their output, and Your first analysis in the TUI does the same interactively.

2. Watch live traffic

Live capture on Linux needs raw-socket access. Rather than running sipnab as root, grant the binary the two capabilities once, then run it as yourself:

sudo sipnab --setup-caps

Then capture on an interface. Replace eth0 with yours, which ip link lists:

sipnab -d eth0

For a stream of JSON, one SIP message per line, add -N --json:

sipnab -N -d eth0 --json

Re-run --setup-caps after each upgrade, because replacing the binary clears its capabilities. On macOS, run live capture with sudo instead. Capture live traffic without root explains the privilege model, and Tune capture on a busy server covers packet loss.

3. Receive HEP from your proxies

Kamailio, OpenSIPS and Asterisk can each mirror their SIP traffic over HEP, so one sipnab listener sees the calls of every node without anything installed on the production hosts. A listener on a routable address must name the senders it accepts (--hep-allow) or share a secret with them (--hep-auth-file). Otherwise sipnab refuses to start it:

sipnab -N -L 0.0.0.0:9060 --hep-allow 192.0.2.10

To try it on one machine, bind to loopback and replay a capture into it from a second terminal with -H (HEP send):

sipnab -N -L 127.0.0.1:9060

sipnab -N -I sip-problem-call.pcap -H 127.0.0.1:9060

A proxy's HEP feed carries its SIP signaling, not the call audio, so for audio quality run sipnab where the media flows as well. Run sipnab beside OpenSIPS, Run sipnab beside Kamailio and Connect sipnab to Homer set this up end to end, TLS transport included.

4. Serve the REST API, metrics and MCP

sipnab can answer other programs while it captures. Choose an API key and keep it in the environment, where sipnab reads it and where ps cannot see it:

export SIPNAB_API_KEY="$(openssl rand -hex 32)"

Serve the REST API and Prometheus metrics on loopback. The process keeps serving until you press Ctrl-C:

sipnab -N -I sip-problem-call.pcap --api 127.0.0.1:8080 --metrics 127.0.0.1:9100

curl -H "Authorization: Bearer $SIPNAB_API_KEY" http://127.0.0.1:8080/v1/dialogs

MCP (Model Context Protocol) lets an AI agent, such as Claude Code, call sipnab's analysis as tools. Over stdio, the default transport, the agent starts sipnab itself, so this is the command you register with your MCP client (--mcp-transport http serves remote agents instead):

sipnab --mcp -N -I sip-problem-call.pcap --mcp-tools core

The server offers 74 tools, and every tool costs the agent context before it asks anything. --mcp-tools core loads a small set that still answers a whole call. Named bundles such as signaling and media, and bundles of your own in the config file, load other sets (Choosing which tools load).

Next: REST API and metrics, Prometheus metrics, MCP server, and Connect an AI agent to sipnab.

Security basics

• Privileges. Reading files needs none. For live capture, prefer sudo sipnab --setup-caps to running as root. Started as root, sipnab opens the capture device and then drops to an unprivileged user (nobody, or --user); --chroot confines it further.
• Listeners bind to loopback by default. On a routable address, the REST API refuses to start without --api-key or --api-signing-key, MCP over HTTP without --mcp-token or --mcp-signing-key, and the metrics endpoint without --metrics-auth. Set up authentication covers signed tokens, rotation and revocation.
• TLS. The REST API, MCP over HTTP and the metrics endpoint each serve HTTPS themselves when given a certificate and key: --api-tls-cert / --api-tls-key (API TLS), --mcp-tls-cert / --mcp-tls-key (MCP TLS) and --metrics-tls-cert / --metrics-tls-key (Metrics TLS), or the matching tls_cert / tls_key keys in sipnab.toml. HEP can use TLS in both directions (--hep-listen-transport tls, --hep-send-transport tls), and the sender either trusts only a named CA (--hep-tls-ca) or adds one to the host's bundle (--hep-tls-extra-ca).
• Sending. Capture is passive. The features that send are off until you ask for them, for example HEP forwarding (-H), reverse DNS (--reverse-dns), and --kill-scanner and -K, which on a live interface answer scanners with SIP responses. When sipnab reads a capture file, it sends no scanner responses.
• The threat model. Threat model and security assessment lists the assets, trust boundaries, mitigations and known gaps.

What it does

• Several ways to read the results. The interactive TUI, the non-interactive CLI (-N), JSON (--json, one message per line), reports, the REST API, and the MCP server
• Call analysis. Dialog state, PDD (post-dial delay, the wait before ringing), SIP header matching (--from, --to and the rest), and a filter language of 33 fields, 8 operators and boolean logic
• Diagnostic aliases. --problems, --slow-setup, --short-calls, --one-way and --nat-issues as flags; codec-asym, ptime-asym, payload-asym, duration-asym and late-media through --filter (for example sipnab -N -I capture.pcap --filter codec-asym)
• RTP quality. Jitter, loss, MOS (mean opinion score, an estimate of how the call sounded, from the ITU-T G.107 E-model; where it comes from), RTCP XR (RFC 3611) reports, and one-way audio
• Security analysis. Scanner detection, registration floods, digest credential leaks, STIR/SHAKEN, and fraud heuristics, with alerts to syslog, JSON or a command of your own (--alert, --alert-exec). It can write fail2ban input (--fail2ban), and ask TFPS to ban a source, which is an action that stays off until --allow-action enables it
• HEP v3 send over UDP, TCP or TLS, and HEP v1/v2/v3 receive
• TLS and SRTP decryption. From an SSLKEYLOGFILE (TLS 1.2 and 1.3), an RSA private key (--tls-key, TLS 1.2 RSA key exchange only), SRTP keys (the SDES a=crypto keys in the SDP, or a master-keys file with --srtp-keys), and DTLS-SRTP (--dtls-keylog, RFC 5764). Capture SIP over TLS helps you choose
• eBPF TLS capture. This does not break TLS. On a host where you already have root, kernel uprobes read the SIP plaintext inside OpenSSL or wolfSSL before the library encrypts it (--uprobe-tls), so it needs no key, certificate or restart. It is in the released Linux gnu tarballs, .deb and .rpm, not the static musl builds, and needs a kernel with BTF
• SIPREC metadata. Reads the recording metadata (RFC 7866) that a session recording client sends. sipnab is not a recording client or server
• Relay correlation. Ties media on an rtpengine relay (rtpengine) or an rtpproxy relay (--rtpproxy-control) back to its call, and reads rtpengine's own counters over its control port (--rtpengine-control), labeled as the relay's report rather than sipnab's measurement
• vCon export and delivery. Writes each observed call as a vCon, a conversation container (--export-vcon, Export a call as a vCon). --vcon-forward, a separate process, delivers them to a vCon store such as vcon.store or a self-hosted conserver (in the gnu and macOS builds; the static musl builds lack the vcon feature). --vcon-forward-kind vcon-store adds vcon.store's ingest path and header and changes only the copy it sends, because vcon.store's validator rejects the string-array extensions both vCon drafts define (Send sipnab's vCons to vcon.store)
• Export formats. pcap and pcapng, TXT, JSON, NDJSON, CSV, an HTML page of the call flow, Markdown, WAV audio, SIPp XML scenarios and RTP JSON
• pcap in and out. Reads and writes pcap and pcapng, with rotation and splitting; reads directories, tar archives and password-protected ZIP and 7z archives, and stored vCon containers as the SIP messages they hold.
• MCP server. 74 tools over stdio or HTTP: 61 only read, and the 13 that write each say what they change. File writes stay inside --mcp-file-root; swapping the capture, shutting the server down, recording findings and asking TFPS to ban a source stay off until you enable them (--mcp-allow-open-capture, --mcp-allow-shutdown, --mcp-allow-save-findings, --allow-action). MCP server has a first working example

The TUI

• Call list with sortable columns, multi-select, inline search and filters
• Call flow ladder with color-coded arrows, SDP codecs, and PDD
• Four timestamp modes: absolute, delta from the previous message, delta from the first, and scaled to time
• Split view: the raw SIP message beside the ladder, resized with +/-
• Message diff: select two messages with Space to compare them
• Extended flow: merge the legs of one call through a proxy or B2BUA into one ladder (x or F4)
• RTP streams with jitter, loss and MOS (Tab), audio playback, and WAV export (F2)

Keybindings lists every key, per view.

Build from source

sipnab is Rust everywhere except the OS boundary: 111 unsafe blocks, all of them FFI, and the build rejects any block that does not state its own soundness argument.

You need Rust 1.99+ (edition 2024) and the libpcap headers:

• macOS: included with the Xcode Command Line Tools (xcode-select --install)
• Debian/Ubuntu: apt install libpcap-dev
• Fedora/RHEL: dnf install libpcap-devel

cargo build --release

The binary is at target/release/sipnab. Install with cargo installs the published crate instead.

At run time, sipnab loads the system libpcap (libpcap.so.1 on Linux). Only the static musl release binary carries its own. Audio playback in the TUI also needs libasound (ALSA), but loads it only when you press play: playback lives in a separate plugin, libsipnab_audio.so, so a binary built with audio starts fine on a host without libasound, and WAV export still works there.

Feature flags

Flag	What it adds	Default
native	Live and file capture, output writers, the CLI. Needed by every feature below except tls, audio and wasm	yes
tui	The interactive terminal UI	yes
audio	RTP audio playback in the TUI, through the lazily loaded sipnab-audio plugin, and WAV export	yes
metrics	Standalone Prometheus metrics server (--metrics)	yes
tls	TLS and DTLS decryption, SRTP key extraction	no
hep	HEP v3 send, HEP v1/v2/v3 receive	no
api	REST API and its Prometheus endpoint, over HTTP or HTTPS	no
mcp	MCP server, stdio transport	no
mcp-http	MCP server over HTTP (Streamable HTTP). Implies mcp and api	no
plugins	WASM plugin host (--plugin): sandboxed third-party detections	no
vcon	vCon export of one observed call	no
archive	Password-protected ZIP and 7z input	no
bpf	eBPF TLS capture (--uprobe-backend bpf). Needs a nightly toolchain and bpf-linker to build, and a kernel with BTF to run. Outside full	no
wasm	WebAssembly build for in-browser pcap analysis	no
full	native, tui, audio, metrics, tls, hep, api, mcp, mcp-http, plugins, vcon, archive	no

Every feature:

cargo build --release --features full

A headless capture host, with the HEP listener, REST API and MCP over HTTP, and no TUI or audio:

cargo build --release --no-default-features --features native,hep,api,mcp,mcp-http

Installation covers the other builds, cross-compilation included.

Add it to your voice stack

Step-by-step guides that install your SIP server, OpenSIPS, Kamailio, Asterisk or FreeSWITCH, and each piece beside it, then connect sipnab to it. Every command in each guide ran on fresh virtual machines, and each page names them.

• SIP proxy. OpenSIPS and Kamailio carry your calls, and every other guide builds on them: Use OpenSIPS and run sipnab beside it; Use Kamailio and run sipnab beside it.
• PBX. Asterisk answers calls and places them on to the callee, as two legs: Use Asterisk and run sipnab beside it.
• Softswitch. FreeSWITCH answers each call and bridges it to the callee as a second call, with the audio of both passing through it: Use FreeSWITCH and run sipnab beside it.
• Call records. A vCon server keeps every call as a vCon. OpenSIPS records calls into it over SIPREC, and sipnab can send its own vCons, built from what it saw on the wire. sipnab --vcon-forward delivers them, to the server or to vcon.store (in the gnu and macOS builds, which carry the vcon feature): Use a vCon server, run sipnab beside it, send to vcon.store.
• Attack blocking. TFPS stops SIP scanners and fraud in the kernel with XDP, and fail2ban bans them with an nftables rule: Use TFPS and run sipnab beside it; Use fail2ban and run sipnab beside it.
• Media relay. rtpengine or rtpproxy anchors every call's audio, and sipnab matches the media on the relay with the call it belongs to: Use rtpengine and run sipnab beside it; Use rtpproxy and run sipnab beside it.
• Call history. Homer keeps a searchable history of every call your proxy sends it over HEP, and sipnab can join the same feed: Use Homer and run sipnab beside it.
• Metrics. Prometheus and Grafana graph your SIP proxy's statistics, and sipnab adds its own call and media series beside them: Use Prometheus and Grafana and run sipnab beside it.

Where to read next

docs/README.md indexes every page by what you are trying to do. The ones most people need:

When you want to	Read
Find out why calls fail, drop, or carry one-way audio	Troubleshooting
Copy a recipe for a common task	Examples and recipes
Narrow to the calls that matter	Filter DSL
Look up a flag	CLI reference
Write a config file	Config reference, starting from contrib/sipnabrc.example
Parse sipnab's JSON or export pcap	Output formats
Use sipnab as a Rust library	Library API
Understand how it works inside	Architecture and Fault model

Getting help

Ask usage questions in Discussions, and report bugs in Issues. SUPPORT.md explains which is which, and MAINTAINERS.md says who answers and how fast.

Contributing

We welcome contributions. CONTRIBUTING.md covers the build and test workflow, the git hooks, and the pull request checklist. Before we can merge a pull request, you sign the Contributor License Agreement once, and a pull request cannot merge until the license/cla check passes. If your change adds a dependency, read Dependencies first. This project follows the Contributor Covenant Code of Conduct. ROADMAP.md says what we intend to work on over the next year, and what we have decided not to build.

Security

Found a vulnerability? Do not open a public issue. SECURITY.md gives the private reporting address, the response timeline, and what is in scope, such as parser crashes, key-material leaks, privilege-drop and chroot escapes, API and MCP authentication bypass, and command injection through the --alert-exec family.

Support the project

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.

Copyright 2024-2026 Norm Brandinger