How omelug/wpa3_tester works
Purpose and entry points
wpa3_tester is a C++ automation framework for executing WPA3/Wi-Fi security tests, attacks, scans, and hardware-capability checks while collecting targeted evidence and reports. The primary executable starts at wpa3_test/main.cpp; build composition is rooted in CMakeLists.txt and wpa3_test/CMakeLists.txt. A separate result-rendering executable lives in result_overview/src/main.cpp.
Configuration-driven test planning
YAML defines global settings, actors, observers, individual runs, schemas, and generated suites. Parsing and validation are centralized in wpa3_test/src/setup/config_parser.cpp, wpa3_test/src/setup/YAMLValidator.cpp, and wpa3_test/src/setup/requirement_validation.cpp. Canonical configuration and validation schemas are under wpa3_test/attack_config/global_config.yaml, wpa3_test/attack_config/validator/, and attack-specific folders such as wpa3_test/attack_config/DoS_soft/.
Setup and actor lifecycle
Setup turns validated configuration into internal, simulated, or external actors and prepares their interfaces/processes. The boundary is represented by actor config types in wpa3_test/include/config/Actor_Config/ and setup implementations in wpa3_test/src/setup/Actor_setup.cpp and wpa3_test/src/setup/setup.cpp. Run and suite state are tracked through wpa3_test/src/config/RunStatus.cpp and wpa3_test/src/config/RunSuiteStatus.cpp.
System and hardware control
The runtime targets Linux wireless hardware, network interfaces, namespaces, and subprocesses. wpa3_test/src/system/ProcessManager.cpp manages external program execution; wpa3_test/src/system/netlink_helper.cpp and wpa3_test/src/system/nl80211_compat.cpp form the Wi-Fi/netlink boundary. Hardware capability discovery and packet-injection qualification are implemented under wpa3_test/src/system/hw_capabilities/; bundled ath9k HTC firmware support is in wpa3_test/src/system/firmware/ath9k-firmware/.
Test/attack execution modules
Attack implementations are modular C++ units selected by configuration. Major families include hard/soft DoS, downgrade, enterprise, multi-channel MITM, scanners, and two-interface tests: wpa3_test/src/attacks/DoS_hard/, wpa3_test/src/attacks/DoS_soft/, and wpa3_test/src/attacks/mc_mitm/. Shared attack setup establishes actor connections in wpa3_test/src/attacks/components/setup_connections.cpp. The attack layer drives real radio traffic and coordinates configured AP/client/rogue-AP actors.
External programs and observers
Adapters integrate hostapd, wpa_supplicant, and OpenWrt/external actors through wpa3_test/src/ex_program/hostapd/ and wpa3_test/src/ex_program/external_actors/. Observer wrappers collect packet captures, traffic, station state, and resource data via wpa3_test/src/observer/observers.cpp, wpa3_test/src/observer/tcpdump_wrapper.cpp, and wpa3_test/src/observer/tshark_wrapper.cpp; configured observer programs also include Mausezahn, iperf, and resource/station checkers.
Results and deployment
Logs, device metadata, and reports are produced by wpa3_test/src/logger/ and visual suite/result fillers in wpa3_test/src/visual/. result_overview/ consumes result data to generate an HTML-oriented overview with static assets. The project is CMake-based, with a C remote injector at wpa3_test/remote_injector/main.c; Raspberry Pi 4 provisioning/cross-build assets are under tester_setup/raspberry_pi4/.
Main entry points: CMakeLists.txt CMake build · config_parser.cpp Config parser & validation · netlink_helper.cpp Wi-Fi / netlink boundary · Actor_setup.cpp Actor setup
Components 18
Build & Deployment
- CMake build · Builds tester, result overview, and native components.
CMakeLists.txt - Raspberry Pi provisioning · Provides Raspberry Pi 4 provisioning and cross-build support.
Configuration & Setup
- YAML configs & schemas · Defines settings, actors, runs, suites, and attack parameters.
wpa3_test/attack_config/global_config.yaml - Config parser & validation · Parses YAML and validates schemas and requirements.
wpa3_test/src/setup/config_parser.cpp - Actor setup · Creates simulated or external actors and prepares interfaces.
wpa3_test/src/setup/Actor_setup.cpp - Run & suite state
wpa3_test/src/config/RunStatus.cpp
Test Runtime
- Tester executable
wpa3_test/main.cpp - Attack modules · Configuration-selected DoS, downgrade, enterprise, MITM, scanner, and interface tests.
- Actor connections · Establishes connections among configured test actors.
wpa3_test/src/attacks/components/setup_connections.cpp - External actor adapters · Controls hostapd, wpa_supplicant, OpenWrt, and external actors.
Host & Hardware
- Process manager · Launches and manages external programs.
wpa3_test/src/system/ProcessManager.cpp - Wi-Fi / netlink boundary · Controls interfaces, namespaces, and nl80211-backed wireless operations.
wpa3_test/src/system/netlink_helper.cpp - Hardware capability checks · Discovers radio capabilities and verifies packet injection.
- Linux Wi-Fi hardware
- Remote injector
wpa3_test/remote_injector/main.c
Evidence & Reporting
- Observer collection · Captures packets, traffic, station state, and resource data.
wpa3_test/src/observer/observers.cpp - Logs & report fillers · Produces logs, metadata, reports, and visual suite data.
- Result overview · Renders result data into an HTML-oriented overview.
result_overview/src/main.cpp
Connections 23
- CMake build → Tester executable: builds
- CMake build → Result overview: builds
- CMake build → Remote injector: builds
- Raspberry Pi provisioning → CMake build: cross-build support
- Tester executable → Config parser & validation: loads plan
- YAML configs & schemas → Config parser & validation: parsed and validated
- Config parser & validation → Actor setup: validated configuration
- Config parser & validation → Run & suite state: initializes runs
- Actor setup → External actor adapters: provisions actors
- Actor setup → Wi-Fi / netlink boundary: prepares interfaces
- Tester executable → Attack modules: executes selected tests
- Attack modules → Actor connections: coordinates actors
- Actor connections → External actor adapters: uses
- Attack modules → Observer collection: collects evidence
- Attack modules → Wi-Fi / netlink boundary: drives radio traffic
- External actor adapters → Process manager: launches programs
- Process manager → Linux Wi-Fi hardware: controls host tooling
- Wi-Fi / netlink boundary → Linux Wi-Fi hardware: configures radios
- Hardware capability checks → Wi-Fi / netlink boundary: queries capabilities
- Remote injector → Linux Wi-Fi hardware: injects packets
- Observer collection → Logs & report fillers: capture data
- Run & suite state → Logs & report fillers: run outcomes
- Logs & report fillers → Result overview: result data