sipnab

SIP & RTP capture, analysis, and security tool.

One static binary that reads a whole estate. Kamailio, OpenSIPS and
Asterisk already speak HEP, so they mirror their signaling to a single sipnab
listener and that one process answers for every node — nothing goes on the
production hosts, and there is no collector, no database and no web UI to
operate.

On one box it still does what you expect. sipnab honors every
sngrep keybinding and accepts the
sipgrep flags, in one Rust binary that
adds first-class RTP quality monitoring, VoIP diagnostic aliases, security
analysis, and an MCP server an AI agent can drive.

Features

• Four output modes -- interactive TUI, non-interactive CLI, JSON, MCP server (drive sipnab from an AI agent)
• SIP header matching -- From, To, Contact, User-Agent, filter DSL
• RTP quality monitoring -- jitter, loss, MOS scoring, one-way audio detection
• Per-call asymmetry signals -- codec, ptime, payload-type, duration, late-media (Phase 8.7)
• Diagnostic aliases -- --problems, --slow-setup, --short-calls, --one-way, --nat-issues as flags; codec-asym, ptime-asym, payload-asym, duration-asym, late-media via --filter (e.g. sipnab -N -I capture.pcap --filter codec-asym)
• Security analysis -- scanner detection, registration flood, digest leak, STIR/SHAKEN, fraud heuristics
• Event execution -- run commands on dialog state changes or quality drops
• HEP v3 -- send/receive Homer Encapsulation Protocol
• TLS/SRTP decryption -- SSLKEYLOGFILE (TLS 1.2/1.3), RSA private key (--tls-key, TLS 1.2 RSA-kx only — not ECDHE/PFS), SRTP media (--srtp-keys + SDES a=crypto, AES-CM), and DTLS-SRTP key extraction (--dtls-keylog, RFC 5764)
• Privilege separation -- drop to unprivileged user after capture device open
• pcap I/O -- read/write pcap and pcapng, file rotation and splitting
• MCP server mode -- expose analysis (dialogs, streams, RTP, security findings) as 38 Model Context Protocol tools an AI agent can call. No tool edits the analysis in place; file export, capture swapping and shutdown stay off unless you enable them. Stdio + HTTP transports. See docs/mcp.md.

Prerequisites

Build dependencies

• Rust 1.97+ (edition 2024)
• libpcap headers
  • macOS: included with Xcode Command Line Tools (xcode-select --install)
  • Debian/Ubuntu: apt install libpcap-dev
  • Fedora/RHEL: dnf install libpcap-devel

Runtime dependencies

sipnab dynamically links to system libraries. These must be present on the
target system:

tls, hep, api, mcp, mcp-http, vcon, and wasm are pure-Rust and
need no additional system libraries.

The audio feature no longer links libasound into the sipnab binary.
Device output lives in a separate plugin, libsipnab_audio.so
(/usr/lib/sipnab/ from the .deb, or next to the binary in dev builds),
which sipnab dlopens only the moment you press play. So an audio-enabled
binary starts fine on a host without libasound. If libasound (or the plugin)
is missing, playback returns a clear error and WAV export (F2) still works.
Install libasound2 for live playback — it is a Debian Recommends, not a
hard dependency. For headless servers, each release also ships a -noaudio
.deb with no plugin and no ALSA Recommends at all (see
docs/install.md).

Build

cargo build --release

The binary is at target/release/sipnab. Live capture requires root or
CAP_NET_RAW (Linux) / BPF access (macOS).

Cross-compilation

You can produce pre-built binaries for x86_64 and aarch64 Linux from macOS using
cross:

Build for x86_64 Linux. The result is dynamically linked, so the target host
needs libpcap present:

cross build --release --target x86_64-unknown-linux-gnu

Build for aarch64 Linux:

cross build --release --target aarch64-unknown-linux-gnu

Cross-compilation requires Docker (via Colima,
Docker Desktop, or similar) and cross (cargo install cross).

Quick start

The default mode is the TUI -- an interactive call list. It puts the terminal in
raw mode, so anything pasted after it arrives as keystrokes rather than as a
second command (i clears non-matching dialogs, q quits). Run it on its own:

sudo sipnab -d eth0

CLI mode instead of the TUI, filtering on the From header:

sudo sipnab -N -d eth0 --from 1001

Diagnose a specific call from a pcap. --no-cli-print keeps the whole capture's
message dump out of the way, so the report is all you get:

sipnab -N -I capture.pcap --call-report <call-id> --no-cli-print

Show only the calls sipnab considers problematic:

sudo sipnab -N -d eth0 --problems

Emit JSON and pipe it to jq:

sudo sipnab -N -d eth0 --json | jq .

Detect SIP scanners and report them to syslog:

sudo sipnab -N -d eth0 --kill-scanner --alert syslog

TUI

The default interactive mode is a full terminal interface for reading SIP and
RTP as they happen:

• Call list with sortable columns, multi-select, inline search, filter DSL
• Call flow ladder with color-coded arrows, SDP codec display, PDD annotation
• Four timestamp modes -- absolute (HH:MM:SS.mmm), delta from previous
  message (color-coded by latency), delta from first message, and scaled, which
  stretches the ladder with time-proportional spacer rows
• Split view -- raw SIP detail panel alongside the ladder diagram, resizable
  with 9/0 or +/-
• Message diff -- select two messages with Space to compare side-by-side
• Extended flow -- merge correlated dialog legs into a single ladder (F4/x)
• RTP stream list -- jitter, loss, MOS scores (Tab to switch)

sipnab honors every sngrep keybinding. Press F1 for the full shortcut reference.

Feature flags

Build with specific features. Adding TLS decryption and HEP to the default set:

cargo build --release --features tls,hep

Everything the crate can do:

cargo build --release --features full

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

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

Note: audio is in the default feature set, but it does not add a load-time libasound2 dependency to the sipnab binary. The rodio/ALSA code lives in the separate sipnab-audio cdylib plugin (libsipnab_audio.so), which the binary dlopens lazily only when you actually play a stream. So the binary starts fine without libasound. Install libasound2 only if you want live playback (otherwise WAV export still works). For a fully audio-free build, drop audio (e.g. --no-default-features --features native,tui or the headless recipe above) and the plugin is simply not built.

Documentation

docs/README.md is the full index, grouped by what you are
trying to do. The pages worth knowing by name:

Arrived with a problem

• Troubleshooting -- symptom to command. Calls that
  fail, drop after a round number of minutes, ring for ages, or carry audio one
  way only: what to run, and what the output means
• Cookbook -- copy-paste recipes for common workflows
• Filter DSL -- narrow to what matters
  (rtp.mos < 3.5 and one_way == true), plus the diagnostic aliases

Looking something up

• Installation -- binaries, packages, capabilities for live capture
• CLI Reference -- all flags, organized by group
• Config Reference -- TOML config file format
  (starter file: contrib/sipnabrc.example)
• Output Formats -- NDJSON schema, jq recipes, pcap export
• Keybindings -- TUI keyboard shortcuts
• MOS and codecs -- where the quality score comes
  from, and which codecs report a placeholder instead
• REST API & Metrics -- endpoints, response shapes, Prometheus
• MCP Server -- tools, transports, token bootstrap, systemd unit, troubleshooting
• Library API -- using sipnab as a Rust crate; typed ParseError/CaptureError

Understanding it

• Architecture -- module map, data flow, threading model
• Fault model -- what sipnab does when things go wrong
• Implementation Plan -- historical design decisions and roadmap

Getting help

Usage questions belong in
Discussions. Bug reports belong in
Issues.
SUPPORT.md covers which is which, and
MAINTAINERS.md is honest about who answers and how fast.

Contributing

Contributions are welcome -- see CONTRIBUTING.md for the
build/test workflow and pull request checklist. This project follows the
Contributor Covenant Code of Conduct.

Security

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

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.

Copyright 2024-2026 Norm Brandinger