The Problem

Network administrators need a repeatable way to assess Wi‑Fi security on Linux machines without cobbling together ad‑hoc scripts. The gap is a unified, GUI‑driven tool that can invoke the low‑level aircrack-ng suite (capture, deauth, handshake extraction) while handling privilege escalation safely.

What This Does

airgorah bundles three Rust crates:

  • crates/agent – a lightweight privileged daemon (airgorah-agent) that talks directly to the wireless interface. Core work lives in src/backend/ (e.g., capture.rs, deauth.rs, scan.rs, pcap.rs).
  • crates/common – shared library (src/lib.rs) exposing types, IPC primitives (ipc.rs), and handshake handling (handshake.rs).
  • crates/gui – a GTK4 front‑end (src/main.rs) that presents a modern UI. UI callbacks delegate to src/backend/client.rs, which uses the common IPC layer to request actions from the agent.

The repository also ships a Dockerfile for containerised builds and a GitHub Actions workflow (.github/workflows/CI.yml) that runs cargo fmt/cargo clippy and builds all crates.

How It Is Wired

Entry point → agent

  1. Execution starts in crates/agent/src/main.rs. It parses CLI flags (if any) and calls backend::app::run() (see src/backend/app.rs).
  2. run() creates an ipc::Server (from crates/common/src/ipc.rs) listening on a Unix socket, then spawns async tasks for each backend module based on incoming IPC requests.
  3. A request such as “capture traffic” is routed to backend::capture::start_capture() which opens a raw socket (raw_socket.rs) or libpcap handle (pcap.rs) on the selected interface (interface.rs). The capture loop writes packets to a temporary pcap file and notifies the GUI via IPC messages.

Entry point → GUI

  1. crates/gui/src/main.rs initializes GTK4, loads icons, and constructs the top‑level UI (frontend/mod.rs).
  2. UI actions (e.g., pressing “Deauth”) invoke methods in frontend/connections/deauth.rs, which instantiate backend::client::AgentClient.
  3. AgentClient opens the same Unix socket defined in crates/common/src/ipc.rs and sends a serialized command (e.g., Command::Deauth { mac, iface }).
  4. The agent receives the command, matches it in backend::app::handle_command(), and forwards it to backend::deauth::run_deauth(). This module uses vendors.rs to map MAC prefixes and issues the actual deauthentication frames via the raw socket.

Data flow – The only external side‑effects are:

  • Direct access to the wireless NIC (monitor mode, packet injection).
  • Filesystem writes for captured pcap/handshake data (paths defined in globals.rs).
  • UI updates sent back over the IPC channel.

The IPC layer is the central hub; all privileged actions funnel through it, making it the highest‑impact component for security reviews or refactoring.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/airgorah
cd airgorah

# Build all crates (requires Rust toolchain)
cargo build --release

# Optional: build the Docker image
docker build -t airgorah .

# Run the privileged agent (needs polkit or sudo)
sudo target/release/airgorah-agent &

# Launch the GUI (runs as normal user)
target/release/airgorah-gui

No additional configuration files are present; the GUI prompts for the wireless interface and output directory at runtime.

Real‑World Use

A penetration tester plugs a compatible USB Wi‑Fi adapter, starts airgorah-agent with root rights, then runs the GUI on the same host. Using the “Scan” view they list nearby APs, select a target, click “Deauth” to force a client reconnect, and capture the resulting WPA handshake. The handshake file is saved automatically and can be fed to aircrack-ng for offline cracking.

Code Health & Issues

  • Medium – Untested code – repository-wide – No tests/ directory or #[cfg(test)] modules were found, meaning core paths (capture, deauth, IPC) lack automated verification.
  • Low – Limited test coverage in CI – .github/workflows/CI.yml runs only cargo fmt and cargo clippy – Build passes but functional testing is absent.
  • Low – Documentation gaps – only README and two markdown docs – No inline API docs (///) for public functions in crates/common, making onboarding slower.

No secrets, hard‑coded credentials, or license anomalies were detected.

The Bottom Line

airgorah delivers a cohesive Rust‑based GUI wrapper around the aircrack-ng toolset, with a clear separation between privileged agent and user‑space UI via a single IPC channel. The codebase is functional but lacks automated tests and deeper documentation, which raises maintenance risk for security‑critical changes. It is suitable for teams comfortable with Rust and Linux networking who need a ready‑made audit UI and are prepared to add their own test suite.