ESPTool

Description

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.

Details

Hardware

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

Software

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

Project Logs

Collapse

rev 0.2 board assembly
Daniel Grießhaber • 08/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ßhaber • 07/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:
pin function
12 MISO
13 MOSI
14 SCK
15 CS
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

Discussions

Andreas Reischle wrote 06/22/2017 at 15:03

I briefly worked on capturing the 4-way handshake, but gave up, as I could only get the first 112 bytes of the packets in promiscuous mode. You mention that as one of the planned features. Have you found a way around that limitation?

I'll have a try with the ESP32 next. Espressif claimed "full packet receive" in their current SDK release notes.

Are you sure? yes | no

aceofjokers wrote 06/06/2017 at 07:57

Looks like an awesome tool!!!

might be worth a thought - 5ghz....the ESP8266 only supports 2.4ghz

Are you sure? yes | no

crushedice2000 wrote 03/14/2017 at 10:18

What about WPS? Would be easy to implement WPS brute forcing and/or calculation of default PIN?

Are you sure? yes | no

Daniel Grießhaber wrote 03/14/2017 at 20:12

I'm not completely sure, but I think the processing power and memory of the ESP is not sufficient for such an attack

Are you sure? yes | no

crushedice2000 wrote 03/14/2017 at 20:32

I searched on Google and the only method that seems supported by the ESP8266 SDK is WPS PBC (with button). Seems like the most vulnerable method (WPS PIN) is not implemented yet. What a pity.

Are you sure? yes | no

D4rkC00d3r wrote 02/01/2017 at 00:23

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

Are you sure? yes | no

Daniel Grießhaber wrote 03/14/2017 at 20:14

You can always order the bare board from OSHPark and create a BOM from the Eagle files https://oshpark.com/shared_projects/IPe5DGPV

Are you sure? yes | no

Mike wrote 11/29/2016 at 19:44

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

Daniel Grießhaber wrote 03/14/2017 at 20:16

The Code in its current state is already available on github (https://github.com/dangrie158/ESPTool), however I wasn't able to develop all features yet since I'm working on my masters thesis

Are you sure? yes | no

mrjuoji wrote 10/31/2016 at 17:46

do you think you could made a version of esptool for this :https://goo.gl/HzFtGT

Are you sure? yes | no

Daniel Grießhaber wrote 03/14/2017 at 20:19

Hi, should be really easy to do. Just add some buttons. Since the i2c pins for the display are "fixed" this should work with out (or only minor) adjustments to the firmware.

Have a look at the pin definitions in the main.cpp (https://github.com/dangrie158/ESPTool/blob/develop/Firmware/src/main.cpp)

Are you sure? yes | no

Marco Pfeffer wrote 06/22/2017 at 14:00

This is what I thought as well. Since I already have wemos ESP8266 with 1.3 OLED from aliexpress. I will try finding a convinient way to add Buttons. Thanks Daniel for providing the code.

Are you sure? yes | no

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

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

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

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

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

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

Will there be code?

Are you sure? yes | no

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

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

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

Arya wrote 08/04/2016 at 20:14

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

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 wrote 07/30/2016 at 08:58

Can it also find multiple hidden SSID's?

Are you sure? yes | no

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

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 wrote 08/01/2016 at 07:04

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

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 wrote 08/01/2016 at 09:44

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

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

You can use the ADC pin to read multiple buttons. http://letsmakerobots.com/node/33397

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

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

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

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

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

ESPTool

Description

Details

Hardware

Software

Project Logs

Collapse

rev 0.2 board assembly

ESP8266-12E and the case of the extra pins

Discussions

Similar Projects

SUPEROLED8

ESP8266 SDK Tutorials

ESP8266 Lua Tutorials

Adventures with ESP8266-12E, NodeMCU, and Lua

pin	function
12	MISO
13	MOSI
14	SCK
15	CS

ESPTool

Become a Hackaday.io member

Just one more thing

Description

Details

Hardware

Software

Project Logs Collapse

Enjoy this project?

Discussions

Become a Hackaday.io Member

Similar Projects

Does this project spark your interest?

Report project as inappropriate

Send message

Remove Member

Project Logs

Collapse