# 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](https://github.com/malvira/libmc1322x/blob/master/tools/rftestrx2pcap.py)
for the Redbee Ecotag (https://github.com/malvira/libmc1322x/wiki/wireshark).

## Dependencies

The `sniffer.py` script is written in Python and needs [pyserial](https://pypi.python.org/pypi/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
$ BOARD=<name> make clean all flash
```

2.  Run the `sniffer.py` script (change to subfolder `tools/`) as follows :
    For serial port:
```
$ ./sniffer.py [-b baudrate] <tty> <channel> [outfile]
```
For network socket:
```
$ ./sniffer.py <host>:<port> <channel> [outfile]
```

You should see output like below:
```
ifconfig 3 set chan 26
ifconfig 3 raw
ifconfig 3 promisc
RX: 0
```

For detailed information on the parameters use the scripts on-line help:

```
./sniffer.py -h
```

### 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 -b 500000 /dev/ttyUSB1 17 foo.pcap
```

This .pcap can then be opened in Wireshark.

Alternatively for live captures, you can pipe directly into Wireshark with:
```
$ ./sniffer.py -b 500000 /dev/ttyUSB1 17 | wireshark -k -i -
```

#### Windows (serial)

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

```
$ ./sniffer.py -b 500000 COM1 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 localhost:20000 26 foo.pcap
$ ./sniffer.py localhost:20000 26 | wireshark -k -i -
```