📡 WiFi Audit Tool

Command-Line Wireless Security Auditing Toolkit for Kali Linux

---

📖 Table of Contents

• Overview
• ⚠️ Authorization Requirement
• Core Features
• Project Architecture
• Dependencies
• Installation
• Usage — Basic
• Usage — Advanced
• Configuration
• Feature Deep Dive
• Example Authorized Workflow
• Hardware Requirements
• Testing
• Troubleshooting
• Contributing
• Author
• License

---

🧭 Overview

WiFi Audit Tool is a command-line wireless security toolkit built for Kali Linux environments. It wraps the standard aircrack-ng suite in a guided, menu-driven workflow — and layers structured scan output, offline vendor identification, historical tracking, and multi-format reporting on top, so an authorized wireless assessment produces a real audit trail instead of just terminal scrollback.

It's built for two audiences at once:

Audience	How they use it
🟢 Beginners	Guided interactive menu — no flags to memorize
🔵 Advanced users	Non-interactive CLI flags for scripting, cron jobs, and CI pipelines

---

⚠️ Authorization Requirement

This tool is intended strictly for authorized security testing.

Running scans or capture operations against networks without explicit written permission may violate laws and regulations in your jurisdiction. The author and contributors are not responsible for misuse or resulting damage.

✅ Allowed use cases:

• Networks you own
• Networks you are contracted / engaged to test
• Controlled lab environments

❌ Not allowed:

• Any network you don't have explicit written permission to test

---

🚀 Core Features

	Automatically enables and disables monitor mode on the selected wireless adapter.
	Timed scans parsed into structured data (BSSID, ESSID, channel, privacy, power) — not just raw terminal output.
	Offline BSSID → manufacturer identification via OUI prefix. No internet required in the field.
	Rule-based classifier flags open networks, WEP, WPA (non-WPA2/3), and WPA2+WPS as HIGH/MEDIUM risk with plain-language explanations.
	Every scan is logged to a local JSONL history file — track a network's security posture over time.
	Diff two scans to see what's new, what disappeared, and whether any network's security got weaker or stronger.
	Export any scan/report as JSON, HTML (styled), or CSV (spreadsheet-ready).
	Targets a selected BSSID and channel to capture WPA/WPA2 handshakes.
	Generates ready-to-run `aircrack-ng` cracking commands for offline analysis.
	Fully non-interactive mode for cron jobs, CI pipelines, or scripted audits.
	Save default interface, scan duration, and export format so you stop retyping the same flags.

---

🏗 Project Architecture

wifi-audit-tool/
│
├── wifi_audit.py              # Entry point — interactive menu + argparse CLI
│
├── modules/
│   ├── scan.py                 # airodump-ng wrapper + CSV output parsing
│   ├── handshake.py             # WPA/WPA2 handshake capture
│   ├── report.py                 # JSON / HTML / CSV export + crack-command generator
│   ├── history.py                 # Persistent JSONL scan history
│   └── compare.py                  # Scan-to-scan diffing engine
│
├── utils/
│   ├── helpers.py               # Colorized output (colorama) + validated input prompts
│   ├── ai_helper.py              # Rule-based network security classifier
│   ├── vendor.py                  # Offline BSSID → vendor (OUI) lookup
│   └── config.py                   # Local defaults file (JSON)
│
├── tests/                       # pytest suite — 42 tests across every module above
│   └── fixtures/                 # Sample airodump-ng CSV fixtures for parser tests
│
├── .github/workflows/            # CI: pytest + flake8 on every push
├── install.sh                     # Dependency installer (PEP 668 safe)
└── requirements.txt

---

📦 Dependencies

Dependency	Purpose
Python 3.8+	Runtime
aircrack-ng suite	airodump-ng, aireplay-ng — scanning & capture
iw	Interface / monitor-mode management
iproute2	Interface up/down control
colorama	Cross-platform colored terminal output
Kali Linux (or compatible)	Target OS

---

⚙️ Installation

Clone the repository

git clone https://github.com/trmxvibs/wifi-audit-tool.git
cd wifi-audit-tool

Make the installer executable

chmod +x install.sh

Run the installer

./install.sh

This installs aircrack-ng, python3-pip, and the Python dependencies in requirements.txt. It uses --break-system-packages for the pip install — required on modern Kali/Debian (PEP 668) since this tool runs as root alongside aircrack-ng rather than in an isolated virtualenv.

---

🟢 Usage — Basic (Interactive Mode)

Run with root privileges:

sudo python3 wifi_audit.py

You'll get a guided menu:

==== WiFi Auditing Tool (Kali Edition) ====
1)  Scan WiFi Networks (live view)
2)  Timed Scan + Security Analysis (structured, with vendor lookup)
3)  Capture Handshake
4)  Vulnerability Report / Crack
5)  Scan History (from disk, persists across runs)
6)  Export Last Scan Report (JSON/HTML/CSV)
7)  Compare Last Scan to Previous Scan
8)  Configure Defaults (interface, scan duration, export format)
9)  Guidelines & Help
10) Exit

Just follow the prompts — adapter selection, scan duration, and file paths are all asked interactively.

---

🔵 Usage — Advanced (Scripted / Automation Mode)

Skip the menu entirely for automation, cron jobs, or CI-driven audits:

sudo python3 wifi_audit.py --scan-duration 30 --iface wlan0mon --export report.json

Flag	Type	Description
--scan-duration SECONDS	int	Runs a timed scan, analyzes it, then exits. Omit for interactive menu.
--iface IFACE	string	Wireless interface to use. Defaults to first detected interface.
--export PATH	path	Export destination. Format inferred from extension: .json, .html, .csv.

Example — daily cron audit:

# /etc/cron.daily/wifi-audit
sudo python3 /opt/wifi-audit-tool/wifi_audit.py \
  --iface wlan0mon \
  --scan-duration 60 \
  --export /var/log/wifi-audit/$(date +%F).json

Every scan — interactive or scripted — is automatically logged to scan_history.jsonl, so Compare Last Scan to Previous Scan works regardless of which mode you used.

---

⚙️ Configuration

Set your own defaults once (interactive menu, option 8) so you don't have to retype flags:

{
  "iface": "wlan0mon",
  "scan_duration": 60,
  "export_format": "csv",
  "history_path": "scan_history.jsonl"
}

Stored in .wifi_audit_config.json in your working directory. CLI flags always override the config file when both are given.

---

🔬 Feature Deep Dive

📡 Structured Scanning

airodump-ng output is parsed directly from its CSV export into clean Python dicts — bssid, essid, channel, privacy, cipher, authentication, power — ready for analysis, export, or scripting.

🏷 Offline Vendor Lookup

Every BSSID is matched against its OUI (organizationally unique identifier) prefix to reveal the manufacturer — TP-Link, Netgear, Cisco, Ubiquiti, and more — entirely offline.

🛡 Security Classifier

Not machine learning — a transparent, auditable rule set:

Privacy	Severity	Reason
Open (OPN)	🔴 HIGH	No encryption — traffic readable by anyone nearby
WEP	🔴 HIGH	Broken since ~2005, crackable in minutes
WPA (non-WPA2/3)	🟠 MEDIUM	Vulnerable to known TKIP attacks
WPA2 + WPS	🟠 MEDIUM	WPS PIN attacks may apply
WPA2 / WPA3	✅ Clean	No issues flagged

🕰 Scan History & Comparison

Every scan is appended to scan_history.jsonl. The Compare feature diffs your latest scan against the previous one:

[NEW] NewNeighborWifi (DE:AD:BE:EF:00:01)
[GONE] FreeWiFi (AA:BB:CC:DD:EE:FF)
[CHANGED] HomeNetwork (00:11:22:33:44:55): WPA2 -> WEP (WEAKER)

📤 Multi-Format Export

Format	Best for
JSON	Programmatic processing, archiving
HTML	Human-readable report, client hand-off (XSS-safe, escaped output)
CSV	Spreadsheet analysis, filtering, sorting

---

🧪 Example Authorized Workflow

1. Run a timed scan against your lab network (option 2)
2. Review flagged findings — open networks and WEP show as HIGH severity
3. Export the report (option 6) to archive or hand off
4. A week later, scan again and use Compare (option 7) — catch a network that quietly dropped from WPA2 to open
5. For deeper analysis, capture the target's handshake (option 3) and generate the offline crack command (option 4)

---

🔧 Hardware Requirements

Most built-in laptop WiFi chipsets don't support monitor mode, and phone-hosted Kali (Termux/NetHunter) generally can't access the internal chipset at all.

You need:

• A USB WiFi adapter with a monitor-mode-capable chipset
• An OTG adapter, if running from a phone

Supported chipsets (tested):

• Atheros AR9271
• Ralink RT5370

✅ Recommended environments:

• Native Kali Linux
• Kali Live USB
• Kali VM with USB passthrough
• Dedicated test adapter

---

✅ Testing

pip install -r requirements.txt --break-system-packages
PYTHONPATH=. pytest -v

CI runs this full suite plus flake8 on every push via GitHub Actions — badge at the top of this README reflects live status.

Test file	Covers
test_scan.py, test_scan_parsing.py	airodump-ng wrapper + CSV parsing
test_ai_helper.py	Security severity classification
test_vendor.py	OUI vendor lookup
test_history.py	JSONL scan history persistence
test_compare.py	Scan diffing logic
test_config.py	Config load/save/defaults
test_report_export.py	JSON/HTML/CSV export, XSS-safety
test_utils.py	Colorized output helpers

---

🩹 Troubleshooting

❌ Error: No Interfaces Detected

Error detecting interfaces: Command ['iw', 'dev'] returned non-zero exit status 1

Cause: Occurs when running Kali inside Android/Termux or NetHunter guest mode — the host OS blocks direct access to the internal WiFi chipset.

Fix: Use an external USB adapter (see Hardware Requirements).

❌ pip install fails with "externally-managed-environment"

This is expected on modern Kali/Debian (PEP 668). install.sh already handles this with --break-system-packages. If installing manually, add the same flag.

❌ Monitor mode fails to enable

Try:

rfkill unblock wifi

then re-run the tool.

---

🤝 Contributing

Pull requests, issue reports, and security improvement suggestions are welcome. For significant changes, please open an issue first to discuss the proposal.

---

👤 Author

Independent security enthusiast focused on wireless security testing, Kali Linux tooling, and practical command-line automation.

---

📄 License

Licensed under the terms in LICENSE.

---

_{Built for authorized security testing. Use responsibly. 🛡️}