Eggsec provides standalone-complete passive WiFi network reconnaissance and basic security posture assessment via the wireless feature. This enables defense validation, lab-based assessment of wireless infrastructure, and identification of obviously weak or misconfigured networks.
Passive reconnaissance is the default. Active deauth/disassoc is available under wireless-advanced (CLI deauth and TUI active mode). Handshake capture remains future work.
(Phase 0 — complete 2026-06-11; Phase 1 — complete 2026-06-12): Standalone-complete passive WiFi recon + rogue heuristic + reporting bridge + TUI tab + policy integration. Active deauth/disassoc is available under wireless-advanced in both CLI and TUI, with dry-run default and live confirmation. See the active loadout details (completed).
Build with --features wireless (or --features full) for passive scanning.
Build with --features wireless-advanced (or --features full) to also enable active deauth/disassoc attacks (Phase 1), exposed through the CLI deauth subcommand and the TUI active mode:
# Passive only
cargo build --release -p eggsec-cli --features wireless
# With active attacks (Phase 1 deauth)
cargo build --release -p eggsec-cli --features wireless-advancedRuntime requirements (Linux):
- Root (or
CAP_NET_ADMIN) foriwlist scan wireless-toolspackage providingiwlist(e.g.sudo apt-get install wireless-tools)- Wireless interface in managed mode and up (e.g.
wlan0)
macOS/Windows: Not supported in this phase (iwlist is Linux-specific).
- Use only on networks you own or are explicitly authorized to assess (lab, authorized defensive validation).
- This is passive listening — it does not transmit or disrupt.
- Root is required for raw interface access; do not run untrusted code as root.
- Legal/regulatory restrictions on spectrum monitoring may apply in some jurisdictions — know your local rules.
- Production impact: minimal (passive), but repeated scans or suspicious activity can still be noticed by monitoring systems.
- The CLI and TUI both surface prominent warnings about privileges and authorized use.
See also: docs/SAFETY.md, architecture/wireless.md, and the EnforcementContext policy gate (handler uses SafeActive risk + wireless feature requirement).
# Basic scan (default ~10s)
eggsec wireless wlan0
# With JSON output
eggsec wireless wlan0 --json
# Write to file
eggsec wireless wlan0 -o results.json
# Longer scan window
eggsec wireless wlan0 --duration 30
# Repeated scans (useful for observing changes / basic rogue heuristics over time)
eggsec wireless wlan0 --repeat 5 --duration 10
# Quiet (minimal stderr)
eggsec wireless wlan0 -q --json
# Dry-run (plan/CI validation; no privileges or iwlist required; emits valid JSON + notes)
eggsec wireless wlan0 --dry-run --json
# Repeated scans with known-good allowlist (suppresses rogue heuristic for your lab APs)
eggsec wireless wlan0 --repeat 3 --known-good ./lab-aps.txt
# Show full rogue/suspicious details (analysis always runs; default shows count + hint only)
eggsec wireless wlan0 --detect-suspicious
# Help
eggsec wireless --helpImportant: The command prints a clear root/CAP_NET_ADMIN/iwlist permissions warning (unless --quiet). Use only in lab/defense-validation contexts.
Rogue / Suspicious Detection UX: Analysis for rogue/Evil-Twin candidates (same SSID + differing BSSID or security type) always runs. In default human output, only a compact summary line is shown ("Rogue/suspicious candidates: N (use --detect-suspicious to show full details)"). Use --detect-suspicious for the full Findings list (with descriptions/recommendations). Use --known-good to suppress known-authorized APs from triggering the heuristic (recommended for lab baselines). A short explanatory note is included in output when candidates are present. Severity is Low (BSSID diff) or Medium (security config differences, possible downgrade). Heuristic only — always verify physically or via inventory.
- SSID (network name), BSSID (AP MAC), channel, signal strength (dBm)
- Security type: Open, WEP, WPA, WPA2, WPA3, Enterprise (802.1X), Unknown
- WPS enabled (via beacon/IE indicators in iwlist output)
- Hidden SSIDs (ESSID empty or explicitly hidden)
- WPA2/WPA3 transition mode (mixed mode networks)
- Basic vulnerability findings via
analyze_networks:- Open networks (Medium)
- WEP (High)
- WPA (legacy TKIP, Medium)
- Unknown security (Medium)
- Enterprise (informational/low; verify RADIUS/EAP/cert)
- Weak signal (<= -80 dBm)
- WPS enabled (advisory)
- Hidden SSID (advisory)
- Transition mode (advisory)
- Possible Rogue AP / Evil Twin candidate (passive heuristic: same SSID with differing BSSID or security type across cells; Low severity, labeled as such)
- Recommendations generated for weak/legacy configurations + "Run repeated scans to observe changes over time for rogue detection."
Findings and networks are also exposed via to_scan_report_data() for unified reporting (JSON, HTML, Markdown, etc.).
The Wireless tab in the TUI provides both passive scanning and active attack capabilities.
Passive Scanning (wireless feature):
- Enter your wireless interface name and press Enter
- Results display detected networks with SSID, BSSID, channel, security, and signal strength
- Rogue and suspicious network heuristics are applied automatically
Active Attacks (wireless-advanced feature):
- Press
ato toggle between passive and active attack mode - Active mode shows input fields for: BSSID, Client MAC, Frame Count, Rate Limit
- Press
dto toggle Dry Run mode (on by default for safety) - Press Enter to execute — the policy confirmation overlay will appear for live (non-dry-run) attacks; dry-run attacks (default) launch without a prompt
- Active attacks require
OperationRisk::Intrusiveclearance and explicit operator confirmation when live - Results display findings, evidence, and recommendations
- The active attack runs through the same
TaskConfig::WirelessActiveworker as the CLI path; result updatesset_active_results()and renders in the same Results view
Key Bindings:
a— Toggle active/passive moded— Toggle dry-runEnter— Start scan or attackEscape— Stop running operation
Navigation, export, and task management follow standard TUI tab patterns (see architecture/tui.md for tab architecture).
- Human-readable text (default) includes networks table + Recommendations + Findings/Vulnerabilities sections.
--jsonproduces the fullWirelessScanResult(networks + recommendations + metadata). For repeated scans (--repeat > 1) this is wrapped as{ "last_scan": <WirelessScanResult>, "repeat_count": N, "summary": "..." }. The native shape (direct result or wrapped) is accepted directly byeggsec report convert(auto-bridged toScanReportDatawhen thewirelessfeature is enabled).- File output (
-o) supported for both modes. - Structured findings feed into
ScanReportData(viato_scan_report_data) for SARIF/JUnit/HTML/Markdown/etc. pipelines. The bridge is optional and opt-in. - New fields on
WirelessNetwork/ report data:wps_enabled,is_hidden,transition_mode(serde defaulted for forward compat on old reports). - Note:
to_scan_report_data()(used for SARIF/JUnit/HTML/Markdown/etc.) always callsanalyze_networks(..., None); rogue/Evil-Twin candidates are therefore always present in structured report findings regardless of--known-good.--known-goodsuppression applies to CLI human-readable rogue findings plus repeat-scan diffs/summary, not to the raw report data.
pub struct WirelessNetwork {
pub ssid: String,
pub bssid: String,
pub channel: u8,
pub security_type: SecurityType,
pub signal_strength: i32,
pub last_seen: String,
pub wps_enabled: bool,
pub is_hidden: bool,
pub transition_mode: bool,
}
pub enum SecurityType { Open, WEP, WPA, WPA2, WPA3, Enterprise, Unknown }
pub struct WirelessScanResult {
pub interface: String,
pub networks: Vec<WirelessNetwork>,
pub scan_duration_secs: u64,
pub recommendations: Vec<String>,
}
pub struct WirelessVulnerability { /* ... from analyze_networks ... */ }See crates/eggsec/src/wireless/mod.rs for full definitions and WirelessScanner::analyze_networks.
WARNING: Requires root (or CAP_NET_ADMIN) and 'iwlist' (wireless-tools). ...
Scanning on wlan0 for ~10s...
Wireless Scan Results - Interface: wlan0
Networks found: 3
1. CorpNet
BSSID: 00:11:22:33:44:55
Channel: 6
Security: WPA2
Signal: -62 dBm
Last seen: 2026-...
...
Findings / Vulnerabilities:
- Open Network (Medium): ...
- WPS Enabled (Medium): ...
Rogue/suspicious candidates: 1 (use --detect-suspicious to show full details)
Note: Rogue/Evil-Twin detection is a passive heuristic (multiple BSSIDs or security differences for same SSID). Use --known-good for lab baselines; verify with physical survey or asset inventory.
Recommendations:
- ...
- Run repeated scans to observe changes over time for rogue detection.
(JSON mode includes full structured data with the three extra booleans per network.)
- Lab / defense validation: Repeated scans (
--repeat) against known-good APs to baseline "normal" BSSIDs/channels/security; flag deviations. - CI / regression: JSON output +
to_scan_report_data(or rely on CLI auto-bridge) into SARIF/JUnit for wireless posture checks (e.g. "no open/WEP/WPA in this environment"). - Rogue hunting (passive): Use
--repeatand review the summarized rogue count in default output, or add--detect-suspiciousfor the full findings list. Cross-check against asset inventory. This is a heuristic only — follow up with authorized physical/radio validation. - Reporting: Pipe native
--jsontoeggsec report convert(auto-bridged) or consumeScanReportDatadirectly via the bridge.
- Always run as root (or with CAP_NET_ADMIN) for real scans; use
--dry-run --jsonin CI or unprivileged planning to validate flags/JSON shape without privileges. - Use
--known-goodfor your lab environment. Create a file with authorized SSID, BSSID, or "SSID,BSSID" entries (one per line;#comments supported). This suppresses false-positive rogue/Evil-Twin candidates for your known APs while still detecting new or changed ones. - Use
--repeat(e.g. 3–10) with a short--duration(5–15s) for monitoring or change detection. Review per-scan "Changes since previous" diffs (new nets, sec changes, signal drift, new rogue candidates) and the final "Scan summary over time". - Default rogue output is summarized: Rogue/Evil-Twin candidates are always analyzed. Human output shows a count + hint by default. Add
--detect-suspiciouswhen you need the full details + recommendations for triage. - JSON for automation:
--json(with or without--repeat) produces machine-readableWirelessScanResult(last successful scan). With--repeat >1, a"summary"envelope field is included (alongsidelast_scanandrepeat_count). Pipe toeggsec reportor your own post-processing. - Baseline before hunting: Run repeated scans in a clean lab state, save
--known-good+ JSON baselines. Re-run later to observe drift or new BSSIDs. - Interpret findings conservatively: Open/WEP/WPA are high-confidence issues. Rogue is a passive heuristic only — same SSID from multiple BSSIDs or security downgrade signals can be legitimate roaming or guest nets; always cross-check MAC inventory or perform physical survey.
- TUI: The Wireless tab provides interactive entry + table view. Use for quick visual scans; exports and session features follow standard TUI patterns.
- Prefer lab environments: Wireless is a defense-lab / regression tool. Do not use for unauthorized spectrum monitoring. Know your local regulations.
Example practical flows:
# Single authoritative scan + JSON record
sudo eggsec wireless wlan0 --json -o baseline.json
# Dry-run to validate a CI command shape (no root needed)
eggsec wireless wlan0 --dry-run --repeat 3 --json
# Lab monitoring with known-good baseline (repeat 5x, 10s each)
sudo eggsec wireless wlan0 --repeat 5 --duration 10 --known-good ./authorized-aps.txt
# Full rogue details on demand
sudo eggsec wireless wlan0 --detect-suspicious --repeat 3- Active attacks (deauth, disassociation, Evil Twin AP creation, handshake capture, etc.) — Phase 1 deauth/disassoc is now implemented (see "Active Attacks (Phase 1)" below); Phase 2+ handshake capture and Phase 3+ flood/rogue-sim remain future work. Phase 1 design (completed): deauth gated behind
wireless-advancedfeature flag = ["wireless"]; heavily policy-gated with--allow-active-wireless, packet budgets, andIntrusiverisk tier; MCP/agent tool exposure remains intentionally absent for the entire wireless surface, including advanced — standalone defense-lab design decision, not registered asSecurityTool. - Handshake capture / PMKID / WPS PIN attacks / KRACK-style testing
- Deep WPS enumeration beyond beacon flags
- Bluetooth/BLE
- Windows/macOS native scanning (iwlist Linux-only)
- Full pipeline integration (wireless is a standalone-complete defense-lab surface; MCP and agentic tool exposure is intentionally absent per design decision — wireless is not registered as a SecurityTool and does not appear in tools/list or agent dispatch). Optional reporting bridge only. See architecture/wireless.md (MCP / Agentic section).
Build with --features wireless-advanced (or --features full).
Phase 1 implements targeted and broadcast deauthentication/disassociation frame injection for defense validation, WIPS/WIDS testing, and AP/client resilience regression.
- Root or
CAP_NET_ADMINprivileges - Monitor-mode capable wireless interface (e.g.,
wlan0moncreated viaairmon-ng start wlan0) - Explicit
--allow-active-wirelessflag for non-dry-run execution - Only on networks you own or have explicit written authorization to test
# Dry-run deauth (no frames sent; valid JSON output; no privileges required)
sudo eggsec wireless wlan0 deauth --bssid AA:BB:CC:DD:EE:FF --dry-run --json
# Targeted client deauth (lab only)
sudo eggsec wireless wlan0 deauth \
--bssid 00:11:22:33:44:55 \
--client aa:bb:cc:dd:ee:ff \
--count 30 \
--reason-code 7 \
--allow-active-wireless \
--manual-override-reason "Authorized WIPS regression test on lab AP"
# Broadcast deauth (all clients on AP - higher impact)
sudo eggsec wireless wlan0 deauth --bssid 00:11:22:33:44:55 --broadcast --count 100
# Output to file
eggsec wireless wlan0 deauth --bssid AA:BB:CC:DD:EE:FF --dry-run -o deauth-plan.json| Argument | Description |
|---|---|
--bssid |
Target AP BSSID (required, e.g., AA:BB:CC:DD:EE:FF) |
--client |
Target client MAC (omit for broadcast deauth to all clients) |
--broadcast |
Send to broadcast address (all clients on AP) |
--count |
Number of frames to send (default: 50) |
--reason-code |
802.11 reason code (default: 7 = class 3 from nonassociated STA) |
--max-frames |
Hard budget cap (default: 100, max enforced) |
--fps |
Frame injection rate in frames/sec (default: 10, max enforced) |
--dry-run |
Plan mode: show what would be sent without transmitting |
--allow-active-wireless |
Required for non-dry-run execution |
--json |
JSON output |
--output FILE |
Write output to file |
--monitor-iface IFACE |
Specify monitor-mode interface |
The deauth subcommand crafts 802.11 deauthentication frames (with radiotap headers) and optionally injects them via a raw socket on a monitor-mode interface. Each frame targets a specific (BSSID, client) pair or broadcasts to all clients of an AP.
Produces wireless-active-deauth findings with severity High, evidence (frames sent, target, reason code), and remediation (enable 802.11w/PMF, check WIPS detection latency, verify client reconnection).
- Lab-only: Active frame injection can disrupt legitimate wireless clients
- Defense validation: Intended for WIPS/WIDS regression testing and AP resilience validation
- Feature gated: Requires
wireless-advancedfeature (not included in default build) - Policy gated:
OperationRisk::Intrusive+required_features: ["wireless-advanced"] - Manual confirmation:
--allow-active-wirelessrequired for non-dry-run (audited) - Budget enforcement: Hard caps on max frames (1000) and rate (100 fps)
- Dry-run safe:
--dry-runproduces valid JSON without any transmission
See docs/SAFETY.md.
Active attack results can be converted to unified reports (SARIF, JUnit, HTML, Markdown, CSV) via the reporting bridge. The auto-bridge works for both CLI and TUI output:
# Dry-run deauth → JSON → SARIF report
sudo eggsec wireless wlan0 deauth --bssid AA:BB:CC:DD:EE:FF --dry-run --json -o deauth.json
eggsec report convert deauth.json -f sarif
# Real deauth → HTML report
sudo eggsec wireless wlan0 deauth --bssid AA:BB:CC:DD:EE:FF --count 10 --allow-active-wireless --json -o deauth.json
eggsec report convert deauth.json -f htmlThe bridge produces wireless-active-* categories (e.g. wireless-active-deauth) for findings. Native --json output from eggsec wireless <iface> deauth is auto-bridged by eggsec report convert when the wireless-advanced feature is enabled. TUI-generated results follow the same bridge path when exported to JSON.
- Unit (no hardware): parser, security-type, and state tests under
wireless::— run withcargo test -p eggsec --lib --features wireless wireless::. - Passive fixture (no hardware/privilege): canned
iwlistoutput, multi-BSSID rogue-heuristic networks, and known-good suppression inwireless::fixture— same command,wireless::fixture::selector. - Active fixture (bytes only, never transmitted): deauth/disassoc frame
construction under
wireless-advanced—cargo test -p eggsec --lib --features wireless,wireless-advanced wireless::fixture::. - Manual RF (lab hardware only, never CI): real scans on owned nets and
any frame injection. Documented procedure; not required for release
readiness. See PLATFORM.md and
eggsec doctor.
- "iwlist: command not found" or permission denied: install wireless-tools; run as root or grant CAP_NET_ADMIN; ensure interface exists and is up (
ip link show). For planning without privilege use--dry-run --json; for the matrix useeggsec doctor. - No networks seen: wrong interface, interface down, regulatory domain restrictions, or very short duration.
- "No wireless interface specified": pass the interface name (e.g.
wlan0,wlp3s0). - TUI wireless tab not visible: rebuild TUI/CLI with
--features wireless. - Tests: Unit tests cover parsing and analysis (no hardware required). Run with
--features wireless.
- Source:
crates/eggsec/src/wireless/mod.rs - CLI:
crates/eggsec/src/cli/wireless.rs - Handler/policy:
crates/eggsec/src/commands/handlers/wireless.rs - TUI tab:
crates/eggsec-tui/src/tabs/wireless.rs - Output conversion:
crates/eggsec-output/src/convert.rs - Architecture:
architecture/wireless.md - Agent skill:
.opencode/skills/eggsec-agent/wireless_security_testing.md - Plans: All wireless implementation plans completed — standalone completion, active attacks loadout design, TUI/MCP/agentic integration, CLI integration, and closeout checklist.
Phase 1 deauth/disassoc is now implemented (see "Active Attacks (Phase 1)" above). Full roadmap:
- Phase 2: Handshake capture (PMKID, WPA handshake), WPS PIN enumeration
- Phase 3+: Flood attacks, rogue AP simulation, KRACK-style testing
All active paths require --features wireless-advanced, runtime confirmations/overrides (--allow-active-wireless + reason), packet budgets, and lab-only framing. Reporting bridge extends with wireless-active-* categories. MCP/agent tool exposure remains intentionally absent for the entire wireless surface.
Always ensure explicit authorization. Prefer lab environments for development and regression.
eggsec wireless is a standalone defense-lab surface: passive scanning lives under wireless, and active deauth/disassoc lives under wireless-advanced (CLI and TUI active mode). It emits local WirelessScanResult (with embedded WirelessNetwork list and recommendations) directly for human-readable output and --json.
An optional to_scan_report_data() bridge (in wireless/mod.rs) converts findings (from analyze_networks) + the full networks list into canonical ScanReportData (with wireless_networks: Vec<WirelessNetworkReportData> and findings). This enables SARIF, JUnit, HTML (with networks table), Markdown, CSV, JSON, trend, etc. via eggsec-output.
- Native
--json(or the--repeatwrapped form withlast_scan) is accepted directly byeggsec report convert(auto-bridged in the report handler whenwirelessfeature is present). This fulfills the documented "CI / regression" and "Reporting" flows. - Categories in the bridged findings use consistent
wireless-*naming based on vulnerability type:wireless-roguefor "Possible Rogue AP / Evil Twin (passive heuristic)"wireless-securityfor Open Network / WEP Encryption / WPA Encryptionwireless-wpsfor "WPS Enabled"wireless-hiddenfor "Hidden SSID"wireless-signalfor "Weak Signal Strength"wireless-transitionfor "WPA2/WPA3 Transition Mode"wireless-otherfor Enterprise / Unknown Security / other
- Evidence is populated with network identifier plus channel/signal/security for context (e.g.
network=<ssid> bssid=<bssid> ch=6 sig=-60dBm sec=Open). The compact id prefix is preserved for compatibility. - Remediation is mapped from the vulnerability recommendation.
- The bridge always runs rogue analysis with
analyze_networks(..., None)(known-good suppression is for human/repeat UX + diffs only; bridged findings always include rogue candidates). - Native
--json(directWirelessScanResultor the--repeat > 1wrapped form{ "last_scan": <WirelessScanResult>, "repeat_count": N, "summary": "..." }) is accepted directly byeggsec report convert(auto-bridged in the report handler whenwirelessfeature is present; the bridge is invoked on the innerlast_scanresult for the "last" scan case). The bridge is per-result. - Design decision (standalone completion 2026-06-11): wireless remains intentionally outside the main
ScanProfilepipeline and has no dedicated wireless profiles/stages (aspirational only; seearchitecture/defense_lab.md,architecture/cli_commands.mdSpecial Cases, andarchitecture/wireless.md).
Use the native types (WirelessScanResult / direct --json) for lab-specific wireless workflows, repeated-scan temporal summaries, and --known-good UX. Use the bridge (or report convert on native --json) when you need unified reporting consumers (SARIF/JUnit/HTML/Markdown/CSV/trend/etc.). The integration is lightweight and opt-in. "standalone defense-lab" language is deliberate: wireless is a complete standalone CLI/TUI surface for lab/defense use; passive scanning lives under wireless, active deauth/disassoc under wireless-advanced, and the bridge is only for optional unification of output formats.
This is one of the consolidated "standalone defense-lab surfaces" (wireless + mobile + auth-test). Wireless and mobile provide local types directly + optional to_scan_report_data bridge (auto-bridged by eggsec report convert when the feature is present); auth-test is local-only (no bridge, no conversion). None participate in ScanProfile pipelines or dedicated profiles/stages in this round (aspirational only). See the short shared "Output Models" explanation in docs/USAGE.md (Report Management → Convert Reports), architecture/{wireless,mobile,auth,cli_commands,defense_lab,output}.md, AGENTS.md (standalone defense-lab surfaces note), and CAPABILITIES.md (Lab Defense table). MCP/agent tool exposure is intentionally absent for wireless (see architecture/wireless.md MCP/Agentic section and the handoff plan resolution).
Active wireless results extend the bridge with wireless-active-* findings while preserving the standalone defense-lab + optional bridge model and MCP-absent design.