# omelug/wpa3_tester architecture
> Architecture diagram of the GitHub repository omelug/wpa3_tester, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/omelug/wpa3_tester
- Repository: https://github.com/omelug/wpa3_tester
## Overview
#### 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`](https://github.com/omelug/wpa3_tester/blob/main/CMakeLists.txt) (CMake build), [`wpa3_test/src/setup/config_parser.cpp`](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/config_parser.cpp) (Config parser & validation), [`wpa3_test/src/system/netlink_helper.cpp`](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/system/netlink_helper.cpp) (Wi-Fi / netlink boundary), [`wpa3_test/src/setup/Actor_setup.cpp`](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/Actor_setup.cpp) (Actor setup)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_build["Build & Deployment"]
node_cmake["CMake build
[CMakeLists.txt]"]
node_rpi_provisioning["Raspberry Pi provisioning
deployment assets"]
end
subgraph group_planning["Configuration & Setup"]
node_config_sources["YAML configs & schemas
configuration
[global_config.yaml]"]
node_config_validation["Config parser & validation
setup layer
[config_parser.cpp]"]
node_actor_setup["Actor setup
lifecycle layer
[Actor_setup.cpp]"]
node_run_state["Run & suite state
status tracking
[RunStatus.cpp]"]
end
subgraph group_runtime["Test Runtime"]
node_tester_main["Tester executable
C++ entry point
[main.cpp]"]
node_attack_modules["Attack modules
test implementations"]
node_connection_setup["Actor connections
attack component"]
node_external_adapters["External actor adapters
program integration"]
end
subgraph group_platform["Host & Hardware"]
node_process_manager["Process manager
system control
[ProcessManager.cpp]"]
node_netlink_boundary{{"Wi-Fi / netlink boundary
Linux wireless control
[netlink_helper.cpp]"}}
node_hardware_checks["Hardware capability checks
qualification"]
node_wireless_hardware{{"Linux Wi-Fi hardware
external platform"}}
node_remote_injector["Remote injector
C utility
[main.c]"]
end
subgraph group_results["Evidence & Reporting"]
node_observers["Observer collection
evidence capture
[observers.cpp]"]
node_logging_visuals["Logs & report fillers
result production"]
node_result_overview["Result overview
report executable
[main.cpp]"]
end
node_cmake -->|"builds"| node_tester_main
node_cmake -->|"builds"| node_result_overview
node_cmake -->|"builds"| node_remote_injector
node_rpi_provisioning -.->|"cross-build support"| node_cmake
node_tester_main -->|"loads plan"| node_config_validation
node_config_sources -->|"parsed and validated"| node_config_validation
node_config_validation -->|"validated configuration"| node_actor_setup
node_config_validation -->|"initializes runs"| node_run_state
node_actor_setup -->|"provisions actors"| node_external_adapters
node_actor_setup -->|"prepares interfaces"| node_netlink_boundary
node_tester_main -->|"executes selected tests"| node_attack_modules
node_attack_modules -->|"coordinates actors"| node_connection_setup
node_connection_setup -->|"uses"| node_external_adapters
node_attack_modules -->|"collects evidence"| node_observers
node_attack_modules -->|"drives radio traffic"| node_netlink_boundary
node_external_adapters -->|"launches programs"| node_process_manager
node_process_manager -->|"controls host tooling"| node_wireless_hardware
node_netlink_boundary -->|"configures radios"| node_wireless_hardware
node_hardware_checks -->|"queries capabilities"| node_netlink_boundary
node_remote_injector -->|"injects packets"| node_wireless_hardware
node_observers -->|"capture data"| node_logging_visuals
node_run_state -->|"run outcomes"| node_logging_visuals
node_logging_visuals -->|"result data"| node_result_overview
click node_cmake "https://github.com/omelug/wpa3_tester/blob/main/CMakeLists.txt"
click node_tester_main "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/main.cpp"
click node_config_sources "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/attack_config/global_config.yaml"
click node_config_validation "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/config_parser.cpp"
click node_actor_setup "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/Actor_setup.cpp"
click node_run_state "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/config/RunStatus.cpp"
click node_connection_setup "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/attacks/components/setup_connections.cpp"
click node_observers "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/observer/observers.cpp"
click node_process_manager "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/system/ProcessManager.cpp"
click node_netlink_boundary "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/system/netlink_helper.cpp"
click node_remote_injector "https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/remote_injector/main.c"
click node_result_overview "https://github.com/omelug/wpa3_tester/blob/main/result_overview/src/main.cpp"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_rpi_provisioning toneBlue
class node_config_sources,node_config_validation,node_actor_setup,node_run_state toneAmber
class node_tester_main,node_attack_modules,node_connection_setup,node_external_adapters toneMint
class node_process_manager,node_netlink_boundary,node_hardware_checks,node_wireless_hardware,node_remote_injector toneRose
class node_observers,node_logging_visuals,node_result_overview toneIndigo
```
## Components
### Build & Deployment
- [CMake build](https://github.com/omelug/wpa3_tester/blob/main/CMakeLists.txt): build · Builds tester, result overview, and native components. · `CMakeLists.txt`
- **Raspberry Pi provisioning**: deployment assets · Provides Raspberry Pi 4 provisioning and cross-build support.
### Configuration & Setup
- [YAML configs & schemas](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/attack_config/global_config.yaml): configuration · Defines settings, actors, runs, suites, and attack parameters. · `wpa3_test/attack_config/global_config.yaml`
- [Config parser & validation](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/config_parser.cpp): setup layer · Parses YAML and validates schemas and requirements. · `wpa3_test/src/setup/config_parser.cpp`
- [Actor setup](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/setup/Actor_setup.cpp): lifecycle layer · Creates simulated or external actors and prepares interfaces. · `wpa3_test/src/setup/Actor_setup.cpp`
- [Run & suite state](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/config/RunStatus.cpp): status tracking · `wpa3_test/src/config/RunStatus.cpp`
### Test Runtime
- [Tester executable](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/main.cpp): C++ entry point · `wpa3_test/main.cpp`
- **Attack modules**: test implementations · Configuration-selected DoS, downgrade, enterprise, MITM, scanner, and interface tests.
- [Actor connections](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/attacks/components/setup_connections.cpp): attack component · Establishes connections among configured test actors. · `wpa3_test/src/attacks/components/setup_connections.cpp`
- **External actor adapters**: program integration · Controls hostapd, wpa_supplicant, OpenWrt, and external actors.
### Host & Hardware
- [Process manager](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/system/ProcessManager.cpp): system control · Launches and manages external programs. · `wpa3_test/src/system/ProcessManager.cpp`
- [Wi-Fi / netlink boundary](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/system/netlink_helper.cpp): Linux wireless control · Controls interfaces, namespaces, and nl80211-backed wireless operations. · `wpa3_test/src/system/netlink_helper.cpp`
- **Hardware capability checks**: qualification · Discovers radio capabilities and verifies packet injection.
- **Linux Wi-Fi hardware**: external platform
- [Remote injector](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/remote_injector/main.c): C utility · `wpa3_test/remote_injector/main.c`
### Evidence & Reporting
- [Observer collection](https://github.com/omelug/wpa3_tester/blob/main/wpa3_test/src/observer/observers.cpp): evidence capture · Captures packets, traffic, station state, and resource data. · `wpa3_test/src/observer/observers.cpp`
- **Logs & report fillers**: result production · Produces logs, metadata, reports, and visual suite data.
- [Result overview](https://github.com/omelug/wpa3_tester/blob/main/result_overview/src/main.cpp): report executable · Renders result data into an HTML-oriented overview. · `result_overview/src/main.cpp`
## Connections
- 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