This is a prototype of the SPIN platform.
What is SPIN?
SPIN stands for Security and Privacy for In-home Networks, it is a traffic visualization tool (and in the future analyzer) intended to help protect the home network with an eye on the Internet of Things devices and the security problems they might bring.
Currently, the SPIN prototype is implemented as a package that can be run on either a Linux system or an OpenWRT-based router; it can show network activity in a graphical interface, and has the option to block traffic on top of existing firewall functionality.
For a screenshot, see here.
Building the source code
The SPIN prototype is meant to be run on an OpenWRT device, but can also be compiled and run on a Linux system.
On (Linux) PC
apt-get install gcc make autoconf libnfnetlink-dev libmnl-dev libnetfilter-queue-dev
apt-get install libnfnetlink0 libmnl0
Lua dependencies (for client tooling and message broker):
lua 5.1 (and luarocks for easy install of libs below)
apt-get install libmosquitto-dev
luarocks install lua-mosquitto luabitop luaposix
- mosquitto (or any MQTT software that supports websockets as well)
Run in the source dir:
autoreconf --install ./configure make
After this step is complete, you can find the spin daemon in the spind directory. The tools/spin_print and tools/spin_config tools are supporting tools for older versions and deprectaed in the latest release.
SPIN sends its data to MQTT, which any MQTT client can then read. A web-based client ('the bubble app') can be found in
src/web_ui/static/spin_api/, the main HTML file is
graph.html, and depending on where you host it, you can access it from a browser with the URL
file://<path>/graph.html?mqtt_host=<ip address of MQTT server>.
src/web_ui also contains a small web API server that uses lua-minithttp, with currently a limited subset of the intended functionality; we are working on RPC calls that will then be exposed to the web API.
If you have a build environment for OpenWRT (see https://wiki.openwrt.org/doc/howto/build), you can add the following feed to the feeds.conf file: src-git sidn https://github.com/SIDN/sidn_openwrt_pkgs
After running scripts/feeds update and scripts/feeds install, you can select the spin package in menuconfig under Network->SIDN->spin.
Running make package/spin/compile and make package/spin install will result in a spin-.ipk file in bin/.
This package has an extra file in addition to the ones described in the previous section: a startup script /etc/init.d/spin; this script will load the kernel module and start the spin_mqtt.lua daemon.
(NOTE: in the current version, the IP address of the router/server is hardcoded to be 192.168.8.1; this is also the address used in this example. We are working on deriving this address automatically, or at the very least make it a configuration option).
When the OpenWRT package is installed, SPIN should start automatically after a reboot. Simply use a browser to go to http://192.168.8.1/www/spin/graph.html to see it in action.
When installed locally, a few manual steps are required:
- Configure and start an MQTT service; this needs to listen to port 1883 (mqtt) and 1884 (websockets protocol).
- Load the relevant kernel modules:
modprobe nf_conntrack_ipv4 nf_conntrack_ipv6 nfnetlink_log nfnetlink_queue
- Enable conntrack accounting:
- Start the spin daemon
spind/spind -l -o -m <mqtt_host>
- Load the spin bubble app by visiting
mqtt host defaults to 127.0.0.1 for the daemon, and to 192.168.8.1 for graph.html
High-level technical overview
The software contains three parts:
- a daemon that aggregates traffic and DNS information (with nf_conntract and nflog) and sends it to MQTT
- a RESTful API (currently only a subset of the intended funcitonality)
The information that is sent to MQTT contains the following types:
- Traffic: information about traffic itself, source address, destination address, ports, and payload sizes
- Blocked: information about traffic that was blocked (by SPIN, not by the general firewall)
- DNS: domain names that have been resolved into IP addresses (so the visualizer can show which domain names were used to initiate traffic)
The daemon will also listen for configuration commands in the MQTT topic SPIN/commands. This will be replaces by RPC calls in the near future.
Data protocols and APIs
For the channels and mqtt message formats, see doc/mqtt_protocol.md
For the Web API description, see doc/web_api.md