ik5 / sip-capture

Capture SIP traffic and export over MQTT

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

sip-capture agent

GitHub Workflow Status

What is it and why would I want it?

sip-capture agent acts like an IoT sensor for your SIP call signalling. By deploying it where it can monitor SIP-based network traffic it will capture specific SIP signalling (such as all initial INVITE requests) and forward it as "sensor data" to be consumed by other applications. The resulting data can be used to monitor statistics about your VoIP traffic, stored for call flow debugging, used for billing, or connected to more advanced applications (such as NextCaller's Vericall product) to do real-time detection of call spoofing or analysis of fraud potential.

The surface area for code and configuration of sip-capture is deliberately small so that it can be easily audited and deployed in a secure fashion. One goal is that a single engineer who is proficient in Go should be able to review and understand the behavior of the whole sip-capture codebase in no more than an afternoon.

How does it work?

At it's core, sip-capture is simple: it's a small Go application that uses gopacket/libpcap to listen for SIP signalling, filters to select only the desired messages, and then encapsulates each message in a simple data structure and publishes them to an MQTT topic.

There's a bit to unpack in that statement:

A small Go application

The code base is simple and well documented enough you can audit it and understand it yourself. You should be able to confidently deploy it in your stack, knowing that there are no unanticipated malicious surprises waiting for you. Because it's Go, it can be compiled for nearly any sort of Unix-like system or you can use an existing pre-compiled Docker image.

Use libpcap to capture SIP signaling

sip-capture is a passive SIP sensor, you deploy it where it can see your SIP traffic; possibly directly on your SBC, on the same network switch/VLAN, or by using port mirroring or spanning to deliver a copy of the SIP traffic to the host where the agent is running. It also gives you access to the full BPF filtering capabilities of libpcap to narrow down capture to only specific sorts of network traffic, to ensure you're not capturing unnecessary packets.

Filters to select desired SIP messages

BPF works well for selecting transport-level network packets, but above and beyond that, sip-capture contains a purpose-built filtering language that can further inspect the SIP signaling for specific traits. Select only certain SIP methods, only requests or responses, only certain statuses, or even do full regex selection on message headers or bodies. Messages can also be specifically excluded if they match certain criteria.

Encapsulates each message in a simple data structure

SIP signaling can contain arbitrary data, including non-ASCII and even binary encodings. To be sure it can be transmitted cleanly over any transport, the raw SIP message is wrapped in an JSON encoding structure, including some metadata like the timestamp of capture, a generated message ID for deduplication, and the version of sip-agent used for capture. This makes it easy to transmit and store the data without worrying about corruption or losing fidelity.

Publishes to an MQTT topic

MQTT messaging has become one of the "native" industry standard protocols for IoT type sensors in recent years. You can use standard off the shelf MQTT brokers to receive the SIP signalling data and allow multiple applications to subscribe to the appropriate topic to receive a copy for whatever processing they choose. Many cloud providers also provide MQTT integrations, including AWS IoT and IoT Greengrass, Azure IoT, and Google Cloud IoT. You can integrate your SIP stack with an IoT rule engines to build enhanced call flows.

What sip-capture doesn't (and should not) do

sip-capture is designed for simplicity, auditability, and good old fashioned Unix do one thing well philosophy. As such, there are a lot of things it could do, but does not.

  • It does not alter captured SIP messages in any way.
  • It does not specifically extract any reversible identifiable data from the captured messages; it does inspect the message to apply filter rules to determine if messages should be published or not, and to generate unique message signature hashes as part of the capture metadata.
  • It does not locally persist any data or configuration; it does emit operating logs on standard output, which the host environment may be configured to capture.
  • It does not transmit any SIP data except over the configured MQTT topic
  • It does not change what MQTT topic it publishes to based on any part of the message or operating environment, beyond start up configuration.
  • It does not guarantee delivery, beyond MQTT QoS 1 with a backoff retry.
  • It does not accept any form of configuration or control messages over MQTT, nor any form of device shadow, that could potentially cause it to change any behavior from how it was configured at start up.

sip-capture is meant to be one building block in a larger solution, and all of these capabilities can be provided by other applications, primarily over MQTT, such as being part of an AWS IoT Greengrass group, cloud IoT Core rules engines, or even other local services attached to the same broker. Excluding them from sip-agent helps enable safer deployments on sensitive segments of your network and to keep potentially dangerous capabilities outside that zone.

Because these features can be handled by other applications and would reduce the simple and auditable nature of the code, requests for these capabilities are very likely to be politely declined.

Building and Installing


  • checkout and build with go
  • go get
  • release docker images and nfpm created deb/rpm



See the configuration docs

ezoic increase your site revenue


Capture SIP traffic and export over MQTT

License:MIT License


Language:Go 97.1%Language:Dockerfile 1.6%Language:Makefile 1.2%Language:Shell 0.1%