Suricata IoT
Welcome to the suricata-IoT wiki!
This repository contains extensions to the Suricata IDS/IPS/NSM to support Internet of Things (IoT) protocols, platforms and devices.
Extensions found here currently include support for the following:
This version of Suricata adds decoders for the datalink protocols commonly utilized in wireless IoT networks listed above.
In addition support is being added for these messaging protocols commonly used in IoT networks to communicate between IoT devices and applications typically hosted in the cloud. The implementation of these protocols is still considered a work in progress. Therefore their implementations can be found on their own feature branches in the source code repository and haven't yet been merged into the mainline IoT branches.
The list of additional application layer protocols will likely be expanded over time as dictated by interest and demand.
The code found in this code repository has been tested on these hardware platforms. The code will probably run on similar platforms but hasn't been validated to date.
Instructions for building the code for each of these platforms follows.
Surcata has been built and tested on both the Raspberry Pi 2 and Raspberry Pi 3 boards running the Raspbian OS using the OpenLabs Raspberry Pi 802.15.4 radio.
A picture of the Raspberry Pi with the OpenLabs radio installed can be found here.
The Suricata setup on the Raspberry Pi with the OpenLabs 802.15.4 radio monitors raw 802.15.4 packets delivered to suricata from the network stack. Suricata is able to decode the 802.15.4 packets containing both the ZigBee protocol or alternatively IPv6 carried over the 6LoWPAN encapsulation.
ZigBee carries network packets that generally do not contain IP packets. Suricata has been extended to decode ZigBee packets and track flows between ZigBee endpoints. Suricata's eve-log logging facility will log ZigBee flows in a manner similar to IP flows. The ability to write rules against ZigBee traffic is being developed but has not yet been completed to the point where I'm making it available in this github repository.
6LoWPAN is an adaption layer that enables carrying IPv6 traffic over an 802.15.4 radio network. With the addition of the ability to decode 6LoWPAN traffic all of suricata's IPv6 capabilities become available over a 6LoWPAN packet network.
The Linux kernel delivered with Raspbian does not properly support the OpenLabs 802.15.4 radio with a working network stack. To get things to work requires cross compiling a more up-to-date kernel and installing it on the Raspberry Pi.
Follow the instructions here https://github.com/RIOT-OS/RIOT/wiki/How-to-install-6LoWPAN-Linux-Kernel-on-Raspberry-Pi to build an install the required kernel.
Log into your Raspberry Pi running your newly installed kernel.
Prepare your Raspberry Pi's build environment using:
sudo apt-get -y install libpcre3 libpcre3-dbg libpcre3-dev \
build-essential autoconf automake libtool libpcap-dev libnet1-dev \
libyaml-0-2 libyaml-dev pkg-config zlib1g zlib1g-dev libcap-ng-dev libcap-ng0 \
make libmagic-dev libjansson-dev
sudo apt-get install git-core
Now download the suricata source code from this repository using:
git clone -b feature/IoT-v7 git@github.com:decanio/suricata-IoT.git
Now build the code:
cd suricata-IoT
git clone https://github.com/OISF/libhtp
./autogen.sh
./configure
make
And finally install suricata and along with a full configuration:
sudo make install-full
sudo ldconfig
To prepare the 802.15.4 radio for monitoring perform the following steps:
sudo iwpan phy phy0 set channel 0 11
sudo iwpan dev wpan0 del
sudo iwpan phy phy0 interface add mon0 type monitor
sudo ifconfig mon0 up promisc
Alternatively, I've created a startup.sh script I use to avoid running these commands repeatedly containing the following:
#!/bin/sh
iwpan phy phy0 set channel 0 11
iwpan dev wpan0 del
iwpan phy phy0 interface add mon0 type monitor
ifconfig mon0 up promisc
which can be run with:
sudo ./startup.sh
Now to run suricata capturing packets from the 802.15.4 radio mon0 monitoring interface we created use:
suricata -c suricata/suricata.yaml --pcap=mon0 --runmode=single
Setting up Suricata IoT on the Itron Riva Edge
The Itron RF board is a 900Mhz 802,15.4 radio built to reach longer distances than the 2.4Ghz 802.15.4 radio used on the Raspberry Pi. The Itron Riva's RF radio carries IPv6 traffic over 6LoWPAN.
A picture of a small network of Itron Riva boards can be found here.
At the time of this writing the network stack supporting the Itron RF board delivers IPv6 packets to the packet sniffing interface. Therefore suricata does not have visibility into the operation of the layers beneath IPv6. I'm told that future version of the network stack may provide more visibility.
So therefore suricata running on the Itron Riva Edge will only support its operation at and above the IPv6 layer. A special Itron specific switch has been added to suricata to support this mode of operation.
Running suricata on the Itron Riva uses the stock kernel and runtime environment delivered with the Itron Riva Edge. However, a native code development environment is not supported on the Itron Riva Edge. Therefore cross compiling suricata for the Itron Riva Edge is necessary.
Set up the Itron cross development environment by following the instructions in the Itron Riva Edge SDK Setup Guide.
Before moving onto building suricata its probably worth proving that you can build and run the "Hello Itron Riva" example application described in the SDK Setup Guide.
Building suricata involves downloading and cross compiling several dependent libraries and then finally cross compiling and linking suricata. Finally all of the pieces required to install suricata are copied to the Itron Riva Edge board.
Cross compiling suricata for the Itron Riva was done on a machine running Ubuntu Linux 16.04 LTS.
First create a work directory:
mkdir -p $HOME/work/itronriva
Get a minimal set of dependent libraries using the Ubuntu code repository (note that the Itron Riva runtime environment is similar enough to Ubuntu that these seem to work):
cd $HOME/work/itronriva
apt-get source libjansson-dev
apt-get source libpcap-dev
apt-get source libyaml-dev
apt-get source libpcre3-dev
apt-get source file
Create a build target directory on your cross development host:
mkdir -p $HOME/work/itronriva/target/usr
Build the dependent libraries:
Build libpcap:
cd $HOME/work/itronriva/libpcap-1.7.4
./configure --host=armv7l-timesys-linux-uclibcgnueabi --with-pcap=linux --prefix=$HOME/work/itronriva/target/usr
make
make install
Build libjansson:
cd $HOME/work/itronriva/jansson-2.7
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
Build libyaml:
cd $HOME/work/itronriva/libyaml-0.1.6
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
Build libpcre:
cd $HOME/work/itronriva/pcre3-8.38
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
Build libmagic:
cd $HOME/work/itronriva/file-5.25
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
Note the build and installation of libmagic desribed here doesn't quite work. Therefore libmagic support in this Itron Riva version of suricata has been disabled until this is sorted out.
Now download the suricata source code from this repository using:
cd $HOME/work/itronriva
git clone -b feature/IoT-v7-riva git@github.com:decanio/suricata-IoT.git
Now build the code:
cd suricata-IoT
git clone https://github.com/OISF/libhtp
./autogen.sh
./configure --host=armv7l-timesys-linux-uclibcgnueabi \
--with-libpcre-includes=$HOME/work/itronriva/target/usr/include \
--with-libpcre-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libyaml-includes=$HOME/work/itronriva/target/usr/include \
--with-libyaml-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libpcap-includes=$HOME/work/itronriva/target/usr/include \
--with-libpcap-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libmagic-includes=$HOME/work/itronriva/target/usr/include \
--with-libmagic-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libjansson-includes=$HOME/work/itronriva/target/usr/include \
--with-libjansson-libraries=$HOME/work/itronriva/target/usr/lib \
--prefix=$HOME/work/itronriva/target/usr/local
make
Due to configuring suricata using --prefix=$HOME/work/itronriva/target/usr/local we need to fix up the suricata.yaml configuration file and the suricatasc script so that when we copy the target directory from the host to the target they will reference the directory used on the target.
cd $HOME/work/itronriva/target/usr/local/etc/suricata
echo sSSS$HOME/work/itronriva/targetSSSSSSg >script
sed -i 's/\//\\\//g' script
sed -i 's/SSS/\//g' script
sed -f script -i suricata.yaml
sed -f script -i $HOME/work/itronriva/target/usr/local/bin/suricatasc
rm script
A script to perform the entire build operation is as follows:
#!/bin/sh
mkdir -p $HOME/work/itronriva
cd $HOME/work/itronriva
apt-get source libjansson-dev
apt-get source libpcap-dev
apt-get source libyaml-dev
apt-get source libpcre3-dev
apt-get source file
mkdir -p $HOME/work/itronriva/target/usr
cd $HOME/work/itronriva/libpcap-1.7.4
./configure --host=armv7l-timesys-linux-uclibcgnueabi --with-pcap=linux --prefix=$HOME/work/itronriva/target/usr
make
make install
cd $HOME/work/itronriva/jansson-2.7
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
cd $HOME/work/itronriva/libyaml-0.1.6
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
cd $HOME/work/itronriva/pcre3-8.38
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
cd $HOME/work/itronriva/file-5.25
./configure --host=armv7l-timesys-linux-uclibcgnueabi --prefix=$HOME/work/itronriva/target/usr
make
make install
cd $HOME/work/itronriva
git clone -b feature/IoT-v7-riva git@github.com:decanio/suricata-IoT.git
cd suricata-IoT
git clone https://github.com/OISF/libhtp
./autogen.sh
./configure --host=armv7l-timesys-linux-uclibcgnueabi \
--with-libpcre-includes=$HOME/work/itronriva/target/usr/include \
--with-libpcre-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libyaml-includes=$HOME/work/itronriva/target/usr/include \
--with-libyaml-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libpcap-includes=$HOME/work/itronriva/target/usr/include \
--with-libpcap-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libmagic-includes=$HOME/work/itronriva/target/usr/include \
--with-libmagic-libraries=$HOME/work/itronriva/target/usr/lib \
--with-libjansson-includes=$HOME/work/itronriva/target/usr/include \
--with-libjansson-libraries=$HOME/work/itronriva/target/usr/lib \
--prefix=$HOME/work/itronriva/target/usr/local
make
make install-full
cd $HOME/work/itronriva/target/usr/local/etc/suricata
echo sSSS$HOME/work/itronriva/targetSSSSSSg >script
sed -i 's/\//\\\//g' script
sed -i 's/SSS/\//g' script
sed -f script -i suricata.yaml
sed -f script -i $HOME/work/itronriva/target/usr/local/bin/suricatasc
rm script
Expect these instructions to be enhanced and updated over time.
If you find errors or omissions in these instructions don't hesitate to contact decanio.tom at gmail.com