koutto/pi-pwnbox-rogueap: Build a Headless WiFi Hacking Kit

koutto/pi-pwnbox-rogueap: Build a Headless WiFi Hacking Kit

When security professionals arrive on-site for a red team engagement or WiFi assessment, they need a reliable, portable platform that boots without peripherals and provides immediate remote access. Configuring Kali Linux on a Raspberry Pi from scratch—selecting compatible USB WiFi adapters, enabling monitor mode, setting up rogue access points, and establishing remote connectivity—consumes hours that could be spent on actual testing. The koutto/pi-pwnbox-rogueap project addresses this directly: a shell-based automation framework that transforms a Raspberry Pi into a headless PwnBox with preconfigured network interfaces, dedicated attack hardware, and browser-based remote access.

This open-source kit (2,078 GitHub stars, 222 forks, GPL v3.0) targets on-site red team engagements, WiFi security assessments, and hands-on attack practice. It is actively maintained with the last commit dated June 8, 2026.

What is koutto/pi-pwnbox-rogueap?

koutto/pi-pwnbox-rogueap is a collection of shell scripts and configuration files designed to automate the deployment of a Raspberry Pi-based PwnBox and Rogue Access Point. The project is maintained by koutto and falls squarely into the penetration testing hardware / wireless security tooling category.

The project distinguishes itself through specificity rather than abstraction. Rather than offering a generic Kali configuration tool, it encodes hard-won compatibility knowledge for particular WiFi USB adapters—the Alfa AWUS036NEH (Ralink RT2870/3070), Alfa AWUS036ACH (Realtek RTL8812AU), and BrosTrend AC1L AC1200 (also RTL8812AU)—each assigned dedicated roles: built-in Pi wireless for internet connectivity, BrosTrend for persistent AP mode remote access, and Alfa adapters for monitor mode and packet injection during attacks.

The project's relevance stems from two converging needs: the Raspberry Pi 4 and 5's sufficient performance for wireless auditing tasks, and the persistent difficulty of configuring modern Realtek drivers on ARM64 Kali systems. By documenting exact chipset behaviors, providing driver fallback compilation instructions, and automating persistent interface naming via MAC-address-based udev rules, the project saves practitioners from repetitive hardware debugging.

A notable companion asset is the project's WiFi Hacking MindMap and Cheatsheets, which contextualize the hardware setup within broader attack methodologies including MitM techniques.

Key Features

Hardware-Specific Adapter Orchestration The project maps four distinct wireless interfaces to specific physical devices with documented chipset capabilities. The built-in Broadcom 43430 handles internet connectivity with automatic WPA supplicant boot connection. The BrosTrend AC1L serves as a dedicated 2.4/5 GHz access point for remote administration. The Alfa AWUS036NEH provides reliable 2.4 GHz monitor mode and injection (out-of-box Kali support). The Alfa AWUS036ACH extends this to dual-band 802.11ac with equivalent capabilities. This explicit role assignment prevents the common failure mode of attempting monitor mode on an AP-mode adapter or vice versa.

Headless Operation with Dual Remote Access Paths The PwnBox boots without display or keyboard requirements. Remote access is provided through SSH on port 22 and a browser-based VNC-over-HTTP via Apache Guacamole on port 8080. The Guacamole installation includes MySQL^{↗ Bright Coding Blog}-backed authentication and supports up to three concurrent VNC sessions to a local TigerVNC server.

Persistent Network Configuration The install script establishes eth0 and wlan0 as predictable names for built-in interfaces, and wlx* prefixed names for USB adapters based on their MAC addresses. This prevents the interface renaming chaos that typically follows adapter hotplug events on Linux systems.

Dedicated Administration Wireless Network A hidden SSID (PWNBOX_ADMIN) with WPA2-PSK authentication spawns automatically at boot on the designated AP adapter, providing a 10.0.0.1/24 management network independent of target environment infrastructure.

Tomcat Version Auto-Detection The start/stop scripts for Guacamole service management automatically detect whether Tomcat 9 or Tomcat 10 is installed, accommodating newer Kali/Debian releases without manual intervention.

Python^{↗ Bright Coding Blog} 3 Migration The install script has been updated to use Python 3 exclusively, reflecting the removal of Python 2 from modern Kali distributions. Legacy tool compatibility is addressed through containerization suggestions rather than deprecated runtime maintenance.

Use Cases

On-Site Red Team Engagements Practitioners can pre-configure the PwnBox, transport it to target facilities, and establish presence without requiring local network credentials or infrastructure access. The hidden PWNBOX_ADMIN network provides a fallback command channel. The compact form factor—Pi in case with USB adapters and optional power bank—minimizes physical footprint.

WiFi Security Assessments The dual Alfa adapter configuration supports comprehensive auditing: the AWUS036NEH for reliable 2.4 GHz coverage (compatible with older corporate environments) and the AWUS036ACH for 5 GHz and 802.11ac enterprise networks. Tools like Aircrack-ng, airgeddon, Kismet, and Bettercap operate with verified hardware compatibility.

Wireless Attack Technique Practice The included mind map and cheatsheets provide structured learning paths from theoretical 802.11 frame mechanics through practical command sequences. The headless operation encourages remote tool interaction patterns identical to real engagement workflows.

Rogue Access Point Deployment The BrosTrend adapter's dedicated AP role, combined with dnsmasq DHCP/DNS services, enables controlled evil twin or captive portal scenarios. The explicit separation between attack adapters (Alfa) and infrastructure adapters (BrosTrend, built-in wlan0) reduces configuration errors during multi-phase attacks.

Remote Lab Access For practitioners maintaining home or colocated testing labs, the Guacamole VNC-over-HTTP interface eliminates client-side VNC viewer requirements and traverses restrictive egress networks through standard HTTPS-like traffic patterns on port 8080.

Installation & Setup

The installation requires Kali Linux ARM (64-bit strongly recommended for Pi 4/5), internet connectivity during setup, and root privileges. The following reproduces the documented procedure exactly:

1. Prepare Base System

Download the Kali Linux ARM image from https://www.kali.org/get-kali/#kali-arm and flash to a 64 GB Class 10 or better microSD card using Raspberry Pi Imager or dd.

2. Initial Boot and Network Verification

Boot the Pi, log in with default credentials (kali/kali), and confirm internet connectivity:

ping 8.8.8.8

3. Clone Repository

git clone https://github.com/koutto/pi-pwnbox-rogueap.git

4. Configure Installation Parameters

Edit scripts/install-system.sh before execution. Critical settings include:

• GUACAMOLE_PASSWORD and GUACAMOLE_MYSQL_PASSWORD: Apache Guacamole authentication credentials
• WiFi interface persistent names: wlxaabbccddeeff format matching adapter MAC addresses
• eth0 and wlan0 MAC addresses for built-in interfaces
• WIFI_SSID and WIFI_PASSPHRASE for automatic client connection on built-in wireless

5. Execute Install Script

cd pi-pwnbox-rogueap/scripts
./install-system.sh

The script pauses after each step to permit output inspection. This behavior is intentional—errors in driver compilation or service configuration are visible before proceeding.

6. Post-Install Verification

Reboot and validate interface configuration:

ip a
iwconfig

Expected state: eth0 and wlan0 for built-in interfaces; wlx* prefixed names for USB adapters; active AP PWNBOX_ADMIN on designated wlx* interface.

7. Guacamole VNC Connection Setup

Navigate to http://<ip_pwnbox>:8080/guacamole/ and authenticate as guacadmin. Configure a new connection:

8. Credential Hardening

passwd kali  # Change system password

Additionally change Guacamole default credentials via http://<ip_pwnbox>:8080/guacamole/#/manage/mysql/users/guacadmin.

Real Code Examples

The README provides specific commands for operational tasks. Below are reproduced examples with contextual explanation.

Example 1: Adding a New WiFi Network to PwnBox

When the PwnBox must connect to a new wireless network not present in its saved configuration, the built-in wlan0 interface requires manual WPA passphrase addition:

# Generate WPA configuration stanza and append to supplicant config
wpa_passphrase <SSID> <passphrase> >> /etc/wpa_supplicant.conf

# Associate with the network in background mode
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf

# Obtain DHCP lease
dhclient -v wlan0

# Verify connectivity
ping 8.8.8.8

This sequence is necessary because the install script disables NetworkManager in favor of classic /etc/network/interfaces management. The -B flag daemonizes wpa_supplicant; -v on dhclient provides progress visibility. This approach prioritizes deterministic startup behavior over dynamic network management—appropriate for a device with known-good operational networks but occasionally requiring ad-hoc connectivity.

Example 2: Manual Driver Compilation for BrosTrend AC1L

When the vendor repository (deb.trendtechcn.com) is unavailable, the RTL88x2BU driver must be built locally:

# Install build dependencies
sudo apt-get install -y bc git build-essential dkms

# Clone driver source to DKMS-expected path
sudo git clone https://github.com/cilynx/rtl88x2bu.git /usr/src/rtl88x2bu-5.8.7

# Register with DKMS for automatic rebuild on kernel updates
sudo dkms add -m rtl88x2bu -v 5.8.7

# Build and install for current kernel
sudo dkms autoinstall

The explicit version 5.8.7 in the path matches DKMS module naming conventions. This fallback procedure is critical because the BrosTrend adapter serves the PWNBOX_ADMIN AP; without functional drivers, remote administration capability is lost.

Example 3: DHCP Service Conflict Resolution

The install script includes both dnsmasq (serving the admin AP) and isc-dhcp-server (required by tools like Fluxion). Port 67/UDP conflicts are prevented by default—isc-dhcp-server is disabled—but manual switching is documented:

# Stop admin AP DHCP service
systemctl stop dnsmasq

# Start dedicated DHCP server for attack tooling
systemctl start isc-dhcp-server

This operational pattern reflects real multi-tool workflows where the PwnBox transitions between infrastructure provisioner and attack participant roles.

Example 4: NetworkManager Restoration

For practitioners requiring temporary NetworkManager operation (perhaps for WiFi site survey with modern GUI tools):

systemctl start NetworkManager
systemctl enable NetworkManager

The README explicitly notes this as a reversible deviation from the project's designed network stack.

Advanced Usage & Best Practices

Interface Naming Discipline The persistent wlx* naming scheme prevents the wlan1 → wlan2 renaming that occurs when USB adapters enumerate in different orders. However, this requires accurate MAC address documentation during initial setup. Verify with ip link show before running install-system.sh; post-install changes require manual /etc/udev/rules.d/70-persistent-net.rules editing or script re-execution.

Memory-Conscious Guacamole Operation The README explicitly warns that Guacamole consumes substantial RAM. For memory-constrained Pi 3 deployments or when only SSH access is needed, use the provided stop-guacamole.sh script. Conversely, GUI-dependent tools like airgeddon (which spawns multiple xterm windows) require Guacamole or direct HDMI access.

64-bit ARM Considerations for Pi 4/5 While the project states all tools function on arm64, practitioners should verify specific precompiled binaries in their workflow. The README suggests box64 as an x86_64 emulation fallback or manual compilation where source is available. Testing critical tools before field deployment is prudent.

Boot Time Optimization The documented allow-hotplug eth0 modification addresses a common headless deployment friction: DHCP timeout waits on unplugged Ethernet. For exclusively wireless-operated PwnBoxes, this change is recommended.

Credential Hygiene The default PWNBOX_ADMIN passphrase (Koutto!PwnB0x!) and Guacamole credentials must be changed before any operational use. The hidden SSID provides obscurity, not security—active scanning reveals the network presence.

Comparison with Alternatives

The WiFi Pineapple offers polished cloud integration and commercial support; koutto/pi-pwnbox-rogueap provides transparency, adapter choice, and no subscription dependencies. Generic Kali ARM installations demand substantially more configuration effort for equivalent wireless functionality. The PwnBox project occupies a middle ground: more structured than raw Kali, more flexible than proprietary hardware.

FAQ

What Raspberry Pi models are supported? Pi 3 Model B+, Pi 4, and Pi 5. Pi 4/5 strongly benefit from 64-bit Kali ARM images.

Can I use different WiFi adapters than those listed? Monitor mode, injection, and AP mode capabilities depend on specific chipset drivers. The documented adapters are verified; substitutes require independent compatibility verification.

Is Python 2 still required? No. The install script uses Python 3 exclusively. Legacy Python 2 tools should be migrated or containerized.

Why does Guacamole fail to start on fresh Kali installs? Newer Kali releases ship Tomcat 10. The provided scripts auto-detect this, but manual verification via systemctl list-unit-files | grep tomcat may be needed.

How do I find the PwnBox IP on a LAN network? Use network discovery tools like netdiscover or check your DHCP server leases. The admin network IP is always 10.0.0.1.

What license governs use? GNU General Public License v3.0, permitting modification and redistribution with source disclosure requirements.

Is active maintenance expected to continue? The repository shows activity through June 2026, but as with volunteer open-source projects, future maintenance depends on maintainer availability.

Conclusion

koutto/pi-pwnbox-rogueap delivers a pragmatic, hardware-grounded solution for practitioners who need reliable, repeatable Raspberry Pi-based wireless testing platforms. Its value lies not in novelty but in operational specificity: the exact adapter chipsets, the verified driver compilation paths, the persistent interface naming, and the dual remote access methods all address real friction points encountered when building similar kits from scratch.

The project best serves security professionals comfortable with shell-based configuration who want documented, version-controlled infrastructure rather than opaque appliances. The included mind map and cheatsheets provide educational scaffolding for those building wireless attack proficiency.

For a field-ready PwnBox with known-good hardware compatibility and headless operation, review the complete documentation and source at https://github.com/koutto/pi-pwnbox-rogueap.