How codesparadox/noteviltwin works
Project Type & Purpose
• This is an educational network security toolkit (“Not Evil Twin”) that runs on Unix. It orchestrates two main flows:
a. Attack flow: de-authenticate a client from a real AP, spin up a fake AP, run a phishing web-server to capture credentials.
b. Defence flow: sniff for deauthentication frames to alert on potential attacks.
• It combines Python CLI scripts (using Scapy, subprocess calls to hostapd/dnsmasq, gnome-terminal) and a Node.js/Express web server for phishing.
Main Components
A. Hardware & OS
• Two network interfaces on the host machine (one in “monitor” mode, one in “managed” mode).
• The Unix host runs Python, Node.js, hostapd, dnsmasq, iptables, etc.
B. Python CLI Orchestrators
• NotEvil.py – main attack driver: chooses interfaces, triggers deauth, launches fake_ap.py.
• deauth.py – sends deauthentication packets via Scapy on monitor interface.
• fake_ap.py – generates hostapd/dnsmasq configs, brings up fake SSID (10.0.0.1), and launches index2.js in a new terminal.
• create_conf_files.py – writes hostapd.conf and dnsmasq.conf.
• factory_setting.py – tears down fake AP, deletes config files, resets interfaces.
• defence.py – sniffing daemon: puts interface in monitor mode, counts deauth packets, raises alerts, then switches back to managed.
C. System Daemons
• hostapd – runs the fake access point using generated hostapd.conf.
• dnsmasq – hands out DHCP leases to connecting clients.
D. Node.js Web Server (index2.js)
• Express app serving a captive portal page (generateHTML) on GET.
• Handles POST /password to record credentials to attack/html/passwords.txt (and optionally validate them via node-wifi).
E. Data Store
• passwords.txt – logs captured passphrases.
Interactions & Data Flows
1. User runs python3 NotEvil.py:
– Selects monitor interface → NotEvil.py spawns deauth.py in the same terminal.
– deauth.py continuously emits deauth frames to target AP ↔ client over the monitor interface.
2. NotEvil.py launches fake_ap.py (via gnome-terminal):
– fake_ap.py runs create_conf_files.py → hostapd.conf & dnsmasq.conf
– Starts hostapd & dnsmasq → fake AP SSID on managed interface (10.0.0.1).
– Opens a new terminal to run node html/index2.js on port 80.
3. Target client associates to the fake AP → HTTP requests to Node server:
– GET → serve captive portal HTML.
– POST /password → log entry in passwords.txt → (optional) node-wifi check → respond with success/failure.
4. After credential capture, factory_setting.py is invoked → clean up hostapd/dnsmasq, delete config, reset interfaces.
5. Defence flow (optional): user runs python3 defence.py:
– Selects interface → monitor mode → sniff deauthentication frames with Scapy → count & alert if threshold reached → revert to managed mode.
Architectural Patterns & Design Principles
• Modular CLI utilities: each Python script has a single responsibility (scan, deauth, fake AP setup, cleanup, defense).
• Subprocess orchestration: scripts invoke hostapd/dnsmasq and spawn terminals.
• Event-driven web server: Express handles HTTP GET/POST.
• Clear separation: attack vs defence, network interface roles (monitor vs managed), and technology stacks (Python vs Node).
Essential Elements Checklist
• Annotations on network interfaces and modes.