mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
118 lines
4.3 KiB
Markdown
118 lines
4.3 KiB
Markdown
# RIOT Sniffer Application
|
|
|
|
|
|
## About
|
|
|
|
This sniffer script can be used to sniff network traffic using RIOT based
|
|
nodes. It is primarily designed for sniffing wireless data traffic, but can also
|
|
well be used for wired network traffic, as long as the used network devices
|
|
support promiscuous mode and output of raw data.
|
|
|
|
The sniffer is based on a RIOT node running the [sniffer application](https://github.com/RIOT-OS/applications/tree/master/sniffer) application located in [RIOTs application repository](https://github.com/RIOT-OS/applications).
|
|
This node outputs received network traffic via a serial port or a network socket in the Wireshark
|
|
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 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 from
|
|
(https://github.com/RIOT-OS/applications/tree/master/sniffer)
|
|
|
|
2. Run the `sniffer.py` script
|
|
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 -
|
|
```
|