==========================================================================================
                          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.
=========================================================================================