ESP8266 – WIDS – “Spooky”

Okay this is both #ESP8266 and #Security.

When i first got my hands on the ESP8266 i was curious how much can be done with the chip in terms of security. Knowing that the chip can go ‘monitor’ mode it was clear to me that first thing i’ll code would be the Wireless Intrusion Detection thing running on a 5v low power chip. At that time i ordered something what is called #NODEMCU and the fun started.


The chip itself is capable of running a callback on ever packet it receives with a function:

static void ICACHE_FLASH_ATTR handle_pkt(uint8_t* buf, uint16_t len)

There is actually an official “Sniffer” PDF document by Espressif, google it for more details.

So the way Spooky works is simple. It captures packets within BSSID that is your local home Access Point. When a packet is received, it scans through 802.11 to find the source and destination. If Source or Destination is not listed on the ‘trusted mac’s’ list then it adds this traffic to a list that is then sent out to your Gmail account every hour.

So long story short, Spooky monitors for a non-trusted traffic (that has to be defined by user) and reports it when found via E-Mail, see below for example.

A Spooky generated e-mail notifying of unknown traffic (this is an unknown device authenticating on my AP)



And a simple configuration page with trusted devices added


static void ICACHE_FLASH_ATTR handle_pkt(uint8_t* buf, uint16_t len)

So how is this all programmed?
Firstly all is coded in C with Arduino IDE – it’s just great we can code chips with C. It was my first adventure with chip programming and i was very happy i didn’t have to lear myself some ASM or other script-kiddie language around.

The code itself is very easy, ESP8266 has a file system (SPIFF) so the configuration is loaded/stored directly from that file. I could easily skip writing/reading from EEPROM thanks to this.

All these Web server things are built in and available as ready to use classes so i will not go into details with that.

The Sniffer Callback function has to be very quickly executed or WatchDog will restart the chip, so there is no room and space and time for a lot of work to do. Knowing that i am only doing quick 802.11 inspection to find out RSSI, BSSID, Source, Destination and packet type in accordance to the below 802.11 header


First i find out the packet type by defining them as below:
Zrzut ekranu 2016-08-04 o 10.58.11

Then i filter out all Beacon and Probe request type of frames as they fly around and Spooky will identify them as unknown traffic. So i’m looking only after DATA and MANAGEMENT type frames that are Directed towards user selected Access Point BSSID. This is how i get only the interesting packets out of the chaos around.

Next i read out Source / Destination by looking into ToDS FromDS fields – these are swapped around in regards to the frame type, so be careful how you read them. An example below:

Zrzut ekranu 2016-08-04 o 10.57.11

Then we get the RSSI of the packet, this is easily taken from ESPRESSIF RxControl header within 802.11.

At this moment Spooky knows:
– What is the Packet type
– What BSSID is packet traveling within
– What source is this packet coming from
– What destination is this packet going to

Now having all above and list of trusted MAC addresses, it is easy for Spooky to identify wether a traffic directed within a defined BSSID is trusted or non trusted.
Anything coming from/to a MAC address that is not on the trusted list and having BSSID as defined by user is considered untrusted – and Spooky will email you the details.
All the rest is trusted so Spooky will ignore the traffic.

So the idea of using Spooky is quite simple:
Whenever you get an untrusted traffic notification from Spooky – you either block the MAC address on your Router (if you can’t identify it) or add it to Spooky Trusted MAC’s list (if you know the MAC).

Thanks to this you keep your AP safe and you are notified of unknown events. The word Notified is important because you don’t have to check your AP logs (who does it anyway?)  for intruders and you can respond to events immediately. And yes i know routers can be configured to block untrusted MACs, but i never used that option.

Spooky went into release and some of the users even made a small TicTac version of it.


I expect to make some 3d printed cube for spooky in free time. If you are interested in the code i will be posting it shortly.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s