RIOT/sniffer/tools

RIOT Sniffer Application

About

This sniffer script can be used to monitor and capture network traffic using a RIOT based node. It is primarily designed for sniffing wireless data traffic, but can also well be used for wired network traffic, as long as used network devices support promiscuous mode and output of raw data.

The python script sniffer.py requires a RIOT node running the sniffer app, its source code is located in this repository (see main folder). This node outputs received network traffic via a serial port or a network socket in the common Wireshark/libpcap (pcap) format. This output is then parsed by the sniffer.py script included in this folder run on a host computer.

The sniffer.py script is a modified version of malvira's script for the Redbee Ecotag (https://github.com/malvira/libmc1322x/wiki/wireshark).

Dependencies

The sniffer.py script is written in Python and needs pyserial.

Installing the dependencies:

Debuntu

apt-get install python-serial

PIP

pip install pyserial

Usage

General usage:

1. Flash an applicable RIOT node with the sniffer application (insert path to RIOT source and board name), as follows:

$ git clone https://github.com/RIOT-OS/applications/
$ cd applications/sniffer
$ RIOTBASE=<path/to/RIOT> BOARD=<name> make clean all flash

2. Run the sniffer.py script (change to subfolder tools/) as follows : For serial port:

$ ./sniffer.py serial <tty> <baudrate> <channel> [outfile]

For network socket:

$ ./sniffer.py socket <host> <port> <channel> [outfile]

The script has the following parameters:

• connType: The type of connection to use. Either serial for serial ports or socket for network sockets.
• host: The host if the socket connection type is in use.
• port: The port of the host if the socket connection type is in use.
• tty: The serial port the RIOT board is connected to. Under Linux, this is typically something like /dev/ttyUSB0 or /dev/ttyACM0. Under Windows, this is typically something like COM0 or COM1. This option is used for the serial connection type.
• baudrate: The baudrate the serial port is configured to. The default in RIOT is 115200, though this is defined per board and some boards have some other value defined per default. NOTE: when sniffing networks where the on-air bitrate is > baudrate, it makes sense to increase the baudrate so no data is skipped when sniffing. This option is used for the serial connection type.
• channel: The radio channel to use when sniffing. Possible values vary and depend on the link-layer that is sniffed. This parameter is ignored when sniffing wired networks.
• [outfile]: When this parameter is specified, the sniffer output is saved into this file. See the examples below for alternatives to specifying this parameter. (optional)

Examples

The following examples are made when using the sniffer application together with an iotlab-m3 node that is connected to /dev/ttyUSB1(or COM1) (serial connection type) and runs per default with a baudrate of 500000. For the socket connection type port 20000 is used.

Linux (serial)

Dump packets to a file:

$ ./sniffer.py serial /dev/ttyUSB1 500000 17 > foo.pcap

This .pcap can then be opened in Wireshark.

Alternatively for live captures, you can pipe directly into Wireshark with:

$ ./sniffer.py serial /dev/ttyUSB1 500000 17 | wireshark -k -i -

Windows (serial)

For windows you can use the optional third argument to output to a .pcap:

$ ./sniffer.py serial COM1 500000 17 foo.pcap

IoT-Lab Testbed (socket)

Start an experiment either via the website provided by the IoT-Lab testbed or by using the RIOT specific iotlab Makefile with 3 neighboring iotlab-m3 nodes, where one of them runs the sniffer application and the others run the gnrc_networking application.

Now you can bind the sniffer node to localhost: ssh -L 20000:node-id:20000 user@site.iot-lab.info

Then you can dump or observe the traffic generated by the other nodes running the gnrc_networking application via one of the following commands:

$ ./sniffer.py socket localhost 20000 26 > foo.pcap
$ ./sniffer.py socket localhost 20000 26 | wireshark -k -i -