Wireless Assessment

Overview

PortShim's wireless assessment pipeline lets you discover nearby access points, select targets, and assess their current status — all without switching to monitor mode. This means you can survey the RF environment while keeping your own network connection active.

For active attacks (handshake capture, deauthentication, cracking), monitor mode is required and the network disruption guard will warn you before proceeding.

Pipeline

Green = implemented. All six phases are available now.

Phase 1 — Scan

Discover nearby access points with portshim wireless scan. An external USB WiFi adapter is required — internal WiFi is never used. The command auto-detects your external adapter, checks its capabilities (monitor mode, band support), and runs the best available scan.

Full mode (monitor)

With an external USB adapter, PortShim uses full airodump-ng with monitor mode and packet injection for the most detailed AP data. No network disruption — your internal WiFi handles connectivity while the external adapter does the scanning.

Examples

# Quick scan (requires external USB adapter)
portshim wireless scan

# 30-second scan on 5 GHz band
portshim wireless scan --duration 30 --band 5

# Force full monitor mode (drops network)
portshim wireless scan --force

# Dry run — check hardware without scanning
portshim wireless scan --dry-run

Output

Structured JSON is saved to outputs/wireless/wireless-aps-{timestamp}.json with scan metadata and a sorted list of access points by signal strength. Each AP includes SSID, BSSID, channel, encryption type, signal (dBm), and manufacturer info.

Field	Description
scan_metadata	Timestamp, interface, tool, mode (full/managed), band, duration
access_points[]	Array of APs with SSID, BSSID, channel, encryption, signal_dbm, beacons, manufacturer

Phase 2 — Select

After scanning, pick which APs to target with portshim wireless select. The command loads the most recent scan results and presents a numbered table sorted by signal strength.

Interactive mode

portshim wireless select

Shows a numbered list of all detected APs. Enter selections like 1,3-5,7 or all to pick targets. Selection is saved to outputs/wireless/targets-{timestamp}.json.

Auto-select (agent-friendly)

# Auto-select top 5 strongest APs (prefers unique SSIDs)
portshim wireless select --auto

# Top 3, agent-friendly
portshim wireless select --force --max 3

# Just list, don't save
portshim wireless select --list

Phase 3 — Assess

With targets selected, run portshim wireless assess to check their current status via a fresh managed-mode scan. No network disruption required.

What it reports

• Visibility — Is the target still in range?
• Signal change — How much has the signal changed since the scan?
• Channel match — Has the AP moved channels?
• Encryption match — Has the encryption type changed?
• Association — Are you currently connected to this AP?

# Assess latest targets (fresh iw scan)
portshim wireless assess

# Use a specific targets file
portshim wireless assess --targets-file outputs/wireless/targets-20260706T103000Z.json

# No fresh scan — use cached data only
portshim wireless assess --no-scan

Assessment output

═══ Assessment Results ═══
  3 targets — 2 visible, 1 invisible, 1 associated

  ◉ TESTAP  E2:62:79:B3:48:83
    Signal:  -68 dBm ( -2)
    Channel: 36
    Enc:     WPA3-SAE

  ○ TESTAP_EXT  D8:32:14:0C:5B:64
    Signal:  -32 dBm ( -2)
    Channel: 6
    Enc:     WPA2-PSK

  ✗ OPTUS_0593B0N  8C:83:94:05:93:B3
    Target not visible in current scan
    Last seen on ch 11 at -78 dBm

Phase 4 — Capture

Once targets are selected and assessed, capture WPA/WPA2/WPA3 handshakes with portshim wireless capture. Requires monitor mode — you need a dedicated external USB adapter.

How it works

• Auto-detects your wireless adapter and checks monitor mode support
• Targets all selected APs simultaneously via airodump-ng
• Waits for clients to authenticate — deauth can speed this up (Phase 6)
• Saves capture to outputs/wireless/capture-{timestamp}-01.cap
• Produces a structured JSON result with status, target count, and file metadata

Examples

# Capture handshakes from latest targets (60s default)
portshim wireless capture

# 2-minute capture on a specific interface
portshim wireless capture --duration 120 --interface wlan1

# Use a specific targets file
portshim wireless capture --targets-file outputs/wireless/targets-20260708T150400Z.json

# Dry run — show plan without capturing
portshim wireless capture --dry-run

Phase 5 — Crack

Attempt offline PSK recovery from captured handshakes with portshim wireless crack. Uses aircrack-ng by default with hashcat as an optional GPU-accelerated backend.

Backends

• aircrack-ng (default) — CPU-based, always available, good for small wordlists
• hashcat — GPU-accelerated (AMD/Intel/NVIDIA), requires OpenCL or ROCm
• auto — selects hashcat if GPU detected, falls back to aircrack-ng

Examples

# Crack with default system wordlist
portshim wireless crack --cap outputs/wireless/capture-20260708T150500Z-01.cap

# Custom wordlist
portshim wireless crack --cap capture.cap --wordlist /usr/share/wordlists/rockyou.txt

# GPU-accelerated via hashcat
portshim wireless crack --cap capture.cap --backend hashcat

# 10-minute timeout
portshim wireless crack --cap capture.cap --timeout 600

Output

Saves structured JSON to outputs/wireless/crack-result-{timestamp}.json with the cracking outcome (success/failure/timeout), recovered PSK, target details, and backend used.

Phase 6 — Deauth

Force clients to disconnect from target APs with portshim wireless deauth. This triggers reconnection and re-authentication, producing fresh WPA handshakes for capture. Uses aireplay-ng to send deauthentication frames.

Modes

• Broadcast deauth — Kick all clients from all selected targets
• Targeted deauth — --detect-clients first discovers associated clients, then deauths them specifically
• Dry run — --dry-run shows the plan without sending any frames

Examples

# Deauth clients from latest targets (interactive)
portshim wireless deauth

# Deauth with client discovery first
portshim wireless deauth --detect-clients

# Send 10 deauth frames per target
portshim wireless deauth --count 10

# Agent-friendly (skip all prompts)
portshim wireless deauth --force

# Show plan only
portshim wireless deauth --dry-run

Output

Saves structured JSON to outputs/wireless/deauth-result-{timestamp}.json with per-target client counts, interface used, and deauth count.

Network Disruption Guard

PortShim's wireless pipeline is designed to never surprise you with a dropped connection. Here's how it works:

• External only — All wireless operations require an external USB adapter. Internal WiFi is never touched.
• --force override — Skip interactive prompts for agent-friendly automation.
• Interface restoration — After any monitor mode operation, PortShim restores the interface to managed mode, unblocks NetworkManager, and attempts to reconnect to your Wi-Fi network.
• Agent-friendly — All prompts are skipped with --force, making the pipeline safe for AI-agent orchestration.

Hardware Requirements

An external USB WiFi adapter is required. Internal laptop Wi-Fi adapters are never used — PortShim exits with a clear error if no external adapter is detected. This prevents accidental network disruption during testing.

Recommended adapter:

An external adapter appears as a second wireless interface (e.g. wlan1). PortShim requires an external adapter and uses it for full-mode scanning without disrupting your network connection on wlan0.

Agent Integration

The entire wireless pipeline is agent-friendly. It works with Hermes Agent, Claude Code, Codex, or any CLI-capable AI assistant. The --force flag skips all interactive prompts, allowing an agent to run the full scan → select → assess workflow autonomously while reporting status at each step.

Since internal WiFi is never used, an agent can safely run wireless operations without risk of dropping the host's network connection.