N-I-S (Network Intrusion Scanner)

Category: Embedded Systems / Cybersecurity / Wireless Network Security
Platform: LilyGO T-Display-S3 (ESP32-S3)
Framework: Arduino via PlatformIO | C++
Status: Active — Production Ready

---

Project Overview

N-I-S (Network Intrusion Scanner) is a compact, standalone wireless network security scanner and deauthentication attack detector built on the LilyGO T-Display-S3. It operates in promiscuous (monitor) mode — without joining any WiFi network — and passively analyses all 802.11 (WiFi) frames on the 2.4 GHz spectrum to track active devices and detect ongoing deauthentication (deauth) attacks in real time.

The device is designed for network security professionals, home lab enthusiasts, and anyone who wants a dedicated, always-on tool that silently monitors their wireless environment and raises an alert when hostile activity is detected.

---

Core Features

Passive WiFi Promiscuous Monitoring

• Uses the ESP32-S3's native WiFi radio in raw promiscuous mode (esp_wifi_set_promiscuous)
• Captures all 802.11 frames visible in the air — data frames, management frames, and control frames
• Does NOT transmit any WiFi frames or join any network
• Completely passive and undetectable to other devices

Automatic Channel Hopping

• Cycles through channels 1 through 11 (2.4 GHz band) every 250ms
• Ensures comprehensive coverage of the entire 2.4 GHz spectrum
• Current channel displayed live on the AIRSPACE SCANNER header bar
• Serial monitor logs a sweep completion summary after each full 11-channel cycle

MAC Address Tracking

• Extracts source MAC addresses (Addr2 field at frame offset 10) from:
  • Probe Request management frames (devices actively searching for networks)
  • Data frames (devices actively transmitting data)
• Maintains a real-time table of up to 500 unique MAC addresses
• Active MACs are those seen within the last 5 seconds (rolling 5-second window)
• Thread-safe MAC table access via portMUX critical sections (ISR-safe)
• In-place pruning algorithm removes stale entries without memory reallocation
• New MAC addresses are logged to the serial monitor in real time

Deauthentication Attack Detection

• Monitors for 802.11 Deauthentication frames (subtype 0x0C) and Disassociation frames (subtype 0x0A)
• Counts deauth/disassoc packets within a rolling 3-second window
• Threshold: If more than 15 deauth packets are detected within 3 seconds, a DEAUTH ATTACK DETECTED alert fires
• Alert behaviour:
  • Screen flashes solid red full-screen
  • Large white warning text: "DEAUTH ATTACK / DETECTED"
  • Alert state is frozen for 5 seconds (prevents flickering)
  • After 5 seconds, normal scanning resumes and counters reset

Real-Time Statistics Display

The main scanning UI shows two live statistics panels:

Panel	Metric	Description
Left	Active MACs	Unique devices seen in last 5 seconds
Right	Deauths	Cumulative deauthentication frame count since boot

Both panels update every 250ms (on each channel hop).

Header Bar

• Cyan status bar at top of display showing: AIRSPACE SCANNER - CH [current channel]
• Updates with each channel hop to show the actively monitored channel

---

Frame Analysis

The sniffer callback (sniffer_callback) parses raw 802.11 frame control fields:

Frame Control Word (16-bit):
  Bits 2-3: Frame Type    (0x00=Management, 0x02=Data)
  Bits 4-7: Frame Subtype

Management Subtypes Tracked:
  0x04: Probe Request      -> MAC tracking
  0x0A: Disassociation     -> Deauth counter
  0x0C: Deauthentication   -> Deauth counter

Data Frames:
  Any data frame           -> MAC tracking (Addr2 = source MAC at offset 10)

Frames shorter than 24 bytes are discarded (insufficient header data).

---

Technical Architecture

Component	Detail
MCU	ESP32-S3 @ 240 MHz
Display	ST7789 IPS — 320x170 pixels (landscape)
Display Library	TFT_eSPI (8-bit parallel i8080 interface)
WiFi Mode	WIFI_STA disconnected — raw promiscuous mode
Promiscuous API	esp_wifi_set_promiscuous + esp_wifi_set_promiscuous_rx_cb
Channel Control	esp_wifi_set_channel (timer-driven hopping)
MAC Store	Static array of 500 MacRecord structs
Thread Safety	portMUX_TYPE critical sections for ISR-safe MAC access
Serial Output	115200 baud real-time event logging

---

Hardware Configuration (T-Display S3)

Pin	GPIO	Function
Display Power	15	Must be HIGH for screen power
Backlight	38	PWM backlight (HIGH = on)
TFT Interface	Parallel 8-bit	D0=39, D1=40, D2=41, D3=42, D4=45, D5=46, D6=47, D7=48
TFT Control	CS=6, DC=7, RST=5, WR=8, RD=9	ST7789 control lines

---

Operational Behaviour

Normal Scanning State

1. Radio placed in promiscuous mode on channel 1
2. Every 250ms: channel advances (1→2→...→11→1)
3. Each captured frame triggers sniffer_callback in ISR context
4. MAC addresses are extracted and tracked
5. Deauth/disassoc frames increment counters
6. UI updates with current active MAC count and cumulative deauth count

Alert State (Deauth Attack Detected)

1. Alert condition: deauthCount > 15 within 3-second window
2. Screen clears and fills red
3. Attack warning text rendered in white
4. Alert frozen for 5 seconds (prevents re-triggering on burst traffic)
5. After 5 seconds: deauthCount reset, normal scan resumes, UI redraws

Serial Monitor Output

[NEW MAC] AA:BB:CC:DD:EE:FF
[NEW MAC] 11:22:33:44:55:66
--- SWEEP COMPLETE | Active MACs: 12 | Total Deauths: 3 ---
*** DEAUTH ATTACK DETECTED! ***

---

Legal & Ethical Notice

N-I-S uses passive monitoring only. It does not:

• Transmit any WiFi frames
• Deauthenticate, disrupt, or interfere with any wireless devices
• Connect to or interact with any network
• Store or exfiltrate any captured data

It is a read-only, observe-only wireless security tool. Use only on networks and in environments you own or have explicit authorisation to monitor.

---

Use Cases

• Home network security monitoring — detect if someone is running deauth attacks against your router
• Wireless security auditing — understand device density in your environment
• Educational tool — learn about 802.11 frame structure and wireless protocols
• Conference/event monitoring — detect hostile wireless activity in crowded spaces
• Penetration testing labs — passive observation during authorised assessments