gowifi

An evil Wi-Fi framework, written as a single self-contained Pure Go binary for a Raspberry Pi 4 with multiple Atheros Wi-Fi chipsets.

It creates an evil-twin access point, serves a templateable captive portal to capture credentials, replays them on a second adapter to join the real network, and observes HTTP, DNS and unencrypted SMTP/IMAP traffic.

How it works

1. Recon — scans for the target network via nmcli.
2. Evil twin — creates an AP-mode hotspot with the target ESSID/channel.
3. Captive portal — runs a pure-Go DHCP server and DNS hijacker plus an html/template login page; victims are redirected to it.
4. Interception — a transparent HTTP proxy logs requests, and transparent SMTP/IMAP relays decode plaintext credentials.
5. Deauth — (optional) forces clients off the real AP using injected 802.11 deauthentication frames.
6. Bridge — on a successful login, the captured credentials are used to connect to the real network on the uplink adapter and NAT the evil twin onto the internet.

Build

make build            # native binary
make build-arm64      # cross-compiled static binary for the Pi
make build-portal-generic  # bundle only the generic portal

Portal themes are separate packages and are go:embeded at build time. Build tags control which are bundled (exclude with -tags no_fortinet,no_cisco).

Usage

gowifi has four modes. The physical twin and the cracking machine exchange data through a single campaign folder.

gowifi scan      # capture handshakes + campaign data (monitor mode)
gowifi prepare   # crack captured handshakes (wordlist and/or brute force)
gowifi deploy    # run the full attack for a campaign folder
gowifi check     # verify dependencies and hardware

Campaign workflow

# 1. On the physical evil twin: capture auth packets / handshakes.
sudo gowifi scan -ssid "CORP_WIFI" -bssid "aa:bb:cc:dd:ee:ff" \
  -monitor wlan2 -campaign ./gowifi-campaign

# Optionally serve the dataset over a hidden SSID to download it:
sudo gowifi scan ... -transfer -ap wlan0 -transfer-ssid gowifi-data

# 2. On the big CPU machine: crack.
gowifi prepare -campaign ./gowifi-campaign -wordlist words.txt
gowifi prepare -campaign ./gowifi-campaign -charset abcdef0123456789 -minlen 8 -maxlen 10 -workers 16

# 3. Back on the physical twin: deploy (reads $PWD/gowifi-campaign automatically).
sudo gowifi deploy

The campaign folder is self-contained and timestamped for reproducible ISO audits:

gowifi-campaign/
├── campaign.json       # target SSID/BSSID, clients (MAC + probed SSIDs), handshakes, cracked
├── deploy.json         # deployment settings (read by "gowifi deploy")
├── bruteforce.json     # brute-force checkpoint (paused/resumed across machines)
├── packets.pcap        # raw radiotap frames (hashcat/aircrack compatible)
├── handshakes/*.json   # ANonce/SNonce/MIC/EAPOL per captured handshake
└── credentials/
    └── <hostname>.json # credentials intercepted from that victim, each with
                        # timestamp, source, URL/domain/IP/port, username, password

Brute force

prepare supports a goroutine-parallel, resumable brute force over a charset and length range. Progress is checkpointed to bruteforce.json, so you can pause (Ctrl-C) and resume — even on a different machine — by re-running with the same flags:

gowifi prepare -campaign ./gowifi-campaign -charset abcdef0123456789 -minlen 8 -maxlen 10 -workers 32

Cracking is CPU-bound in Pure Go; wordlists are faster than brute force, and the packets.pcap can be handed to hashcat for large jobs.

Note: WPA2-PSK is crackable offline, but WPA3-SAE is not (it is designed to resist offline dictionary attacks).

Verifying the target system

sudo gowifi check
sudo gowifi check -ap wlan0 -uplink wlan1 -monitor wlan2

check verifies root, nmcli/iptables/sysctl, the NetworkManager daemon, nl80211, wireless adapters, and the AP / station / monitor modes each interface supports. Without interface flags it prints a recommended follow-up command.

Testing

make test          # unit + loopback end-to-end tests
make test-race     # with the race detector
make test-integration  # hardware tests (run on the Pi only)
make vet

Wi-Fi operations are hard to test on a dev host, so every OS boundary is behind a runner.Executor interface. Parsing, DHCP/DNS wire formats and 802.11/netlink encoders are pure functions tested against golden fixtures; the full attack flow is covered by a dry-run end-to-end test against fakes. The integration build tag gates tests that need real hardware. See docs/testing.md for the per-package coverage breakdown.

Layout

• docs/plan.md — full implementation plan and milestones.
• docs/architecture.md — package tree and core interfaces.
• docs/testing.md — how tests are structured and their verified state.
• docs/compatibility.md — supported Wi-Fi dongle chipsets and models.

Disclaimer

Use only on networks you own or are authorized to test.