Skip to content

Home

Jump to bottom Edit New page
Kaian edited this page Mar 7, 2015 · 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 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

  • --with-openssl : Adds OpenSSL support, allows sngrep to parse TLS captured messages
  • --enable-unicode : Adds Ncurses wide-character support, for UTF-8 terminals

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 [-hVciv] [-IO pcap_dump] [-d dev] [-l limit] [-k keyfile] [<match expression>] [<bpf filter>]
  • -h or --help: Display help and usage information
  • -V or --version: Display version information
  • -I or --input <filename.pcap>: Read packets from pcap file instead of network devices. This option can be used with bpf filters
  • -O or --output <filename.pcap>: Save all captured packets to a pcap file
  • -d or --device <device>: Live capture from network device (by default, sngrep captures from all devices)
  • -k or --keyfile <keyfile.pem>: Use private keyfile to decrypt TLS captured packets
  • -c or --calls: Only display dialogs starting with an INVITE request
  • -l or --limit: Change default capture limit
  • -i or --icase: Make match expression case insensitive
  • -v or --invert: Invert match expression
  • <match expression>: Match given expression in Messages' payload. If one request message matches the given expression, the following messages within the same dialog will be also captured.
  • <bpf filter>: Filter captured/readed packets using a BPF filter

For example, capturing all SIP packets from all devices that has source or destiny 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

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.
Clone this wiki locally