Skip to content

Home

Jump to bottom Edit New page
Kaian edited this page Jul 21, 2023 · 32 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 learning 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

if the above does not work, try this:

setcap 'CAP_NET_RAW+eip' /usr/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 beginning. The s of sngrep will stand for SIP.
Why a new tool from network filtering?
Don't know. I couldn't find any console tool that would 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.
I can't see TLS flows even using the private key
sngrep only support a couple insecure cipthers (TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA and TLS_RSA_WITH_AES_256_GCM_SHA384), and needs to capture the initial TLS negotiation in order to decrypt the conversation. If you're using TLS v1.2 or greater with a DH or ECDH cipher, decrypting is impossible as these ciphers implement Perfect Forward Secrecy.
Clone this wiki locally