From a53501b1154fef2378a2e60782f4fa9e53f446d4 Mon Sep 17 00:00:00 2001
From: Tux <max@Maxs-MacBook-Air.local>
Date: Sun, 16 Feb 2025 22:41:19 +0100
Subject: [PATCH] readme

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/README.md b/README.md
index 1c20d22..7ad8a3b 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,75 @@
 # Wireless Pwnage Edition
+
+## What does this do and how does it work?
+
+This setup makes use of Hostapd-WPE (Wireless Pwnage Edition) which is a modified
+version of the standard hostapd (Host Access Point Daemon) tool.
+It enables setting up a rogue access point that mimics legitimate Wi-Fi networks,
+tricking clients into connecting and capturing their authentication credentials.
+
+Modern wireless clients (laptops, smartphones, tablets) attempt to maintain
+seamless connectivity by continuously probing for known Wi-Fi networks in their
+saved list. This behavior allows them to automatically connect when a familiar
+network is in range, without user intervention.
+In combination with a tool like Hostapd-WPE this allows to make clients in range
+connect, even if the authentication fails, and to monitor the attempted handshake.
+
+When a device is not connected to Wi-Fi, it will periodically send probe requests
+asking if any of its previously connected networks are available.
+
+Hostapd-WPE can be configured to respond to all probe requests with an "available"
+response, effectively making the client think the requested SSID is in range.
+
+Many clients, depending on their security settings, will automatically attempt
+to connect to the AP, believing it to be the legitimate network.
+
+The captured authentication attempts can then be used for offline password cracking.
+
+As prerequisite the host which is used to run this setup needs two Wi-Fi network
+cards.
+One is used to run Hostapd-WPE and needs to support AP mode.
+The other is used to monitor the connection attempts and recording the authentication
+handshakes, requiring monitor mode.
+The supported modes for a Wi-Fi network card chipset can be checked with the
+command "iw list".
+
+The script "mon" is used to launch the monitoring mode with one of the network
+cards, recording all captured connections in a pcap file which can then be used
+for cracking the credentials.
+
+The script "wpe" launches Hostapd-WPE in karma mode, making use of the client
+behaviour explained above.
+
+## Processing a capture file
+
+When monitoring Wi-Fi connections the resulting captured data is saved to a pcap
+file, numbered by the times the tool was run, so for the first run "wpa-01.cap".
+
+Various tools can be used to process the captured data, also making use of
+various wordlists which, depending on the host system, are available in the
+directory /usr/share/wordlists.
+
+Examples:
+
+aircrack-ng with a simple wordlist:
+
+```sh
+aircrack-ng -w /usr/share/wordlists/wifite.txt wpa-01.cap
+```
+
+Convert the capture for the use with the tool John the Ripper:
+
+```sh
+aircrack-ng wpa-01.cap -J wpa &&
+hccap2john wpa.hccap > wpa.john &&
+john -w=/usr/share/wordlists/john.lst -form=wpapsk wpa.john
+```
+
+Convert the capture for the use with the tool Hashcat:
+
+```sh
+sudo apt -y install hcxtools &&
+hcxpcapngtool -o wpa.hccapx wpa-01.cap &&
+hashcat -m 22000 -a 0 wpa.hccapx \
+/usr/share/wordlists/rockyou.txt.gz
+```