wscanPLUS (Wi-Fi Intrusion Detection System)

wscanPLUS is a cross-platform Wi-Fi Intrusion Detection System (WIDS) designed to alert users to common 802.11 wireless attacks including Evil Twin / Karma, Deauthentication floods, PMKID sniffing, and KRACK.

🌐 Project Website (GitHub Pages) · Changelog · Releases

Repository Structure

wscanPLUS/
├── android/          # Android app (Kotlin / Jetpack Compose)
├── windows/          # Windows app (C# / .NET 8 / WinUI 3)
└── docs/             # GitHub Pages landing page

Detected Attack Types

Attack	Detection Method
Evil Twin / Karma	Duplicate SSID with different BSSID / OUI mismatch
Deauth Flood	High-frequency Deauth/Disassoc frame count
PMKID Sniffing	Anomalous EAPOL Auth requests from unassociated MACs
KRACK	Retransmitted Message-3 frames / duplicate nonces

---

Android App

Requirements: Android 10+ · Shizuku (recommended) or root access

Features

• Privileged Wi-Fi scanning via Shizuku (ADB user-space), with a root/tcpdump fallback
• Real-time threat alerts using attack heuristics
• Local Room/SQLite threat log persistence
• Light / Dark Material 3 theme toggle
• Settings screen – Firebase URL, Device ID, Gemini API key, desktop companion host
• AI Analysis screen – Gemini 1.5 Flash natural-language threat assessment
• Companion client – pushes mobile scan results to the Windows desktop relay
• Firebase Realtime Database sync
• Release signing via android/keystore.properties (see keystore.properties.template)

Build

cd android
./gradlew assembleDebug

Signed release build

# 1. Copy android/keystore.properties.template → android/keystore.properties
# 2. Fill in keystore path and passwords
# 3. Run:
./gradlew assembleRelease

---

Windows App

Requirements: Windows 11 · .NET 8 · Npcap · WSL2 (optional)

Features

• Raw packet capture via Npcap / SharpPcap
• Monitor-mode capture through WSL2 + usbipd-win passthrough
• Dependency checker – detects missing prerequisites at startup, provides install links
• Companion relay server – HTTP endpoint (port 9000) for Android companion integration
• OUI database lookup for MAC spoofing detection
• Export to .pcap / .csv (Wireshark-compatible)
• Firebase Realtime Database / Firestore sync
• Gemini AI threat analysis (bring-your-own-key)

Build

cd windows
dotnet build WscanPlus.sln

Run tests

cd windows
dotnet test WscanPlus.Tests/WscanPlus.Tests.csproj

---

Companion Mode (Android ↔ Windows)

When a scan is running on Windows, the app starts a local HTTP relay server on port 9000. The Android app can be pointed at the desktop IP (e.g. 192.168.1.100:9000) via Settings. During each scan cycle the Android app forwards mobile Wi-Fi scan results to the desktop for combined heuristic analysis; the desktop pushes back any high-confidence alerts.

---

Shared Features

• OUI Lookup – local SQLite IEEE OUI database, flags vendor mismatches
• Attack Heuristics – shared detection logic across both platforms
• Data Export – .pcap and .csv serialisation
• Cloud Sync – Firebase Realtime Database / Firestore boilerplate
• AI Analysis – Gemini API integration for natural-language threat assessment

License

CC0 1.0 Universal – see LICENSE