========================================================================================== CYD WIFI NETWORKS SENTINEL SYSTEM DOCUMENTATION ========================================================================================= Sentinel is an advanced 2.4 GHz 802.11b/g/n tactical packet sniffer, perimeter AP sentry, threat detection system, and direction-finding instrument built for the ESP32 Cheap Yellow Display (CYD / ESP32-2432S028R) with integrated MicroSD storage. The user interface provides 10 dedicated pages [Page 0 to Page 9], navigatable via on-screen touch controls and a centralized Command Hub menu. ----------------------------------------------------------------------------------------- BOOT INITIALIZATION & TIME ENGINE ----------------------------------------------------------------------------------------- At boot, Sentinel enters Wi-Fi Station mode using credentials from /config.txt to perform an active SNTP time synchronization across a 6-server pool (pool.ntp.org, time.nist.gov, time.google.com, time.windows.com, time.aws.com, time.cloudflare.com). Upon a successful sync, the epoch timestamp is persisted to /time.txt on the MicroSD card. The Wi-Fi client stack is then deactivated, and the hardware promiscuous sniffer engine is engaged. ----------------------------------------------------------------------------------------- PAGE 0: Sentinel Command Hub ----------------------------------------------------------------------------------------- The central operational dashboard featuring: - 8-Button Fast Launcher: Direct touch navigation to Pages 1 through 8. - Live Header Clock: Two-tone real-time display (Cyan labels, Yellow dynamic values) showing current EDT time and calendar date. - System Telemetry Shortcut: A centered version button linking directly to Page 9. ----------------------------------------------------------------------------------------- PAGE 1 [Page 1 of 8]: Sentry Matrix (Perimeter AP Survey) ----------------------------------------------------------------------------------------- Performs active and passive sweeps of nearby Access Points, displaying the top 7 detected networks sorted by RSSI strength: - Tracks SSID, RSSI (dBm), Channel (CH), and Security type (OPEN, WPA2, MIXD, WEP). - Evil Twin / Rogue AP Detection: Flags unauthorized clones of your configured home SSID or rogue OPEN networks in prominent RED. - Periodic Logging: Appends surveys to /_sentry_YYYY-MM-DD.txt on the MicroSD card. ----------------------------------------------------------------------------------------- PAGE 2 [Page 2 of 8]: Traffic & Ambient Vendors ----------------------------------------------------------------------------------------- Combines real-time 2.4 GHz spectrum analysis with an ambient vendor scoreboard: - 13-Channel Density Bar Chart: Auto-scaling histogram showing packet activity across Channels 1 through 13. Tapping any channel bar instantly retunes the sniffer radio. - 6-Vendor Scoreboard: Accumulates packet volume for up to 5 custom vendors defined in /vendors.txt plus an "Others" category. - Vendor Node Inspector Modal: Tapping a vendor row opens a stationary overlay detailing individual MAC addresses, packet tallies, and last-seen RSSI. Selecting any node locks its MAC and immediately transitions to Page 3. ----------------------------------------------------------------------------------------- PAGE 3 [Page 3 of 8]: Geiger Radar Locator (Proximity DF) ----------------------------------------------------------------------------------------- Provides real-time radio direction-finding (DF) on a locked target MAC address: - Multi-Frame Interception: Tracks both 802.11 Management frames and active Data packets. - Variable Pitch & Audio Click Rate: Proximity buzzer scales dynamically from low-frequency clicks at -95 dBm up to 3500 Hz rapid acoustic feedback at close range. - Proportional RSSI Meter: Visual signal strength bar color-coded Green/Yellow/Red. - Inactivity Decay: Automatically resets the meter if the target remains silent for > 90s. - Controls: Dedicated touch buttons to toggle Audio (MUTE / ON) and RELEASE target lock. ----------------------------------------------------------------------------------------- PAGE 4 [Page 4 of 8]: Radio Frame Telemetry ----------------------------------------------------------------------------------------- Comprehensive promiscuous bandwidth and threat analytics: - Segmented Counters: Real-time packet counts for Management (MGMT), Control (CTRL), and Data (DATA) frames formatted compactly (e.g., 2.8M, 458k). - Congestion Rates: Displays live Packets Per Second (PPS) and Probes/Sec. - Attack & EAPOL Indicators: Dedicated live counters for DEAUTH frames and 802.1X / EAPOL authentication handshakes (M1–M4). - Management Subtype Matrix Modal: Tapping MGMT opens a complete 802.11 subtype matrix (Beacons, Probes, Auth, Deauth, Disassoc) with sortable counts and node drill-down. ----------------------------------------------------------------------------------------- PAGE 5 [Page 5 of 8]: Attack & Disconnect Matrix ----------------------------------------------------------------------------------------- Monitors perimeter attack vectors by logging active Deauthentication (DEAUTH) and Disassociation (DISASSOC) frames: - Offender Table: Maps Sender MAC -> Target (DST) MAC, attack type, and frame count. - Threat Inspection Modal: Tapping any incident freezes the transaction data. - Instant Intercept: Includes a [ LOCK ONLY ] button and a [ LOCK+RADAR ] button to pass the attacker's MAC address directly to the Geiger Radar on Page 3. - Attack Logging: Appends threat events to /_attack_YYYY-MM-DD.txt on the MicroSD card. ----------------------------------------------------------------------------------------- PAGE 6 [Page 6 of 8]: Busiest Vendors Leaderboard ----------------------------------------------------------------------------------------- High-density leaderboard profiling ambient manufacturers: - Top 10 Stack: Ranks top 10 hardware vendors by packet count and RF market share percentage. - Unknown OUI Telemetry: Reports the most active unmapped OUI prefix and total hits. - Auto-Refresh: Automatically recalculates and updates statistics every 30 seconds. - Direct Drill-Down: Tapping any vendor row populates and switches to Page 7. ----------------------------------------------------------------------------------------- PAGE 7 [Page 7 of 8]: Vendor Node Explorer ----------------------------------------------------------------------------------------- Deep inspection view of all distinct MAC nodes captured for the selected vendor: - 10-Node Paged Display: Displays nodes sorted by packet volume with ^ / v pagination controls. - Node Inspector Modal: Tapping a node reveals its friendly alias, manufacturer, packet hits, last-seen RSSI, and operating channel, with a direct [ LOCK GEIGER RADAR ] action. ----------------------------------------------------------------------------------------- PAGE 8 [Page 8 of 8]: Live Probes Tracker ----------------------------------------------------------------------------------------- Real-time capture feed of Wi-Fi client probe requests: - Displays transmitter MAC, resolved vendor, requested SSID / asset, and signal RSSI. - Lock Probe Radar: A dedicated button instantly locks the probe MAC as the active target and jumps to Page 3. - Probe Logging: Appends captured requests to /_probe_YYYY-MM-DD.txt on the MicroSD card. ----------------------------------------------------------------------------------------- PAGE 9 [Page 9 of 9]: System Telemetry & Hardware Diagnostics ----------------------------------------------------------------------------------------- Low-level operating metrics accessible via the Page 0 version button: - Uptime Counter: Formatted in days, hours, and minutes. - Memory: Free SRAM heap vs total heap size with percentage. - MicroSD Capacity: Calculated and displayed in integer Gigabytes (GB). - Network Configuration: Hardware MAC, Station IP (DHCP or Static), Active Monitor Channel. - Database Metrics: Total active OUI RAM cache entries and friendly aliases loaded. ----------------------------------------------------------------------------------------- MICROSD FILE STRUCTURE & OFFLINE TOOLCHAIN ----------------------------------------------------------------------------------------- Configuration Files: - /config.txt: Runtime settings (SSID, PASS, DHCP, IP parameters, Sentinel channel, Target MAC). - /vendors.txt: Up to 5 custom scoreboard vendor names for Page 2. - /aliases.txt: Up to 64 custom MAC-to-Friendly-Name mappings (e.g., MAC, FriendlyName). - /oui.txt: OUI database preloaded directly into RAM cache for fast lookup. Daily Log Files (Grouped with leading underscore): - /_attack_YYYY-MM-DD.txt: Recorded deauthentication and disassociation threats. - /_probe_YYYY-MM-DD.txt: Logged client probe requests. - /_sentry_YYYY-MM-DD.txt: AP perimeter survey snapshots. - /_handshake_YYYY-MM-DD.pcap: Captured raw 802.11 EAPOL 4-way handshakes. Offline Utilities: - /unknown_ouis.txt: Automatically logs unrecognized OUI prefixes during operation. - resolve_ouis.py: PC-based Python script to resolve unknown OUIs and update /oui.txt. - dedupe_MAC.py / dedupe_Vendor.py: Clean, sort, and optimize the /oui.txt database. =========================================================================================