Eagle Eye: Wi-Fi Monitoring

Reading Time: 5 minutes

When I was a teenager I spent a lot of time setting networks up with my Dad, fixing routers and switches, building antennas out of cardboard,  and playing with Wi-Fi. I remember playing with Wireshark, DD-WRT, and Tomato Firmware, which I though were really cool, but really hard for any average user to understand how to setup and use.

While taking CS284: Mobile Networking, all of these experiences along with my passion for networking, and the burning curiosity to learn Scapy finally converged on EagleEye: The Network Monitoring Tool for Everyone.

* Follow me for more hacking content!


EagleEye is a wireless network monitoring tool aimed at empowering non-technical users; To allow them to troubleshoot, understand, and fix their wireless networks.

Wi-Fi has become widespread in households, businesses, public places, and even airplanes. Everyone has Wi-Fi now a days and no one wants to use cable anymore! In fact, in the U.S alone, 75% of households have Wi-Fi networks!

The problem is that while most people are setting up their Wi-Fi networks, very few of them really understand all the intricacies of Wi-Fi. Now of course, I'm not saying you should need a Computer Science degree to set one up, but not having a general understanding of a network beyond "I plug it in and I'm done" makes it really hard for users to troubleshoot their networks.

So the idea for this project is twofold. First, I aim to give users a monitoring software that keeps it simple and gives you what you need to know without too much nonsense. Second, I seek to teach basic networking knowledge to the user, enabling them to troubleshoot their networks.

Survey: Do people need it?

Before I embark on different projects, I always like to quickly answer an important question: "Why?". For some projects the answer might simply be "Because It will help me learn a new technology". However, for this project I wanted to go a bit deeper and really understand if there is a need for such a tool.

I surveyed 815 users (mostly from UCs and the Reddit community) and found some interesting data, which I'll provide in quick bullet points:

  • 79.4% of users have set up a Wi-Fi network (either at home, work, etc.)
  • Of those users that set wireless networks, 41.1% was unaware that one could change the channel a Wi-Fi router broadcasts on.
  • Of all the users, 69.3% resolved issues by "turning the router On and Off again"
  • Of all the users, 18.0% resolved issues by "Accessing the router's internal website and figuring out what the issue seemed to be".
  • Of all the users, 76.4% of users stated that they would find it useful to have a program that provided "simple graphs and information [...] to troubleshoot their network.

Through these numbers, it was easier to see that people do want (or need) the ability to troubleshoot their networks. Also, it showed me that even simple concepts such as "broadcasting channels" are not quite commonly known by users. (Which is why sometimes you see a ton of people broadcasting on the same channel on small housing complexes.


While the paper I wrote goes into a lot more detail on how EagleEye works, I wanted to give a very quick overview.

From a users perspective, I wanted them to be able to run the program from any linux computer. Essentially all they need to do is run the program and a browser window will open where they are prompted to select their network and input their network's password, and then the browser will start reflecting the data gathered from the active monitoring.

The first challenge was to decrypt the packets that we received through the wireless adapter that was set in "Monitor" mode. Thankfully, I found the C++ library libtins and dot11decrypt which allowed us to decrypt the live packets we were reading and dump them into a new virtual network adapter. These packets are then filtered and analyzed using Python's networking library Scapy. Finally, all of this information would be stored on a Flask server which then gets pulled by the client browser through javascript AJAX calls. Take a look at the figure below, which shows all of this more clearly.

EagleEye: Architecture
EagleEye: Architecture

Figuring out how to store the measurements and other data needed to display the graphs and charts was also a fun challenge. Ultimately, we decided to split the monitoring into time-slots (or windows) of 5 seconds. However, instead of choosing to keep a list of time-slots containing the network information of each client’s activity, we choose a list of ‘Client’ structures. Each client structure contains the basic client information (IP Address, MAC address, OS, etc.) and also a ‘report’ structure. Inside the ‘report’ structure we keep the client’s activity that happened inside a given 5 second time-slot. If a client is not active during a given 5 second time-slot, the information is not saved, thus saving us space.

This structure was specifically chosen because it decreases the amount of redundant or necessary information, so the overall structure is always quite small (e.i. we are only logging information whenever the client is active). However, the trade-off is that the front-end will need to spend more time arranging the data to properly build charts and calculate basic usage information. Nonetheless, the time needed for our front-end to run the necessary calculations is substantially smaller than the time needed for our front-end to retrieve a substantially bigger, yet organized, data-structure. Furthermore, we were interested in taking away as much complexity from the back-end as we did not want to risk loosing packets or introducing other irregularities on the packet capture.

EagleEye: Storing Information
EagleEye: Storing Information

Ultimately, the project ended up being really fun to build. We added all sorts of nifty features and graphs that could help users. We also added http leak protection that would catch and alert you when passwords and usernames that are being sent in clear-text. Accompanying all this work is a comprehensive help section that tries to guide users so they understand the terminology and charts.

EagleEye: User Interface
EagleEye: User Interface

This project is still on the rather early stages of development as I only had a few weeks to program it. However, I built this basic prototype thinking that I was going to expand on it later. I tried to take few shortcuts and allow for a modular architecture that would let me continue coding without accruing too much technical debt. Anybody else that is interested is completely welcome to contribute to the project.

Paper & Git Repo

As always feel free to contact me with any questions, suggestions, or further ideas. I also wanted to do a quick shout-out to Prof. Belding for such an entertaining class.

Git Repo: github.com/pmsosa/EagleEye

Paper can also be found at Academia.edu.

Loader Loading...
EAD Logo Taking too long?

Reload Reload document
| Open Open in new tab

Recent Posts

Recent Comments




  1. Hari
    March 7, 2018

    Great Work..I'm loving your project...I want to ping you personally...Can you forward your mail id and WhatsApp number

  2. Ellen Walters
    December 13, 2018

    I am interested in contributing to the project. Let me know your thoughts on how to join.

    • sosavpm
      December 14, 2018

      Feel free to check out the git project at: https://github.com/pmsosa/EagleEye
      There you can check on the list of issues and TO-DOs. You can modify the program or add to it whatever features you wish and then do a pull request so I can merge your changes to the main tool. Cheers!

Comments are closed.