A WiFi Security Swiss Army Knife

Similar projects worth following
The ESPTool is a convenient Tool to test your WiFi Security against attackers. It can demonstrate how easy it is to crack a WiFi Password or jam your WiFi so you can't access the internet. This Tool is designed for education and self-tests.

Be aware that it is illegal to use this device on Networks other than your own.

Disclaimer: The authors of this repository are not accountable for any action users may perform with this tool

Why automation? - Of course, there are tools for all of the attacks below, but the ESPTool wants to offer a way to automate these processes in a nice and convenient way. The small form-factor allows you to take it everywhere with you and the simple UI makes it convenient and easy to use. Have you ever tried using aircrack? You first need a WiFi chipset that supports monitor mode and then you have to enter long commands with lots of parameters over and over. This is what the ESPTool tries to automate. WiFi Security for the masses.


The Hardware is designed to be a relative generic and reusable Module around the ESP8266 WiFi Plattform. The Schematic is loosley based on the NodeMCU Project, however instead of breaking out all the free pins, all pins are used for a bunch of devices.

The Device has the following Hardware

  • SSD1306 based OLED Display, connected via I2C
  • microSD Card Socket connected over the SPI interface
  • 3 general purpose buttons
  • ESP8266-12E Module
  • TPS63031 Buck-/Boost-Converter with an input range from 1.8V - 5.5V
  • MCP73831 Single-Cell LiPo Charger Chip
  • CP2012 USB to UART converter Chip


The software is of course the part where all the security features are implemented.

It still is under heavy development. A List of planned features are listed here:

  • Layer 1:
    • Since the ESPs Radio is not really configurable it is not possible to create a WiFi Jammer that works by emitting broadband noise or any other Layer 1 attacks
  • Layer 2:
    • Deauthentification attack
    • collecting authentification frames and save the keys to SD card for later decryption (using a wordlist on a computer, the ESP neither has enough memory nor enough processing power to crack them on the system)
    • arp spoofing and session hijacking when connected (needs investigation)
    • evil twin hotspot
  • Layer 3 (after connecting to an AP):
    • Host discovery (IP Scanner)
    • Ping flooding (ICMP Pings)
  • Layer 4 (after connecting to an AP):
    • Port Scan on Host
Incognito Features (TBD):
  • Random MAC-Address on Power Up
  • Random Mac Address while performing critical Tasks

  • rev 0.2 board assembly

    Daniel Grießhaber08/18/2016 at 15:09 1 comment

    The second revision fixes some minor bugs in the hardware. For example the second SPI bus that I wanted to use for the SD card in the other Version is already in use by the on-board flash chip of the ESP12-E module.

    Although no major fixes, rev 2 is the revision that makes all hardware on the board really usable.

    What I wanted to have an eye on in this revision is that none of the components on the bottom layer changes position. this way I can reuse the stainless steel stencil from OSH Stencils. Since the MLP and DSK packaged components are all on the bottom side it makes it way easier for me to assemble the board without having to hand-solder them.

    Here are some pictures from the assembly:

  • ESP8266-12E and the case of the extra pins

    Daniel Grießhaber07/27/2016 at 10:09 0 comments

    On v0.1 of the Boards, I used the extra SPI interface of the ESP8266-12E Modules to still have enough Pins for the Buttons and other I/O. I also used the "User" and "Flash" Buttons in the same way the NodeMCU did and expected them to not be usable in any other way.

    This was the pin mapping of the first version

    As it turns out there are quite a few problems with this.

    Firstly, the extra SPI Interface on the bottom of the symbol that I wanted to use for the microSD card is actually already connected to the external Flash Chip used to store the executable code for the ESP. Secondly, not only are the SPI pins in use, but the bottom pins are all in use, because the Flash is actually connected via an SDIO interface. As it turns out, Pin 10 (that is connected to the "Right" button is actually already used as a clock signal for the SDIO. This means that when the button is pressed, the clock is held low and the ESP gets stuck because it cant fetch anymore data from the flash.

    However, of course the ESP does offer another SPI Interface. This one is mapped to the pins 12-15 in the following manner:


    So I had to reroute all the pins from the micro SD to these pins, which means I lost all other buttons (Left, Up and Down) that were connected on these pins, so the net problem was: how can I gain some more I/O pins from the ESP?

    Well, it turns out that the USER Button that I copied from the NodeMCU schematic is already designed as general purpose input, so I could use it for one function, say Left (I initially thought that the FLASH and USER button were there to switch between flashing and running mode).

    Next there was the flash button. it is connected to GPIO2 and pulls it low when pressed. GPIO2 is also connected via a pull-up to VDD. This is needed during boot. If GPIO2 is high during boot, it enters the normal run-mode and executes the user program, if GPIO2 is held low, it enters flash-mode. This check only happens during boot immediately after power-on. However after the chip booted, this pin can be used as a normal GPIO pin. This means that the FLAH-Button can also be repurposed as a normal button. The same principle is true for GPIO0. It also influences the boot behaviour, but after booting, it can be used as a normal GPIO. This means that there are now 2 more usable GPIO pins and I can connect 3 Buttons in total (GPIO16, GPIO2 and GPIO0).

    In the v0.1 of the board I had 4 Buttons, in v0.2 there are only 3. The only way I can think of adding another Button would be to replace the I2C Display with an SPI one, which would free SCK and SCL (GPIO4 and GPIO5) but would require one new slave select pin. Still, we would end up with one more pin.

    Another way would be to use some diodes and encode the buttons on the 3 available GPIOs as a binary input, which would make it possible to attach (2 ^ 3) - 1 = 7 Buttons in total, however I don't like the fact that pressing multiple buttons then is the same as pressing another button.

    The v0.2 Board are ordered and I test how the interface turns out with 3 Buttons (one button needs to have two functions for enter/back which could be done with long clicks). If the UI is not really usable with only 3 Buttons I can evaluate the two options above.

View all 2 project logs

Enjoy this project?



D4rkC00d3r wrote 02/01/2017 at 00:23 point

Awesome project, is there a link to buying a board?

  Are you sure? yes | no

Mike wrote 11/29/2016 at 19:44 point

I'm really looking forward to test this project of my own. How is it going? Will the code be aavailble soon?

  Are you sure? yes | no

mrjuoji wrote 10/31/2016 at 17:46 point

do you think you could made a version of esptool for this : 

  Are you sure? yes | no

Dimitris Zervas wrote 10/06/2016 at 11:57 point

Is this "stable"? Stable as in: It's sane to order a board from OSHPark.

I don't care about the firmware (I can update it whenever I want)

  Are you sure? yes | no

Bart wrote 08/15/2016 at 10:12 point

The picture with the channel occupation doesn't show channel 14. I know that channel is only (legally) available in Japan, but it is sometimes being used in western Europe, which doesn't surprise me considering how crowded all other channels are.

Can this channel be added to the channel occupation part or is there a hardware limitation?

  Are you sure? yes | no

Daniel Grießhaber wrote 08/16/2016 at 11:21 point

It's not a technical problem. I left it out because there was not enough space on the display :) . I may  cram it back in, but the I need to resize the font

  Are you sure? yes | no

Gordon McLellan wrote 08/09/2016 at 21:33 point

Consider using a small i2c gpio chip for your buttons. Msop-10 could work nicely, sharing the bus with your display.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/16/2016 at 11:25 point

Thanks, but @Radomir Dopieralski had the great idea that I use the GPIOs from the SPI Interface, so I can read them when CS is low. Putting a resistor between the GPIOs and the button will enable the SPI device to still pull the lines high/low

  Are you sure? yes | no

Ted wrote 08/09/2016 at 03:42 point

Will there be code?

  Are you sure? yes | no

Daniel Grießhaber wrote 08/16/2016 at 11:22 point

There definitley will, however I'm not always pushing changes directly to github, I first finish a feature then push all commits for this feature at once.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/16/2016 at 11:22 point

There definitley will, however I'm not always pushing changes directly to github, I first finish a feature then push all commits for this feature at once.

  Are you sure? yes | no

Arsenijs wrote 08/04/2016 at 20:14 point

You shouldn't put any traces under the ESP antenna on the board, you know that? Maybe use a module capable of an external antenna, or re-position the module...

  Are you sure? yes | no

Daniel Grießhaber wrote 08/05/2016 at 09:14 point

Thanks, you really looked closely on the photos :). I noticed my error after I ordered the v0.1 boards because I did not have a keepout-rectangle in the footprint. However, for the v0.2 board I did not change too much about that because I wanted to use the same solder stencil for the bottom side. The reason for v0.2 was to see if the whole electrical side works with the pin-mapping, etc. v0.3 however will be a complete relayout with a keepout zone.

In practice, however, it isn't too much of a deal. Most traces under the ESP carry mostly DC (e.g. the charge indicator LEDs). There's not much high-speed stuff going on (the I2C and SPI lines are routed on the other end of the board). 

I think the only thing that really worsens the antennas performance is that there is quite some area of ground fill under it, which gives a relatively high capacitance of the antenna to ground. 

Now for testing purposes and mostly developing the firmware I'm sitting next to my testing router anyways, so no problem.

  Are you sure? yes | no

Aleksejs Mirnijs wrote 07/30/2016 at 08:58 point

Can it also find multiple hidden SSID's?

  Are you sure? yes | no

Daniel Grießhaber wrote 08/01/2016 at 05:17 point

Thats a great idea! 

As I see it, the ESP's wifi_station_scan does have a show_hidden parameter for active SSID scanning (including hidden networks) which I set when scanning.

However it should be possible to use the promiscuous mode to scan for probing requests with a set SSID. I will look into this as soon as I implement the attacks. (I'm currently in the process to implement all the framework: UI lib, IO libs, Processing model, SW architecture...)

Thanks for the idea. I also wanted to implement an "evil twin hotspot" feature, so I would need to listen to these frames anyhow.

  Are you sure? yes | no

Aleksejs Mirnijs wrote 08/01/2016 at 07:04 point

I'm glad to help with ideas :))

What about not only "random MAC", but also write in needed MAC address?

Channels scanning and (if possible on this modules) channels jaming.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/01/2016 at 09:14 point

jamming is sadly not possible due to the limited control over the rf section. However, scannin on specific channels is possible. do you want to have kind of a bargraph which channels are used by howmany APs? Or what would be your usecase for specific channels?

Entering a MAC with 3 buttons seems as a really annoying, slow process. What would be the benefit? As said I want to implement an evil-twin functionality where you can select the MAC from a list. is this what you mean?

BTW I already have a way to enter text so you can enter the passphrase for a specific Network. It really sucks and is tedious, however needed to be able to connect for the Layer 3+ attacks

  Are you sure? yes | no

Aleksejs Mirnijs wrote 08/01/2016 at 09:44 point

Yes I want to see bargraph which channels are used by howmany APs. 

You can add 5 buttons as joystik (like @K.C. Lee write) but with more buttons. Examlpe: pressing right can select between number/number, letter/letter, number/letter, letter/number; up and down to scroll to correct value. Or select each charter in turn. After selecting correct value and pressing "Enter" can select (right-left) next section/charter to correct.

If you will add full dimension with MAC, I think what it will be wery big amount of data? Or not?

For future you can divide MAC addresses by vendor sections.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/05/2016 at 09:18 point

I implemented the occupation feature right on monday: look at the gallery

  Are you sure? yes | no

K.C. Lee wrote 07/29/2016 at 20:05 point

You can use the ADC pin to read multiple buttons.

Replace the 5V to 3.3V in the picture below.  Multiple buttons can be pressed and detected if R1, R2 and R3 are different values e.g. 2^n multiples such as 1K, 2K, 3.9K  You need to calibrate them or allow for a range of values for tolerances.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/01/2016 at 05:00 point

Thanks, I was aware that one could use an ADC and an R-network to read multiple buttons, however I always thought that it would mean you could not distinguish each button good enough when multiple buttons are pressed. interesting read, thank you for the comment.

I did not yet upload my full schematic, but since the project is battery powered, I already use the one (and only) ADC to measure the battery voltage for an battery indicator. So this method is not an option for me.

BTW: The ADC of the ESP8266 is referenced to 1V, not 3V3. I think this is because otherwise it would not be able to provide a good reference when VDD is below 3V3.

Maybe some modules have a build in divider network, but at least on the 12-E (or 12-F?) modules I use, it is routed directly out to the A0 pin.

  Are you sure? yes | no

r.e.wolff wrote 08/12/2016 at 08:02 point

In theory that low-ish reference voltage is an advantage. 
In theory you take an 1 Ohm resistor R4, and use 10 resistors causing 2^N mA to get 10 buttons! Of course you'd need to drop a few of the low-order buttons to allow for a bit of tolerance on the resistors and the measurement. And of course running 0.5A for button 9 is not an option.... 

  Are you sure? yes | no

Gary wrote 07/29/2016 at 19:56 point

At least in the US, it would be illegal to jam your own wifi signal.

  Are you sure? yes | no

Daniel Grießhaber wrote 08/01/2016 at 04:53 point

oh really? Man, I live in Germany and I think we have kind of the same here. However, I think no plaintiff, no judge?

  Are you sure? yes | no

Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates