Nikolay Shopik edited this page Sep 28, 2016 · 27 revisions

Logo

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.

Features:

  • 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

Installing

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

configure flag Feature
--with-openssl Adds OpenSSL support to parse TLS captured messages (req. libssl)
--with-gnutls Adds GnuTLS support to parse TLS captured messages (req. gnutls)
--with-pcre Adds Perl Compatible regular expressions support in regexp fields
--enable-unicode Adds Ncurses UTF-8/Unicode support (req. libncursesw5)
--enable-ipv6 Enable IPv6 packet capture support.
--enable-eep Enable EEP packet send/receive support.

You can find detailed instructions for some distributions.

Binaries

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

Interface

There are multiple windows to provide different information:

Here are see some screens of sngrep windows.

General Keybindings

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.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.