Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
What is sngrep?
sngrep is a terminal tool that groups SIP (Session Initiation Protocol) Messages by Call-Id, and displays them in arrow flows similar to the used in SIP RFCs.
The aim of this tool is to make easier the process of learnig or debugging SIP.
- Capture SIP packets from devices or read from PCAP file
- Supports UDP, TCP and TLS (partially) transports
- Allows filtering using BPF (Berkeley Packet Filter)
- Save captured packets to PCAP file
Building from sources
Download the latest release (or clone the GIT repository)
On most systems the commands to build will be the standard atotools procedure:
./bootstrap.sh ./configure make make install (as root)
The configure process will check for needed dependencies:
- libncurses5 - for UI , windows, panels.
- libpcap - for capturing packets from devices and reading them from PCAP files.
- libssl - (optional) for TLS transport
- libncursesw5 - (optional) for UI, windows, panels (wide-character support)
You can pass following flags to ./configure to enable some features
||Adds OpenSSL support to parse TLS captured messages (req. libssl)|
||Adds GnuTLS support to parse TLS captured messages (req. gnutls)|
||Adds Perl Compatible regular expressions support in regexp fields|
||Adds Ncurses UTF-8/Unicode support (req. libncursesw5)|
||Enable IPv6 packet capture support.|
||Enable EEP packet send/receive support.|
You can find detailed instructions for some distributions.
OSX users can install sngrep using homebrew
brew install sngrep
How to use
Command line arguments
There are some arguments that can be used from the command line to change the default sngrep behaviour
sngrep [-hVcivNqrD] [-IO pcap_dump] [-d dev] [-l limit] [-k keyfile] [-LH capture_url] [<match expression>] [<bpf filter>]
-h --help: This usage
-V --version: Version information
-d --device: Use this capture device instead of default
-I --input: Read captured data from pcap file
-O --output: Write captured data to pcap file
-c --calls: Only display dialogs starting with INVITE
-r --rtp: Capture RTP packets payload
-l --limit: Set capture limit to N dialogs
-i --icase: Make case insensitive
-v --invert: Invert
-N --no-interface: Don't display sngrep interface, just capture
-q --quiet: Don't print captured dialogs in no interface mode
-D --dump-config: Print active configuration settings and exit
-f --config: Read configuration from file
-R --rotate: Rotate calls when capture limit have been reached.
-H --eep-send: Homer sipcapture url (udp:X.X.X.X:XXXX)
-L --eep-listen: Listen for encapsulated packets (udp:X.X.X.X:XXXX)
-k --keyfile: RSA private keyfile to decrypt captured packets
For example, capturing all SIP packets from all devices that has source or destination port 5060
sngrep port 5060
Or displaying SIP packets from eth0 device that has as source or destiny 192.168.0.50 through the 5061 port, saving them to /tmp/sip_capture.pcap
sngrep -d eth0 -O /tmp/sip_capture.pcap host 192.168.0.50 port 5061
Or displaying all SIP packets for a given host in sip_capture.pcap PCAP file
sngrep -I /tmp/sip_capture.pcap host 10.10.1.50
Linux users may add capture permissions to sngrep to avoid run it as root
setcap 'CAP_NET_RAW+eip' /usr/local/bin/sngrep
There are multiple windows to provide different information:
- Call List Window: Allows to select the calls to be displayed
- Call Flow Window: Shows a diagram of source and destiny of messages
- Call Raw Window: Display SIP messages texts (useful for copy messages to clipboard)
- Message Diff Window: Displays diferences between two SIP messages
Here are see some screens of sngrep windows.
Most of the program windows have a help dialog with a brief description and useful keybindings. There are some keybindings that can be use anywhere in the program:
- F1 or h: Show current window help and keybindings.
- ESC or q: Go back to the previous window
- F8 or C: Toggle Message syntax highlight
Frequent Asked Questions
- What does sngrep stands for?
- The first versions of sngrep used ngrep to capture sip packets and parse its output. This changed in 0.1.0 release, where libpcap was used instead. sngrep was designed to be used with the same command line arguments that my co-workers used for ngrep, just adding s at the beggining. The s of sngrep will stand for SIP.
- Why a new tool from network filtering?
- Don't know. I didn't find any console tool that will display call flows.
- Extended Call flow window doesn't work
- If you want to make relations between different dialogs (extended callflow) a header must be present in of the dialogs referencing the other one. This header can be X-CID or X-Call-ID and must contain the Call-ID of the other related dialog.