WiFi Discovery

scripts/discover_wifi.sh enumerates nearby 802.11 access points (SSID, BSSID, channel, signal, and encryption) into session findings. It is an opt-in, standalone module: it is not part of the default recon or scan pipeline, and it runs on Linux only.

By default it uses non-disruptive managed-mode scanning through NetworkManager (nmcli) or iw. Monitor-mode capture is a separate, best-effort opt-in that requires a monitor-capable adapter and the aircrack-ng toolchain.

WARNING

Only scan wireless networks you own or are explicitly authorized to assess. Wireless enumeration is subject to local law and engagement scope.

Platform and Dependencies

Requirement	Purpose
Linux	The module skips gracefully on macOS and other platforms
nmcli or iw	Managed-mode scanning backend (at least one is required)
jq	Writing the strictly-valid results JSON
rfkill, ip (run as root)	Best-effort unblocking of the radio and bringing the interface up
aircrack-ng (airodump-ng)	Only for the optional --monitor mode

Install the managed-mode backends on Debian/Raspberry Pi:

sudo apt-get install -y network-manager   # provides nmcli
sudo apt-get install -y iw
# Optional, for monitor mode only:
sudo apt-get install -y aircrack-ng

If neither nmcli nor iw is present, the module prints a warning and skips. See Installation and Raspberry Pi for platform setup.

Standalone Usage

# Managed-mode scan on wlan0 (writes findings into session.json)
./scripts/discover_wifi.sh session.json wlan0

# Best-effort monitor-mode capture (needs a monitor-capable adapter + aircrack-ng)
./scripts/discover_wifi.sh session.json wlan0 --monitor

Arguments:

• session_json: path to a session JSON file. If the file does not exist, the script creates a fresh session for you (standalone convenience).
• interface: the wireless interface to scan (for example wlan0). The script validates that it is a real wireless interface via Linux sysfs before scanning.
• --monitor (optional): request monitor-mode capture. Where monitor mode is unsupported, it falls back to a managed scan.

Run as root to let the module unblock the radio (rfkill unblock wifi) and bring the interface up automatically. Without root, it assumes the interface is already up.

As a Library

The module can also be sourced and driven directly:

source scripts/discover_wifi.sh
run_wifi_discovery "/path/to/session.json" "wlan0" managed   # or: monitor

Scanning Backends

The module selects a backend automatically, preferring nmcli:

Backend	Command	Signal unit
nmcli (preferred)	nmcli -t -f SSID,BSSID,CHAN,SIGNAL,SECURITY dev wifi list ifname <iface> --rescan yes	link-quality percentage (0-100, tagged %)
iw	iw dev <iface> scan (needs root)	signal level in dBm (tagged dBm)

Each access point is normalized to BSSID / SSID / channel / signal / security, and the signal value is rendered with the correct unit per backend.

Findings and Severity

The module emits one finding per discovered access point, plus a final summary finding recording how many networks were seen.

Security	Severity	Rationale
open / none / WEP	high	Unencrypted or weakly-encrypted network; confirm ownership, migrate to WPA2/WPA3, or decommission
WPA / WPA2 / WPA3 / RSN / 802.1x	info	Encrypted network observed; verify it is authorized

Findings are added to the session with category wifi and module discover_wifi, so they flow through aggregation, scoring, and the HTML report like any other finding.

Output Files

Both files are written into the session directory (alongside session.json) with secure permissions:

File	Contents
wifi_scan_results.json	Strictly-valid JSON: interface, timestamp, and a networks array (bssid, ssid, channel, signal, security, signal_unit)
wifi_discovery.txt	Raw scan log and normalized records (mode 600)

Example wifi_scan_results.json:

{
  "interface": "wlan0",
  "timestamp": "2026-07-18T14:30:00Z",
  "networks": [
    {
      "bssid": "AA:BB:CC:DD:EE:FF",
      "ssid": "corp-guest",
      "channel": "6",
      "signal": "72",
      "security": "WPA2",
      "signal_unit": "%"
    },
    {
      "bssid": "11:22:33:44:55:66",
      "ssid": "<hidden>",
      "channel": "36",
      "signal": "-58",
      "security": "open",
      "signal_unit": "dBm"
    }
  ]
}

Hidden SSIDs are recorded as <hidden>, and a missing security value is treated as open. The session data model is documented in Session Data.

Notes

• This module is deliberately excluded from the recon and scan pipeline, so a standard scan never touches the wireless radio. Invoke it explicitly when wireless assessment is in scope.
• Monitor mode is a guarded, best-effort feature. It is off by default and safe to leave unused; managed-mode scanning covers most AP-inventory needs without disrupting the adapter.
• For the standard, wired reconnaissance workflow, see the Reconnaissance Guide.