wifiaudit

Wi-Fi audit toolkit — passive scan, authorized pentest, defense

v1.1.1

Linux

Quick Start

Install via jcli (recommended)

jcli install wifiaudit

Three modes, one binary

# 1. PASSIVE — enumerate visible APs, flag weak crypto
wifiaudit passive scan --iface wlan0

# 2. PENTEST — authorized engagements only
wifiaudit --i-am-authorized pentest handshake --iface wlan0mon \
    --bssid AA:BB:CC:11:22:33 --channel 6 --out ./capture

wifiaudit --i-am-authorized pentest deauth --iface wlan0mon \
    --bssid AA:BB:CC:11:22:33 --client 11:22:33:44:55:66 --count 8

# 3. DEFENSE — rogue / evil-twin detection
wifiaudit defense init --iface wlan0 --out ./watchlist.json
wifiaudit defense scan --iface wlan0 --file ./watchlist.json

What it does

wifiaudit unifies three Wi-Fi audit workflows that normally span different toolchains: iw/nmcli for passive scanning, the aircrack-ng suite + hcxdumptool for authorized pentest capture, and bespoke shell scripting for rogue/evil-twin defense. wifiaudit orchestrates the proven Linux tools, adds parsing, scoring, finding generation, and audit logging — it does not reimplement 802.11 frame handling.

Passive scan. Parses iw dev <if> scan; falls back to nmcli when iw isn't usable. Flags OPEN, WEP, TKIP, mixed WPA/WPA2, WPS-enabled, and hidden SSIDs. JSON output via -o json for pipeline use.
Authorized pentest. Every active subcommand requires --i-am-authorized (or WIFIAUDIT_AUTHORIZED=1) and refuses to act against the host's currently-associated BSSID. All actions append a row to ~/.local/share/wifiaudit/audit.log — proof of scope adherence for engagement docs.
Defense mode. defense init seeds a JSON watchlist from the live RF environment; defense scan diffs a fresh scan, surfacing evil-twins (whitelisted SSID broadcast by an unknown BSSID), cipher regressions, rogue APs from a known vendor OUI, and missing-but-expected APs.
Subprocess-driven, not packet-level. Reimplementing aircrack-ng in Rust would be years of work and leave you with a worse aircrack-ng. wifiaudit is the unified front-end. Operators install the upstream tools via their distro.
Hard fences. Pentest mode refuses without --i-am-authorized; refuses if the target BSSID is the host's currently-associated AP; deauth count is capped at 64 per invocation.

Subcommands

Command	Mode	What it does
`passive scan`	read-only	Enumerate visible APs, score crypto posture
`pentest handshake`	active*	airodump-ng pinned to one BSSID+channel, write .cap
`pentest deauth`	active*	Send up to 64 deauth frames to one client of one BSSID
`pentest pmkid`	active*	hcxdumptool PMKID capture for one BSSID
`defense init`	read-only	Seed a watchlist from the live RF environment
`defense scan`	read-only	Diff a live scan against a watchlist
`doctor`	read-only	Check tool availability + root / monitor-mode posture

* active subcommands require --i-am-authorized or WIFIAUDIT_AUTHORIZED=1.

Defense findings

Finding	Severity	When
`evil_twin`	Critical	A whitelisted SSID is being broadcast by a BSSID the watchlist does not know
`cipher_changed`	Warning	Same SSID+BSSID, but cipher regressed (e.g. WPA2-CCMP → WPA-TKIP)
`rogue`	Warning	Unknown SSID broadcast by a BSSID with the same OUI as a whitelisted AP
`missing`	Info	A whitelisted BSSID is not currently visible

External tool requirements

Run wifiaudit doctor for a host posture report.

Tool	Required for
`iw`	passive scan (preferred backend)
`nmcli`	passive scan (fallback)
`airodump-ng`	`pentest handshake`
`aireplay-ng`	`pentest deauth`
`hcxdumptool`	`pentest pmkid`

Authorization is your responsibility. Active subcommands transmit on the RF spectrum and disrupt service for the targeted devices. Using them against networks you don't own or aren't contracted to test is illegal in most jurisdictions. wifiaudit prints an audit banner and records every active action — present that record alongside your engagement scope.