Wiki / Wireless / Aether-Z

Aether-Z

Wireless v1.5.3 — Multi-phase ZigBee / IEEE 802.15.4 pentest orchestrator — RF survey, network key recovery via join intercept, ZLL touchlink attacks, replay testing, and firmware analysis.
7
Dependencies
6
Phases
15
Catalogue Findings
AETHZ
Finding Prefix

How It Works

⚠️ Authorized Testing Only

This tool interacts with live systems and must only be used for testing that has been explicitly authorized by the asset owner. Unauthorized use of this tool to probe, scan, exploit, or otherwise interact with systems you do not have written permission to test is illegal under computer fraud and abuse laws (CFAA, CMA, and international equivalents). pr0t31n does not condone or recommend any unauthorized use. Always obtain a signed Rules of Engagement (RoE) or Statement of Work (SoW) before beginning any assessment.

Aether-Z is a multi-phase ZigBee and IEEE 802.15.4 penetration testing orchestrator. It automates the assessment of ZigBee-based IoT networks, smart home systems, and industrial control environments through a structured five-phase approach using the KillerBee framework and related ZigBee security tools.

Phase 0 conducts an RF environment survey using zbstumbler and zbfind to discover ZigBee networks, identify active channels, and map PAN IDs and extended PAN IDs in the target environment. Phase 1 targets network key recovery using zbdsniff (passive key sniffing during device joins), zbdump (raw 802.15.4 frame capture), and z3sec (ZigBee 3.0 security testing including key transport interception). Phase 2 performs active enumeration via zbid (device identification), zbscapy (custom frame crafting for protocol probing), and tshark (packet analysis).

Phase 3 executes attack testing including zbreplay (captured frame replay attacks), zbassocflood (association request flooding for denial of service), and zbpanidconflictflood (PAN ID conflict injection to disrupt network operation). Phase 4 performs firmware analysis on ZigBee devices using binwalk (image extraction), goodfet (hardware debug interface for TI CC-series chipsets), and openocd (JTAG/SWD debug access).

Aether-Z integrates with Crucible v2 via __CRUCIBLE_* protocol tokens when CRUCIBLE_MANAGED=1, supporting real-time status tracking, log streaming, and finding emission. It includes pause/resume support and writes findings in the universal pr0t31n schema with wireless-specific metadata fields.

Phase Pipeline

  1. Phase 1 — Survey & Discovery
  2. Phase 2 — Zigbee Network Scanning
  3. Phase 3 — Key Recovery
  4. Phase 4 — Device Enumeration
  5. Phase 5 — Protocol Attacks
  6. Phase 6 — Firmware Analysis

Security

Requires KillerBee-compatible hardware (CC2531 USB dongle or RZUSBstick). CLI tool. Root/sudo may be required for USB device access.

Features

Attack Testing

Frame Replay Attacks
Phase 3: Replays captured ZigBee frames using zbreplay to test whether the network properly rejects replayed commands, particularly for actuator controls (locks, switches, relays).
Association Flood
Phase 3: Floods the ZigBee coordinator with association requests via zbassocflood to test denial-of-service resilience and coordinator stability.
PAN ID Conflict Injection
Phase 3: Injects PAN ID conflict frames via zbpanidconflictflood to disrupt network operation and force coordinator-initiated PAN ID changes.

Capture

Raw 802.15.4 Frame Capture
Captures raw IEEE 802.15.4 frames via zbdump for offline analysis, key recovery, and evidence preservation.

Enumeration

Device Identification
Phase 2: Identifies ZigBee device types, manufacturer codes, and capabilities via zbid, and performs protocol-level probing with zbscapy custom frames.

Firmware

Firmware Extraction & Analysis
Phase 4: Extracts and analyzes ZigBee device firmware using binwalk, goodfet (TI CC-series chipset debug), and openocd (JTAG/SWD) to identify hardcoded keys and vulnerable code.

Integration

Crucible Management
Full Crucible v2 integration via __CRUCIBLE_* protocol tokens for real-time progress tracking, log streaming, and finding emission.

Key Recovery

Network Key Sniffing
Phase 1: Passively captures ZigBee network keys during device join events using zbdsniff, exploiting the key transport mechanism where keys are encrypted with the well-known Trust Center link key.
ZigBee 3.0 Key Testing
Phase 1: Uses z3sec to test ZigBee 3.0 implementations for key exchange vulnerabilities and improper security mode configurations.

RF Survey

ZigBee Network Discovery
Phase 0: Scans all ZigBee channels (11-26) using zbstumbler and zbfind to identify active networks, PAN IDs, extended PAN IDs, and participating devices.

Use Cases

Smart Home ZigBee Assessment

Test ZigBee-based smart home deployments (Philips Hue, SmartThings, etc.) for network key exposure during device pairing, replay attacks on actuator commands, and unauthorized device join capabilities.

Industrial IoT ZigBee Security

Assess ZigBee-based industrial sensor networks for key management weaknesses, ensuring that intercepted keys cannot be used to inject false sensor readings or disable safety controls.

Smart Lock ZigBee Testing

Evaluate ZigBee-enabled door locks for replay attacks on unlock commands, network key interception during provisioning, and resilience to PAN ID conflict disruption.

ZigBee 3.0 Migration Validation

Verify that devices migrated to ZigBee 3.0 properly implement Install Code-based key exchange and are not falling back to insecure legacy key transport mechanisms.

Healthcare IoT ZigBee Assessment

Test ZigBee-based medical device networks for unauthorized access to patient monitoring data, device impersonation, and denial of service against critical alert pathways.

CLI Reference

Command Examples

RF Survey

python3 aether_z.py --phase survey --interface 0

Run Zigbee RF survey on KillerBee device 0.

List Phases

python3 aether_z.py --list-phases

Show available Zigbee assessment phases.

Third-Party Tool Invocations

Commands and flags used when this tool invokes third-party dependencies during operation.

zbstumbler
ZigBee network discovery by scanning channels 11-26 for active PANs, coordinators, and routers
zbstumbler -c 11,15,20,25
zbfind
ZigBee device direction finding and signal strength mapping for physical location
zbfind -c 15 -p 0x1234
zbdsniff
Passive ZigBee network key capture during device join/rejoin events
zbdsniff -c 15
zbdump
Raw IEEE 802.15.4 frame capture to pcap for offline analysis and key recovery
zbdump -c 15 -w capture.pcap
z3sec
ZigBee 3.0 security testing including key exchange analysis and security mode validation
z3sec insecure-rejoin -c 15
zbid
ZigBee device identification including manufacturer code, device type, and capability flags
zbid -c 15
zbscapy
Custom ZigBee frame crafting and injection using Scapy-based protocol manipulation
zbscapy
zbreplay
Replay previously captured ZigBee frames to test network command validation and freshness checking
zbreplay -r capture.pcap -c 15
zbassocflood
ZigBee association request flooding for coordinator denial-of-service testing
zbassocflood -c 15 -p 0x1234
zbpanidconflictflood
PAN ID conflict frame injection to test network resilience against forced PAN ID migrations
zbpanidconflictflood -c 15
binwalk
Firmware image analysis and extraction for ZigBee device flash dumps
binwalk -e firmware.bin
goodfet
Hardware debug interface for Texas Instruments CC-series ZigBee chipsets (CC2530, CC2531, CC2538)
goodfet.cc info
goodfet.cc dump firmware.bin
openocd
JTAG/SWD debug interface for flash memory reads from ZigBee module chipsets
openocd -f interface/jlink.cfg -f target/cc2538.cfg
tshark
ZigBee protocol dissection and analysis of captured 802.15.4 frames
tshark -r capture.pcap -Y zbee_nwk

Finding Nomenclature

Aether-Z findings use the AE- prefix in their catalogue IDs, shared with the Aether wireless family. ZigBee-specific findings include wireless metadata:

  • wireless_data — a dictionary containing ZigBee-specific details (PAN ID, extended PAN ID, channel, network key status, device type, security level)

Risk levels: successful network key recovery is rated CRITICAL; replay attacks that can trigger actuators are HIGH; association flooding and PAN ID conflict vulnerabilities are MEDIUM; informational network discovery results are INFO. Each finding references the specific phase and KillerBee tool that produced it.

Action Items

Aether-Z generates action items for Zigbee-specific follow-up — e.g., "Attempt network key extraction during device re-join", "Test packet replay against discovered coordinator".

Output Files

FileFormatDescription
meta.json JSON Tool identity and engagement metadata
scan.log TXT Human-readable timestamped log
scan.log.json JSONL Machine-readable JSON log events
errors.log TXT ERROR-level entries only
findings_catalogue.json JSON Findings catalogue

Invocation Methods

MethodUsage
CLI — Direct cd /opt/pr0t31n/Aether-Z && python3 aether_z.py

Run directly with command-line arguments.
CLI — Settings File cd /opt/pr0t31n/Aether-Z && python3 aether_z.py --config config.json

Configure via config.json (JSON), then run.
Crucible-Managed

Launched and managed by Crucible (port 5100). Crucible handles start/stop/pause, log streaming, findings aggregation, and status tracking.

Integration

Used By

Third-Party Dependencies & Credits

Tool / LibraryDeveloperTypeLink
KillerBee suite Joshua Wright / River Loop Security system https://github.com/riverloopsec/killerbee
Z3sec Florian Echtler / Fraunhofer SIT system https://github.com/IoTSecurityM/z3sec
tshark / Wireshark Gerald Combs / Wireshark Foundation system https://github.com/wireshark/wireshark
binwalk Craig Heffner / ReFirm Labs system https://github.com/ReFirmLabs/binwalk
OpenOCD OpenOCD project system https://github.com/openocd-org/openocd
goodfet.cc Travis Goodspeed system https://github.com/travisgoodspeed/goodfet
HackRF One (optional SDR) Great Scott Gadgets / Michael Ossmann system https://github.com/greatscottgadgets/hackrf

Metadata

NameAether-Z
CategoryWireless
Version1.5.3
Install Path/opt/pr0t31n/Aether-Z
Main Fileaether_z.py
GitHubhttps://github.com/pr0t31n/Aether-Z.git