ESPhishing is a captive portal attack that is executed on the NodeMCU development board with the ESP8266 microcontroller. It is a social engineering tool that generates a WiFi network with a specific name, enticing people to connect to it and enter their credentials.
The source code given in this public repo is for educational use only. Stealing credential might be illegal depending on where you live. I am not liable for any actions on your behalf. This code is given with no warranties and liabilities. Just be responsible
Most of the code is a modification of the project:
- [ESPBug_PIO] - https://github.com/guanicoe/ESPBug_PIO
Which is heavily inspired by different GitHub repositories.
- [ESPBug] - https://github.com/willmendil/ESPBug
- ESPortalV2 - https://github.com/exploitagency/ESPortalV2
- github-ESPortal - https://github.com/exploitagency/github-ESPortal
- esp8266_deauther - https://github.com/spacehuhn/esp8266_deauther
Here are a few screenshots from my phone showing off the web interface, and what each settings do. The fist image is an example of a captive portal seen by the victim. Would you enter you password?
When you connect to the ESPBug, go to any domain name and to the espportal page (e.g. http://espbug.com/espportal)
You should be shown a pop up window asking you for the password. Defaults are Username: espbug and Password: password.
From there you are redirected to the home page.
You want to go to the settings to prepare the hook. Let's go through all the settings to understand what they do.
-
Hat color (choices: Black Hat or White Hat): This gives you the object to be an arse or a crap arse. Basically the White Hat option redirects the victim to a webpage telling them what just happened and how to protect themselves against phishing attacks. The Black Hat immediately disconnects after the victim entered their credentials.
-
Enable portal (choices: ON or OFF): Basically enables the phishing portal.
-
SSID: Set up the SSID of the device. By default it is espbug. When a phishing attack occured, it defaults back to this name so you can connect and see the logs. You can name it what you want to lure victims.
-
Password: This is the WiFi's password. By default it is password, however, you want this blank when you are carrying an attack so victims can connect to the WiFi. Again, when an attack as successfully happened, the password defaults back to password. You can change these defaults in the source code - might add the option to change that in the settings if you ask for it.
-
Channel (choices: 1 to 14): This is the WiFi channel on the 2.4GHz so from 1 to 14.
-
Hidden (choices: YES or NO): This is important! By default, the WiFi is hidden, that means to connect to the espbug you must manually enter the ssid and password. When an attack occurred, the WiFi is hidden again, so you should connect to the device automatically with the same station. However, during an attack you want the WiFi to be visible, so set this to NO.
-
IP: This is the IP of the espbug. By default you can leave the
192.168.1.1. However during an attack you might want to switch to8.8.8.8. This enables the victim's device to automatically show the sign up screen when they connect to the WiFi. -
GateWay: Same as IP, keep these values the same.
-
Subnet: Do not change if you don't know what you're doing.
-
Username: Default is espbug. Put what you want. This is the username to enter when you connect to the webpage. To access the settings etc...
-
Password: Default is password. As the Username. Put what you want here.
-
FTP: STILL UNDER DEV., commented out for the moment
You should be able to download the binary from the release tab in github. https://github.com/willmendil/ESPBug/releases/tag/0.1 and just updload the binary through the arduino IDE. Look below to see how to setup the board.
To get this code running on a nodeMCU like board - such as the one illustrated below - you need to install the Arduino IDE (! I have only tried on Linux, but this should work on any OS - virtual machine included).
Download and install
From there you need a couple installations clicking the upload button. First got File -> Preferences. At the bottom of the window, you should see Additional Boards Manager URLS. Click the little icon at the end at the end of that line. A new window should show up asking you to Enter additional URLS, one for each row. Add:
https://arduino.esp8266.com/stable/package_esp8266com_index.json
and click OK.
Next, in library manager (Sketch -> Include Library -> Manage Libraries) search for
ArduinoJson
From Benoit Blanchon. YOU MUST INSTALL VERSION 5.13.5 not version 6.
nearly there
Now you only need to install the board. Tools -> Board: "<SOME BOARD NAME>" -> Boards Manager. In the search bar, type
esp8266
by ESP8266 Community. I installed version 2.5.52.6.0.
And YOU ARE DONE! Now, you need to open the espbug.ino and setup the correct parameters for the board.
Here are MY setup parameters
Board: "NodeMCU 1.0 (ESP-12E Module)"
Upload Speed: "115200"
CPU Frequency: "160 MHz"
Flash Size: "4M (FS:3MB OTA:~512KB)"
Debug port: "Disabled"
Debug Level: "None"
IwIP Variant: "v2 Lower Memory"
VTables: "Flash"
Exceptions: "Disabled (new can abort)"
Erase Flash: "All Flash Contents"
SSL Support: "All SSL ciphers (most compatible)"
Port : "<USB PORT>"
you can look at this video for quick demo https://youtu.be/1cIXfD_Jz5s
The web pages are saved in a compress form and in bytes. A small script is available to convert you website into the correct format. this runs in Python3. In the web_converter you must add your web pages in web_pages:
\web_converter>tree /F
Folder PATH listing for volume HDD
Volume serial number is 5E0C-E860
D:.
│ requirements.txt
│ webConverter.py
│
├───css_html_js_minify
│ │ [...]
│
└───web_pages
example.html
Then you just need to run the python script knowing that anglerfish must be installed (python -m pip install anglerfish).
\web_converter>PYTHON webConverter.py
webConverter for master
p <PATH TO>\ESPBug\web_converter
parent <PATH TO>
q compressed
arduino_file_path <PATH TO>\ESPBug\web_converter\webfiles.h
datadir <PATH TO>\ESPBug\web_converter\web_pages
dir <PATH TO>\web_interface
datadir <PATH TO>\ESPBug\web_converter\web_pages
compressed <PATH TO>\ESPBug\web_converter\web_pages\compressed
filelist []
html_files [WindowsPath('<PATH TO>ESPBug/web_converter/web_pages/example.html')]
css_files []
js_files []
[+] Minifying example.html...
[+] Compressing example.html...
[+] Saving everything into webfiles.h...
[+] Done, happy uploading :)
Here are the updated functions
server.on(String(F("/example.html")).c_str(), HTTP_GET, [](){
sendProgmem(examplehtml, sizeof(examplehtml), W_HTML);
});
This is the ouput, not very pretty, but functionnal. (I replaced the exact path to <PATH TO> for privacy).
There is the code that must be added to the void startAP() function in servingWebPages.h. The string F("/example.html") is actually the url path that needs to be called to serve the page. You can therefore put anything you want here.
If we look at the tree we see new stuff now
\web_converter>tree /F
Folder PATH listing for volume HDD
Volume serial number is 5E0C-E860
D:.
│ requirements.txt
│ webConverter.py
│ webfiles.h
│
├───css_html_js_minify
│ │ [...]
│
└───web_pages
│ example.html
│
└───compressed
example.html.gz
Specifically a compressed folder was created in web_pages. You actually need to move everything in web_converter\web_pages inside the espbug folder were the espbug.ino resides.
\ESPBug>tree
Folder PATH listing for volume HDD
Volume serial number is 5E0C-E860
D:.
├───espbug
│ └───web_pages <---- [In this folder]
│ ├───compressed |
│ │ └───js |
│ ├───jade |
│ └───json |
└───web_converter |
├───css_html_js_minify |
└───web_pages [MOVE THIS |]
└───compressed
Then you'll need to recompile the project and upload it to the board. I know, it's not elegante, but it works.
Most of the code is strongly inspired by different repo from github, I just wanted to mention them here.
- ESPortalV2 - https://github.com/exploitagency/ESPortalV2
- github-ESPortal - https://github.com/exploitagency/github-ESPortal
- esp8266_deauther - https://github.com/spacehuhn/esp8266_deauther
- and maybe more which I'll add if I remember
- Have FTP Working
- Make more captive portal HTML pages
- In white Hat mode, the explanation page is closed automatically when using
8.8.8.8. Don't know yet how this can be fixed - There might be an issue with the IPs showing from the connected devices, they are all identical and sometimes erroneous.
- Sometimes the only way to see the logs is by downloading the raw file.
GNU GENERAL PUBLIC LICENSE
Free Software, Hell Yeah!