sipnab

# sipnab [](https://github.com/NormB/sipnab/actions/workflows/ci.yml) [](https://www.bestpractices.dev/projects/13931) [](https://www.bestpractices.dev/projects/13931) [](https://codecov.io/gh/NormB/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](https://sipnab.com/analyze/) reads a pcap in your browser without uploading it. The full documentation lives at **[sipnab.com](https://sipnab.com)** and in [docs/](docs/README.md). The [Glossary](docs/glossary.md) defines the terms these pages use. ## Install On Linux (x86_64 or aarch64) or macOS: ```bash 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](https://sipnab.com/install.sh) 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](docs/install.md#install-with-your-package-manager) | | A static Linux binary with no libpcap dependency (musl) | [Release artifacts](docs/install.md#release-artifacts) | | To prove a download is genuine (checksums, build provenance, SBOM) | [Verify a download is genuine](docs/install.md#verify-a-download-is-genuine) | | To build it yourself | [Build from source](#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: ```bash 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: ```bash 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: ```bash 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`: ```bash 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: ```bash 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](docs/first-cli-triage.md) walks through these commands with their output, and [Your first analysis in the TUI](docs/tui-walkthrough.md) 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: ```bash sudo sipnab --setup-caps ``` Then capture on an interface. Replace `eth0` with yours, which `ip link` lists: ```bash sipnab -d eth0 ``` For a stream of JSON, one SIP message per line, add `-N --json`: ```bash 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](docs/install.md#capture-live-traffic-without-root) explains the privilege model, and [Tune capture on a busy server](docs/tuning-capture.md) 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: ```bash 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): ```bash sipnab -N -L 127.0.0.1:9060 ``` ```bash 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](docs/opensips-sipnab.md), [Run sipnab beside Kamailio](docs/kamailio-sipnab.md) and [Connect sipnab to Homer](docs/homer-sipnab.md) 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: ```bash 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`: ```bash sipnab -N -I sip-problem-call.pcap --api 127.0.0.1:8080 --metrics 127.0.0.1:9100 ``` ```bash 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): ```bash sipnab --mcp -N -I sip-problem-call.pcap --mcp-tools core ``` The server offers 70 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 your own in the config file, landed after release 0.5.196 ([Choosing which tools load](docs/mcp-tools.md#choosing-which-tools-load)). Next: [REST API and metrics](docs/rest-api.md), [Prometheus metrics](docs/prometheus-metrics.md), [MCP server](docs/mcp.md), and [Connect an AI agent to sipnab](docs/mcp-deploy.md). ## 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](docs/auth.md) covers signed tokens, rotation and revocation. - **TLS.** The REST API serves HTTPS itself with `--api-tls-cert` and `--api-tls-key` ([API TLS](docs/rest-api.md#api-tls)); this landed after release 0.5.196, which still refuses the two flags. The metrics endpoint and MCP over HTTP have no TLS of their own: keep them on loopback, or put a TLS-terminating reverse proxy in front. HEP can use TLS in both directions (`--hep-listen-transport tls`, `--hep-send-transport tls`). - **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](docs/threat-model.md) 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](docs/filter-dsl.md) - **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; [where it comes from](docs/mos-and-codecs.md)), 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`) - **HEP v3** send over UDP, TCP or TLS, and HEP 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), SDES SRTP keys (`--srtp-keys`), and DTLS-SRTP (`--dtls-keylog`, [RFC 5764](https://www.rfc-editor.org/rfc/rfc5764)). [Capture SIP over TLS](docs/tls-capture.md) helps you choose - **SIPREC metadata.** Reads the recording metadata ([RFC 7866](https://www.rfc-editor.org/rfc/rfc7866)) that a session recording client sends. sipnab is not a recording client or server - **Relay correlation.** Ties media on an rtpengine relay ([rtpengine](docs/rtpengine.md)) or an rtpproxy relay (`--rtpproxy-control`) back to its call - **vCon export.** Writes one observed call as a vCon, a conversation container ([Export a call as a vCon](docs/vcon.md)) - **pcap in and out.** Reads and writes pcap and pcapng, with rotation and splitting; reads directories, tar archives and password-protected ZIP and 7z - **MCP server.** 70 tools over stdio or HTTP. Out of the box they only read. The tools that save files, swap the capture, query a relay, attach to TLS processes or shut the server down stay off until you enable them. [MCP server](docs/mcp.md) 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](docs/keybindings.md) lists every key, per view. ## Build from source You need **Rust 1.98+** (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` ```bash cargo build --release ``` The binary is at `target/release/sipnab`. [Install with cargo](docs/install.md#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 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: ```bash cargo build --release --features full ``` A headless capture host, with the HEP listener, REST API and MCP over HTTP, and no TUI or audio: ```bash cargo build --release --no-default-features --features native,hep,api,mcp,mcp-http ``` [Installation](docs/install.md#build-it-from-source) covers the other builds, [cross-compilation](docs/install.md#cross-compilation) included. ## Where to read next [docs/README.md](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](docs/troubleshooting.md) | | Copy a recipe for a common task | [Examples and recipes](docs/examples.md) | | Narrow to the calls that matter | [Filter DSL](docs/filter-dsl.md) | | Look up a flag | [CLI reference](docs/cli-reference.md) | | Write a config file | [Config reference](docs/config-reference.md), starting from [contrib/sipnabrc.example](contrib/sipnabrc.example) | | Parse sipnab's JSON or export pcap | [Output formats](docs/output-formats.md) | | Use sipnab as a Rust library | [Library API](docs/library.md) | | Understand how it works inside | [Architecture](docs/architecture.md) and [Fault model](docs/fault-model.md) | ## Getting help Ask usage questions in [Discussions](https://github.com/NormB/sipnab/discussions), and report bugs in [Issues](https://github.com/NormB/sipnab/issues/new/choose). [SUPPORT.md](SUPPORT.md) explains which is which, and [MAINTAINERS.md](MAINTAINERS.md) says who answers and how fast. ## Contributing We welcome contributions. [CONTRIBUTING.md](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](CONTRIBUTING.md#contributor-license-agreement) once, and a pull request cannot merge until the `license/cla` check passes. If your change adds a dependency, read [Dependencies](CONTRIBUTING.md#dependencies) first. This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). [ROADMAP.md](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](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 [](https://www.patreon.com/c/NormB975) [](https://github.com/sponsors/NormB) [](https://cla-assistant.io/NormB/sipnab) ## License Licensed under either of - [Apache License, Version 2.0](LICENSE-APACHE) - [MIT License](LICENSE-MIT) at your option. Copyright 2024-2026 Norm Brandinger