# codesparadox/noteviltwin architecture

> Architecture diagram of the GitHub repository codesparadox/noteviltwin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codesparadox/noteviltwin
- Repository: https://github.com/codesparadox/noteviltwin

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware & OS"
        direction TB
        wlan0["wlan0 (monitor)"]:::hardware
        wlan1["wlan1 (managed)"]:::hardware
    end

    %% External Entities
    subgraph "External"
        direction TB
        TargetAP["Target AP"]:::external
        TargetClient["Target Client"]:::external
    end

    %% Python CLI Orchestrators
    subgraph "Python CLI Orchestrators"
        direction TB
        NotEvil["NotEvil.py"]:::python
        deauth["deauth.py"]:::python
        fakeap["fake_ap.py"]:::python
        createconf["create_conf_files.py"]:::python
        factory["factory_setting.py"]:::python
        defence["defence.py"]:::python
    end

    %% System Daemons
    subgraph "System Daemons"
        direction TB
        hostapd["hostapd"]:::daemon
        dnsmasq["dnsmasq"]:::daemon
    end

    %% Node.js Server
    subgraph "Node.js Server"
        direction TB
        index2["index2.js"]:::node
    end

    %% Data Store
    subgraph "Data Store"
        direction TB
        passwords["passwords.txt"]:::datastore
    end

    %% Attack Flow
    wlan0 -->|"monitor mode packets"| deauth
    NotEvil -->|"spawns"| deauth
    deauth -->|"deauth frames"| TargetAP
    deauth -->|"deauth frames"| TargetClient

    NotEvil -->|"launches"| fakeap
    fakeap -->|"runs"| createconf
    createconf --> hostapd
    createconf --> dnsmasq
    fakeap -->|"launches"| index2

    hostapd -->|"SSID 10.0.0.1"| wlan1
    dnsmasq -->|"DHCP leases"| TargetClient

    index2 -->|"HTTP GET"| TargetClient
    TargetClient -->|"HTTP POST /password"| index2
    index2 -->|"writes"| passwords

    factory -->|"cleanup"| hostapd
    factory -->|"cleanup"| dnsmasq
    factory -->|"resets"| wlan0
    factory -->|"resets"| wlan1

    %% Defence Flow
    wlan0 -->|"monitor mode sniff"| defence
    TargetAP -->|"deauth frames"| defence
    TargetClient -->|"deauth frames"| defence
    defence -->|"alert|threshold reached"| NotEvil

    %% Click Events
    click NotEvil "https://github.com/codesparadox/noteviltwin/blob/main/attack/NotEvil.py"
    click deauth "https://github.com/codesparadox/noteviltwin/blob/main/attack/deauth.py"
    click fakeap "https://github.com/codesparadox/noteviltwin/blob/main/attack/fake_ap.py"
    click createconf "https://github.com/codesparadox/noteviltwin/blob/main/attack/create_conf_files.py"
    click factory "https://github.com/codesparadox/noteviltwin/blob/main/attack/factory_setting.py"
    click defence "https://github.com/codesparadox/noteviltwin/blob/main/attack/defence.py"
    click index2 "https://github.com/codesparadox/noteviltwin/blob/main/attack/html/index2.js"
    click passwords "https://github.com/codesparadox/noteviltwin/blob/main/attack/html/passwords.txt"
    click Patch "https://github.com/codesparadox/noteviltwin/blob/main/attack/Patch.sh"
    click ReadmeAttack "https://github.com/codesparadox/noteviltwin/blob/main/attack/Readme.md"
    click Pics "https://github.com/codesparadox/noteviltwin/tree/main/attack/pics"
    click ReadmeTop "https://github.com/codesparadox/noteviltwin/blob/main/readme.md"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#0366d6;
    classDef node fill:#DFFFD0,stroke:#228B22;
    classDef daemon fill:#E8E8E8,stroke:#888888;
    classDef hardware fill:#FFE4B5,stroke:#FF8C00,stroke-dasharray: 5 5;
    classDef external fill:#FFD0D0,stroke:#CD5C5C,stroke-dasharray: 2 2;
    classDef datastore fill:#FFFACD,stroke:#DAA520;
```
