README.md

sipnab

sipnab captures and analyzes SIP signaling and the RTP media under it, with security checks on both, in a single binary. It offers an interactive TUI, a scriptable CLI, JSON and report output, a REST API, and an MCP server for AI agents.

This index groups the pages by what you are trying to do, following Diátaxis. The four groups answer four different questions:

If you are	you want	start at
new to sipnab	a guided first run	Tutorials
trying to get something done	steps for your goal	How-to guides
looking something up	exact, complete facts	Reference
trying to understand it	why it works this way	Explanation

Tutorials

Follow these in order on your first day. They assume nothing and show what you should see at each step.

• Install sipnab: the one-line installer, prebuilt binaries, packages, or a source build. Reading a capture file needs no privileges. Live capture needs root or CAP_NET_RAW, which sudo sipnab --setup-caps grants once.
• Triage a capture from the command line: download a sample call, list its calls, find the failed ones, explain one, and pipe the answer into jq.
• Your first analysis in the TUI: open the same capture interactively, read the call-flow ladder, measure a delay, and inspect the audio quality.

The Glossary defines PDD, MOS, B2BUA and the other terms these pages use.

How-to guides

Each answers one "how do I" question and assumes you already know what you want.

Find out what went wrong

• Troubleshooting: symptom to command. Failed calls, one-way audio, high loss, NAT issues: what to run and what to look for.
• Examples & recipes: a recipe per task, each with the command and real output, from triage and filtering to HEP, TLS decryption and audio export, plus one-liners to copy.
• Worked examples from real captures: twelve findings read out of live carrier and PBX traffic, each with the command, the output and what to do next.
• Narrow to the calls that matter: the filter language (method == 'INVITE' and rtp.mos < 3.5) and the diagnostic aliases (--filter codec-asym), with its complete grammar and field list.

Capture what you need

• Tune capture on a busy server: tell whether you are dropping packets, and what to change when you are.
• Read SIP inside a tunnel or tag: whether sipnab can read SIP wrapped in MPLS, PPPoE, GTP-U or VXLAN, and what it says when it cannot.
• Capture SIP over TLS: pick a method by the access you have, whether a key log, the process itself, or eBPF.
• Read SIP over TLS without keys: the uprobe and eBPF backends step by step, what they cost in security, and whether your kernel supports them.
• Attribute media on an rtpengine relay: name the calls behind streams captured on a relay that carries no SIP.

Connect sipnab to other tools

• Connect an AI agent to sipnab: every deployment, from an agent on the same machine to a remote server running sipnab as a service.
• Run MCP across an estate: several SIP servers feeding one capture host, agents outside the network, and one call followed across an SBC, a proxy and a PBX.
• Set up authentication: signed bearer tokens for the API and MCP, with lifetimes, key rotation and revocation.
• Export a call as a vCon: write one observed dialog as a conversation container, and what an observer's record lets a consumer conclude.
• Build a vCon capture stack: OpenSIPS, rtpengine, sipnab and a conserver on one node or two, and the failures that look like success.
• Decode G.729 audio: install the codebook tables sipnab does not ship, on a host with or without internet access.
• Use OpenSIPS as your voice stack's SIP server: install OpenSIPS 4.0 from its packages or build it from source, as a proxy the guides below build on. No sipnab involved.
• Run sipnab beside OpenSIPS: watch a call through OpenSIPS as one call, from both its legs.
• Use Kamailio as your voice stack's SIP server: the same with Kamailio 6.1, alone or beside OpenSIPS. No sipnab involved.
• Run sipnab beside Kamailio: watch a call through Kamailio as one call, from both its legs.
• Use Asterisk as your voice stack's PBX: build Asterisk 22 from source, connect a caller to a callee through it, and operate it. No sipnab involved.
• Run sipnab beside Asterisk: watch a call through Asterisk as its two legs, in the terminal interface, over MCP and REST, and from Asterisk's own HEP.
• Use FreeSWITCH in your voice stack: build FreeSWITCH 1.11.3 from source and bridge a test call through it. No sipnab involved.
• Run sipnab beside FreeSWITCH: watch a call's two legs and its audio through FreeSWITCH, tie the legs together, and receive FreeSWITCH's HEP.
• Add a vCon server to an OpenSIPS voice stack: vcon-server, Valkey and PostgreSQL, with OpenSIPS recording every call into it over SIPREC. Kamailio cannot record this way. No sipnab involved.
• Send sipnab's vCons to a vCon server: a vCon for every finished call, forwarded to vcon-server on the same machine or another, and the way a Kamailio stack gets vCons.
• Send sipnab's vCons to vcon.store: the hosted store, through sipnab --vcon-forward, with what the store's signature and consent fields do and do not mean.
• Add TFPS to your voice stack: block attacking SIP sources in the kernel before they reach your SIP server. No sipnab involved.
• Let sipnab see and control TFPS: what TFPS blocks and why, and ban or unban on request, locally or over SSH.
• Ban SIP scanners with fail2ban: OpenSIPS logs scanners and wrong passwords, and fail2ban bans them with an nftables rule. No sipnab involved.
• Feed fail2ban from sipnab: sipnab's scanner and registration-flood detections, banned by fail2ban.
• Add rtpengine to your voice stack: anchor every call's media on an rtpengine relay, from OpenSIPS or Kamailio. No sipnab involved.
• Let sipnab name rtpengine's media: tie the media on a relay to its call, from the relay's control plane or by asking it.
• Add rtpproxy to your voice stack: anchor every call's media on an rtpproxy relay instead, from OpenSIPS or Kamailio. No sipnab involved.
• Let sipnab name rtpproxy's media: tie the media on an rtpproxy relay to its call, from the relay's control traffic.
• Add Homer to your voice stack: a searchable history of every call, sent by OpenSIPS or Kamailio over HEP. No sipnab involved.
• Connect sipnab to Homer: sipnab as a second HEP receiver beside Homer, or as a source that forwards to it.
• Add Prometheus and Grafana to your voice stack: OpenSIPS's or Kamailio's statistics, stored and graphed. No sipnab involved.
• Add sipnab's metrics to Prometheus: sipnab's call and media series beside the proxy's, with sipnab's dashboard.
• Write a WASM plugin: add your own detection to sipnab's diagnosis without forking it.
• Recolor the TUI: colors and preset palettes.

Reference

Complete and dry. Consult them rather than reading them through.

• Glossary: the terms these pages use, one definition each.
• CLI reference: every flag, grouped, with examples.
• Config reference: every [section] and key.
• Error messages: every message sipnab prints when it refuses a run or stops at startup, what it means, and what to do.
• Keybindings: every TUI key, per view.
• Output formats: JSON and NDJSON schemas, pcapng, jq.
• MOS and codecs: where the quality score comes from, and which codecs report a placeholder.
• SIP header fields: every field in the IANA registry, with the nineteen compact forms.
• SIP request methods: every method in the IANA registry and the dialog state machine it drives.
• SIP response codes: every code in the IANA registry, the RFC section defining it, and whether it means the call failed.
• SIP parameters: every URI parameter, header-field parameter and option tag in the IANA registry, and which sipnab parses.
• SIP conformance rules: run the linter, fail CI on it, fix or suppress each finding, and every rule with the RFC section behind it.
• REST API: every endpoint and its response shape, status codes, authentication, and curl recipes.
• Prometheus metrics: every metric family, whether it is a counter or a gauge, and the scrape config.
• MCP server: what an agent gets from sipnab, and a first working example.
• MCP tool reference: the tool bundles, and every tool by name with a link to its page, which gives its arguments and its response. One page per bundle documents each tool's arguments and response:
  • core bundle
  • signaling bundle
  • captures bundle
  • security bundle
  • media bundle
  • relay bundle
  • tfps bundle
  • server bundle
  • vcon bundle
  • tls bundle
• MCP protocol: the wire contract, security model and error semantics.
• Runnable client examples: Python clients and their regression tests.
• Library API: using sipnab as a Rust crate.

Explanation

Read these when you want to know why, not how.

• Architecture: how a packet becomes a call, a media stream and a finding, and where each answer surface reads them from.
• Fault model: what sipnab does when things go wrong, and what it deliberately does not do.
• Threat model: the security assessment, covering what an attacker wants, where they can reach sipnab, what stops them, and the known gaps.
• Assurance case: the argument that sipnab applies secure design principles and that each of the CWE Top 25 weaknesses is countered, with the ones that are only partly countered named.
• Benchmarks: measure throughput and memory on your own capture, and the reference results with how to reproduce them.

Contributing

Start with the Developer index: a reading order through the domain model, the subsystem walk, the invariants, the test tiers, the change checklists, and the build, CI and release machinery. The narrower pages cover threading, zero-copy payloads and TUI testing.

Supporting the project financially? See Backers & Sponsors.