A Raspberry Pi Network Scanner

We’re going to make use of a Raspberry Pi to build a network scanner to keep track of the hosts connecting to our local network. It’s actually pretty easy to do. And as we’re going to make use of ARP scans to do it, which are moderately stealthy unless you heavily hammer the network, it would be easy to make something that is pretty much invisible to most people.

If you did that, you’d end up with a Pi that could sit quietly in a corner and monitor your home or office wireless network, squirreling away information about what hosts are connecting to without anyone taking much notice of it at all. However, we’re not those sort of people. We’re more the glowing red 6-inch tall seven-segment display sort of people. So instead, our network scanner is going to be plenty visible.

Buying Hardware

Most of the hardware for this project is fairly easy to get a hold of and, apart from the giant seven-segment displays and the controller boards for them, you may well have most (or even all) of the bits and pieces you need kicking around your workshop already.

It can also be put together with minimal soldering. The only soldering needed for the project is attaching the controller boards to the seven-segment displays. These boards use castellated mounting holes, which can be tricky to solder if you’re more used to through hole components. However, don’t worry as it’s not anywhere near as hard as SMD soldering and there are several good guides to help you out.

Optionally Adding a Second Wireless Adaptor

We’re going to be adding a second USB WiFi dongle to our Raspberry Pi since the BCM43438 WiFi chipset on the Raspberry Pi 3 does not currently support monitoring mode.

This second adaptor isn’t necessary for our network scanner, as we’ll be using the onboard WiFi adaptor for the most part, but it’ll give us a lot more flexibility later on if we want to do more in-depth monitoring of our network environment. A USB wireless adaptor is also cheap and readily available, so there isn’t a lot of reasons not to add it unless you’re on a really tight budget.

There are really only two or three chipsets used inside mass market USB wireless adaptors. Unfortunately, you’ll need to be somewhat careful about picking out a wireless adaptor that does support monitoring mode as even seemingly identical adaptors, at least from the outside, may be using completely different chipsets on the inside. However, the adapters are cheap, so if you make a mistake, it’s pretty easy just to buy another. Having another USB wireless dongle in your spares box is always handy.

Some of these chipsets are harder to get working in monitor mode than others. For instance, while the Realtek RTL8188CUS chip can support monitoring, and works out of the box on Raspbian, the default Raspbian drivers don’t support monitoring mode. Getting it working is rather tedious.

You can easily check the chipset of a USB wireless adaptor on most Linux computers by typing

In this case you can see that the USB wireless dongle we are using has a Ralink Technology RT5370 chipset. This supports monitoring out of the box and additionally it has the all-too-unusual ability to support both monitoring and promiscuous modes, so you’re able to see unicast, multicast, and broadcast frames. If you can manage to pick a USB adaptor up using this chipset, you’re in the clear.

Getting an OS for the Raspberry Pi

The first thing we need to do is get the Raspberry Pi set up and ready. Go ahead and download the latest version of Raspbian Lite. Insert an SD card into your Macbook, open up a Terminal window, and type df -h, remember the device name for your SD Card. In my case it’s /dev/disk1. We’ll need to use the raw device, /dev/rdisk1.

Unmount the card

rather than ejecting it by dragging it to the trash. Then in the Terminal window change to the directory with your downloaded disk image and type

if the above command reports error “dd: bs: illegal numeric value”, change bs=1m to bs=1M. The card should automatically remount the image’s boot partition, when dd is done. Since recent releases of the Raspbian operating system have disabled SSH on first boot, and we’re intending to run the board without a monitor or keyboard, we’ll have to enable it again.

Navigate to the boot partition and type the following

The contents of the ssh file don’t matter. When the Pi first boots, it looks for this file; if it finds it, it will enable SSH and then delete the file.

Eject the card with the command

Alternatively, if you don’t want to use dd, I recommend Etcher as a good app to burn SD Card images on the Mac.

Booting the Raspberry Pi

Insert the SD card in the board, plug in your WiFi dongle, and, for now, plug the board into the Ethernet. Then connect the power to start it booting. A red LED will initially come on, however the green ACT LED should start flashing, and the orange FDX and LNK LEDS should light up if the boot works correctly.

After booting, the Raspberry Pi should advertise itself using mDNS, with the default name of raspberrypi.local. The easiest way to find it will therefore be to see if it responds to a ping

If the Raspberry Pi doesn’t respond to a ping request the next easiest thing to do will be to log on to your network router and search for the IP address it was allocated using DHCP.

Configuring the Raspberry Pi

Once you find the Pi, go ahead and login with ssh. The default username and password are pi and raspberry respectively, and go ahead and configure it ready for use. Type

at the prompt to start up the Raspbian configuration utility.

This will open the configuration manager. The first option down is Expand Filesystem, which will automagically expand the size of the root partition. Next scroll down to Advanced Options and change the hostname to something less generic. I went with netscan.

Also under Advanced Options are the toggles to enable SSH, SPI, I2C, and Serial. Go ahead and enable all of these now. While you have the configuration utility open, remember to change the user password to something a bit more secure. Finally, hit Finish, and allow the Raspberry Pi to reboot.

Once you login, you can update the Raspberry Pi to the latest version. Type

to update to the latest bug fixed versions of installed packages. If you’re using an older version of Raspbian you may also want to type

to upgrade to the latest version of the operating system.

About Our Wireless Networking

Essentially we’re going to put the Raspberry Pi’s on-board wireless adaptor (wlan0) into promiscuous mode. This allows us to capture packets on a network to which we’re connected. While we’ll use the external USB wireless adaptor (wlan1) in monitor mode, this captures packets regardless of connected network. No association to an Access Point needed (and no authentication).

Let’s start by checking the current network configuration. At the prompt type

Here you see that loopback network device (lo), the ethernet network (eth0) which we’re currently using to connect to the Pi and its IP address, the on-board Raspberry Pi wireless adaptor (wlan0), and finally our USB WiFi dongle (wlan1). You can see that both wlan0 and wlan1 aren’t configured yet. But we’ll get to that in a minute.

We can take a closer look at the wireless adaptors:

We’ll be configuring the Raspberry Pi’s own wireless adaptor (wlan0) to put the Pi onto our network, while reserving our USB dongle (wlan1) for monitoring. Just to be safe, double check that the USB adaptor is capable of being configured for monitoring:

If you see the mon1 interface appear, everything is working as expected, and for now you can tear down the interface again with

If you don’t, check that the chip set really supports monitoring. Type

Somewhere in the output you should see something a lot like this:

with monitor being listed as a supported interface mode. If that’s not the case, either your chipset just doesn’t support monitoring mode or there is a problem with the kernel driver. There are some cases where the mainline kernel driver for the chip set supports monitoring, whilst the default Raspbian driver does not.

Configuring the Wireless Adaptors

Let’s go ahead and put our Raspberry Pi onto our local network using the internal wireless adaptor. First of all, we need to find our network. Go ahead and type

This will perform a scan for networks. Depending on where you are, you may find only a few. If you’re unsure what sort of encryption your network is using, look for a line that looks like this:

Once you have a network SSID and encryption method, we can go ahead and put our Raspberry Pi onto the network. On the assumption you’re using WPA2, open the /etc/wpa_supplicant/wpa-supplicant file in your editor of choice:

Go to the bottom of the file and add the following:

SSID is the ESSID of your home network, and PASSWORD is the WPA2 password for your network. As a side note, if you want to configure two (or more) wireless networks you can do so by adding an id_str to each like this:

When booted, the Raspberry Pi should associate with either network. Additionally, if both networks are present you can add a priority key, and the network with the highest priority will be used first.

After saving the configuration file, wpa-supplicant should notice a configuration change has been made and, within a few seconds, should try and connect to your (priority) wireless network. Generally however, it doesn’t, and you should type the following:

Wait a few seconds and then:

The interface should have acquired an IP address. Now we need to configure our USB wireless adaptor. Here we’re going to do something slightly different. Go ahead and open the /etc/network/interfaces configuration file in your favourite editor, and change the wlan1 entry to

This should tear down the managed interface and put the wireless adaptor into monitor mode on boot. Once you’ve made these changes, go ahead and reboot your Pi with

Once the Raspberry Pi has rebooted, log back in and check the networking configuration. You should see something a lot like

and checking the devices we should see something like

With wlan0 connected to our home network and wlan1 in monitoring mode, by default, on wireless Channel 1.

While we don’t need to do this right now, we can change the channel, either by specifying the mid-frequency in MHGz, or the channel number. So either

or

will switch our USB wireless adaptor from Channel 1 to Channel 6. Remembering that

will give a list of nearby wireless networks, including detailing the channel those networks are using. This means we’re now all set up. We can connect the Raspberry Pi to a known network (or networks) on wlan0, which can be put into promiscuous mode to monitor traffic. We can also use mon1 interface to monitor traffic on another wireless network (or by scanning between frequencies, multiple networks).

If you ever need to (temporarily) return mon1 to managed mode, you can do so as follows:

We’ve finished configuring our wireless adaptors, so it’s safe to unplug your ethernet cable at this point. You won’t be needing it any more unless you want to access the Raspberry Pi from the wired network.

Monitoring Tools

Kismet is a wireless network detector, sniffer, and intrusion detection system that differs from other wireless network detectors by working passively. In other words, it detects without sending any loggable packets. It is able to detect the presence of both wireless access points and wireless clients, and associate them with each other. It is the most widely used and up to date open source wireless monitoring tool.

To get started, let’s go ahead and download, build, and install kismet.

Once the Raspberry Pi has rebooted, we need to make a couple of quick changes to the kismet configuration file. Go ahead and open /usr/local/etc/kismet.conf in your favourite editor and modify the following two entries as below,

Next we need to download the manufacturer list. This is useful to identify the Wireless Interface Manufacturer of the various networked devices that kismet will encounter.

Now we’ve configured kismet we can start the server component directly from the command line

or by starting it as a daemon

We can then start the kismet_client from the command line

which will bring up the default kismet text client.

Once we’ve verified that the kismer_server is running okay by connecting to it from the client, we can launch it on boot by starting the server from /etc/rc.local on boot.

However before we do that, we need to enable the rc.local service itself, and to do so we need to create an rc-local.service file

the contents of which should look like this:

Save and close the file. Make sure /etc/rc.local file is executable.

and enable the service on system boot:

If all goes well, we can now edit the default /etc/rc.local to start our kismet_server on boot.

Now every time we boot the Pi, the Kismet server will be started in the background. Note the use of the ‘-n’ command line option to suppress logging so we don’t fill up our SD Card with logging information.

You can access the server locally on the Pi just by running kismet_client as normal. Or over the network at netscan.local:2501.

Scanning Tools

Now we’ve got some basic monitoring in place, or possibly some fancier hacks, let’s get to the meat of our network scanner project, and install some tools to find and count the devices attached to our home or office network. The first thing we need to install is nmap., and then arp-scan.

While you might be familiar with nmap, you may not be so familiar with arp-scan. It’s a very fast ARP packet scanner that will show every active device on your local subnet.

The interesting thing about this type of tool is, even if a device doesn’t respond to network requests and is designed to be silent, it should be visible to an ARP scan. The downside is, since ARP is non-routable, this type of scanner only works on the local network segment. If you have a complicated network, with multiple routers, it’s unlikely to catch all the hosts on the network.

Running arp-scan on my local network gives a result that looks something like this:

You can get a slightly more helpful version of the same scan by replacing the mac-vendor.txt file in /usr/share/arp-scan with a more comprehensive version. Now, as it happens, Wireshark comes with a  rather good list of NIC vendor codes. Unfortunately, the format of the file isn’t compatible with arp-scan, at least not out of the box. However, after massaging the file with half a dozen regular expressions, you can massage the data into something that arp-scan will accept.Fortunately for you, I’ve done the heavy lifting for you and posted it as a Gist.

You can therefore go ahead and update the mac-vendor.txt file as follows:

Now the same network scan produces something a bit more interesting:

Counting Devices

Since we know that arp-scan is relatively quick, generally it’ll return a result in a much shorter time than nmap. It’s also pretty reliable about finding devices on the network, so we can use it to keep a running count of the number of devices (and which devices) are using our network throughout the day.

The easiest way to do this is to use arp-scan to count the devices periodically throughout the day and log the number to a database. Then we can both report the current number, and also do some later analysis on the data. I’ve put together a quick Perl script to do this, but we will need to install a few tools first before we can use it. So go ahead and install the following packages:

and then grab the Perl script from Github and save it onto your Raspberry Pi.

The script will perform an ARP scan of the local network on wlan0, and save the results into a SQLite database. The default name for the database is network.db, but this can be modified by passing a database name on the command line with the argument “–network NAME”, where NAME is the name of the database file to which the script will automatically append a ‘.db’ ending.

Optionally the script will look to see if the device offers an mDNS associated forward address. You can enable this by passing the command line argument “–dig”. However this will severely impact the performance of the script and make it slow down a lot. However, since we’re serializing the results into an SQLite database, you only really need to run this script every so often to populate the forward addresses for hosts.

The database consists of four tables. The first table, named scan, records the time and hosts present for each ARP scan.

The next, named macs, records the number of times each unique MAC address has appeared in an ARP scan, along with the vendor name of the NIC if known.

The third table, named days, records the number hosts present for each scan on an individual day, as well as a calculated ‘average number of devices connected’ to the network for that day.

The final table, named mdns, is optionally created when the script is executed with the –dig command line argument. This table stores the mapping between MAC address and mDNS forward address if the device advertises one.

We can now run this script from crontab regularly, perhaps every half hour or so, and also once or twice a day with the optional (and much slower) “–dig” command line argument to populate the “mdns” table which maps the device’s MAC address to mDNS forward address.

But before we do that, let’s test it out and run the script from the command line

Or, if you’ve got the patience, you can also look up mDNS forward addresses for the hosts:

This will create a database called “home.db”. After running the script a few times, go ahead and take a look at the database in your favourite database inspector application.

You’ll notice that the total number of hosts visible does vary a bit, as sometimes the ARP scan misses a host or two, or more. You can make the script more reliable by upping the retries “–retry=8” to a higher number. However, the higher this number, the slower the ARP scan.

Adding to Crontab

Now we have everything working, let’s go ahead and add our crontab file to the script. We’ll set it up to run ‘regular’ scans, once every half an hour.

We need to run our script as root so

and then modify the root user crontab file so it looks like this

If you wanted you could also add a second entry to run an ‘enhanced’ scan every so often with ‘–dig’ enabled to attempt to figure out what the mDNS forward address is for each of the discovered hosts. If you haven’t had much experience with crontab before and want to experiment with that, there’s a good introductory how to on the Raspberry Pi site.

Starting Up

We can also make sure the database is updated every time the Raspberry Pi is rebooted by adding our script to the /etc/rc.local file:

Building the Giant Display

So far there hasn’t been a lot of hardware hacking. That’s about to change. With our Perl script running every half hour we now have a running count of how many devices there are on the network

The only soldering needed for the entire project is attaching the driver boards to the back of the giant seven-segment display boards. Fortunately Sparkfun have provided a really in-depth hookup guide to walk you through the process, as well as some excellent advice on how to solder castellated mounting holes if you’re not that familiar with doing so.

Go ahead follow the Sparkfun instructions and attach driver backpacks to the two seven segment displays. The grab your Arduino Uno and wire the two panels up.

While your Arduino is connected to your laptop via USB cable, you can’t power the displays from that, that’s what our 12V power supply is for. So remember to plug that into the barrel connector of the board. At which point you should have both a USB cable (to your laptop) and a power cable coming out of the Arduino.

There’s some excellent example code as part of the Sparkfun hookup guide. So once everything is wired together load it onto the Arduino so we can test out your soldering.

There are two connectors on the Large Digit Driver. ‘IN’ is the input side that should be connected to your microcontroller (the Arduino). ‘OUT’ is the output side that should be connected to the ‘IN’ of additional digits. Each display will use about 150mA with all segments and decimal point on.

Programming the Arduino

Now everything is working stand alone, we can take Nathan’s example code and modify it so that the Arduino accepts a number on the serial port and then displays it using the two linked seven-segment displays. We can then attach the Arduino to our Raspberry Pi, and modify our original scan script to push the current number of devices to the serial port.

You can grab a copy of the modified Arduino sketch from Github. Looking at the code you’ll notice that I’ve stored the last number passed to the code in EEPROM, this means that when we open and close the serial connection from our Raspberry Pi, the display won’t blank out when the Arduino board is reset as the serial connection is opened by our Perl script.

Upload the modified sketch to the board and open up the Arduino Serial Console, make sure the console is set to 9, 600 baud and type a number in and send it to the board. If all goes well the number on the giant seven-segment displays should change.

Connecting the Arduino to the Raspberry Pi

It’s time to put everything together. Unplug the Arduino board’s USB cable from your laptop and plug it into your Raspberry Pi. If all goes well it should show up as a serial device as soon as it’s plugged in,

you can see here that it’s shown up on my Pi as /dev/ttyUSB0.

Go ahead and install the following package:

and then grab the updated Perl script from Github and save it onto your Raspberry Pi, replacing the previous counter.pl script. Change the /dev/ttyUSB0 to reflect your own set up.

This script looks a lot like our original counter.pl script. However, it uses the serial library to connect to our Arduino and sends the current count of devices to the display. Go ahead and run the script as before.

And we’re done. You now have a configured, working, and (very) visible network counter.

Going Further

There’s plenty of scope to take this project further, both to increase the amount of information that the scanner is logging and also to add another display or two.

For instance, the folks over at ETH Entrepreneur Club in Zürich have set up a Raspberry Pi to capture wireless packets and count them. They then map the traffic, on a scale from 0 to 10, and display it on a rainbow-colored LED bar graph as an easy way to know how heavily loaded the network is right now. So perhaps a giant LED bar graph to display the amount of TCP traffic monitored on the mon1 interface?

Another alternative could be an emergency “stop the network“ button if you see something odd happening? So many possibilities, so little time.