# p0cl4bs/wifipumpkin3 architecture

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

- Interactive diagram: https://gitdiagram.com/p0cl4bs/wifipumpkin3
- Repository: https://github.com/p0cl4bs/wifipumpkin3

## Overview

#### Purpose and Entry Points
Wifipumpkin3 is a Python 3.8+ Linux framework for operating a rogue wireless access point and associated man-in-the-middle services. The primary executable entry point is `wifipumpkin3/__main__.py`; package metadata/install entry points are defined in `setup.py`. It exposes both an interactive control surface and a REST service.

#### Control Plane and Session Orchestration
Controllers coordinate AP lifecycle, wireless mode selection, DHCP/DNS, proxy/MITM services, extensions, and UI state. This layer is the main boundary between user/API commands and privileged network processes.
- `wifipumpkin3/core/controllers/defaultcontroller.py`
- `wifipumpkin3/core/controllers/wirelessmodecontroller.py`
- `wifipumpkin3/core/controllers/mitmcontroller.py`

#### Wireless Access-Point Provisioning
Wireless modes create and manage the rogue AP, with static, Karma-style, Docker, and REST-driven variants. Hostapd configuration is supplied as deployable configuration, while packet/network modules handle interface-level operations.
- `wifipumpkin3/core/wirelessmode/wirelessmode.py`
- `wifipumpkin3/core/wirelessmode/static.py`
- `config/hostapd/hostapd.conf`

#### Client Network Services
After clients join the AP, DHCP assigns network settings and DNS resolves or redirects requests. Controllers select/manage server implementations; packet-level components provide DHCP, DNS, DNS spoofing, and listener behavior.
- `wifipumpkin3/core/servers/dhcp/dhcp.py`
- `wifipumpkin3/core/servers/dns/pyDNSServer.py`
- `wifipumpkin3/core/packets/dnsspoofNF.py`

#### Traffic Interception and Captive Portals
The proxy/MITM stage receives client traffic after AP/DHCP/DNS setup. It supports transparent proxy modes, captive Flask portals, phishing/QR flows, traffic modification plugins, and packet inspection. Captive portal presentation is separated from Python plugin logic through template directories.
- `wifipumpkin3/core/servers/proxy/proxymode.py`
- `wifipumpkin3/core/servers/proxy/captiveflask.py`
- `wifipumpkin3/plugins/pumpkinproxy/base.py`
- `config/templates/`

#### Extensions, Modules, and Plugin Boundary
Command extensions expose operations such as AP setup, DHCP configuration, proxy selection, client/network inspection, and shutdown. Optional modules implement scanning, deauthentication, ARP/DNS spoofing, and custom portal functionality. Plugin packages are the intended extension boundary for proxy transforms, sniffing output, and captive portal variants.
- `wifipumpkin3/extensions/ap.py`
- `wifipumpkin3/modules/wifi/wifiscan.py`
- `wifipumpkin3/plugins/captiveflask/plugin.py`

#### API, Runtime, and Infrastructure
A Flask-style REST application exposes access-point, command, plugin, proxy, logging, and authentication endpoints, providing a programmatic alternative to the local UI. The runtime requires Linux and `hostapd`; exception assets also indicate dependencies on `iptables` and DHCP tooling. Container deployment is represented by `Dockerfile` and `docker-compose.yml`.
- `wifipumpkin3/core/servers/rest/application.py`
- `wifipumpkin3/core/servers/rest/blueprints/restapi/accesspoint.py`
- `Dockerfile`

Main entry points: [`wifipumpkin3/core/controllers/defaultcontroller.py`](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/defaultcontroller.py) (Session controllers), [`wifipumpkin3/core/wirelessmode/wirelessmode.py`](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/wirelessmode/wirelessmode.py) (Wireless modes), [`wifipumpkin3/core/servers/proxy/proxymode.py`](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/proxy/proxymode.py) (Proxy modes), [`wifipumpkin3/core/servers/dns/pyDNSServer.py`](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/dns/pyDNSServer.py) (DNS service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_entry["CLI entry point<br/>Python executable<br/>[__main__.py]"]
  node_controllers["Session controllers<br/>controller layer"]
  node_wireless_controller["Wireless mode controller"]
  node_mitm_controller["MITM controller<br/>[mitmcontroller.py]"]
end

subgraph group_network["Network plane"]
  node_wireless_modes["Wireless modes<br/>AP provisioning<br/>[wirelessmode.py]"]
  node_static_ap["Static AP mode<br/>wireless mode<br/>[static.py]"]
  node_hostapd["hostapd configuration<br/>AP config<br/>[hostapd.conf]"]
  node_dhcp["DHCP service<br/>network service<br/>[dhcp.py]"]
  node_dns["DNS service<br/>network service<br/>[pyDNSServer.py]"]
  node_dns_spoof["DNS spoofing<br/>packet component<br/>[dnsspoofNF.py]"]
end

subgraph group_intercept["Interception"]
  node_proxy_modes["Proxy modes<br/>MITM service<br/>[proxymode.py]"]
  node_captive_portal["Captive Flask portal<br/>portal service<br/>[captiveflask.py]"]
  node_portal_templates["Portal templates<br/>presentation assets"]
end

subgraph group_extensions["Extensions"]
  node_proxy_plugins{{"Proxy plugins<br/>plugin boundary<br/>[base.py]"}}
  node_command_extensions["Command extensions<br/>[ap.py]"]
  node_wifi_scan["Wi-Fi scanning module<br/>optional module<br/>[wifiscan.py]"]
  node_captive_plugin{{"Captive portal plugins<br/>plugin boundary<br/>[plugin.py]"}}
end

subgraph group_api["API &amp; deployment"]
  node_rest_app["REST application<br/>Flask REST service<br/>[application.py]"]
  node_accesspoint_api["Access-point API<br/>REST blueprint<br/>[accesspoint.py]"]
  node_container["Container image<br/>deployment"]
end

node_entry -->|"starts"| node_controllers
node_controllers -->|"selects mode"| node_wireless_controller
node_controllers -->|"manages"| node_mitm_controller
node_controllers -->|"exposes commands"| node_command_extensions
node_wireless_controller -->|"provisions"| node_wireless_modes
node_wireless_modes -->|"implements"| node_static_ap
node_static_ap -->|"uses"| node_hostapd
node_wireless_modes -->|"serves joined clients"| node_dhcp
node_wireless_modes -->|"serves joined clients"| node_dns
node_dns -->|"redirect rules"| node_dns_spoof
node_mitm_controller -->|"selects"| node_proxy_modes
node_dhcp -.->|"client traffic path"| node_proxy_modes
node_dns -->|"redirects traffic"| node_proxy_modes
node_proxy_modes -->|"hosts portal"| node_captive_portal
node_captive_portal -->|"renders"| node_portal_templates
node_proxy_modes -->|"loads transforms"| node_proxy_plugins
node_captive_portal -->|"loads variants"| node_captive_plugin
node_command_extensions -.->|"invokes"| node_wifi_scan
node_rest_app -->|"registers"| node_accesspoint_api
node_accesspoint_api -->|"controls"| node_controllers
node_container -.->|"deploys"| node_rest_app
node_container -.->|"packages runtime"| node_wireless_modes

click node_entry "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/__main__.py"
click node_controllers "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/defaultcontroller.py"
click node_wireless_controller "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/wirelessmodecontroller.py"
click node_mitm_controller "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/mitmcontroller.py"
click node_wireless_modes "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/wirelessmode/wirelessmode.py"
click node_static_ap "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/wirelessmode/static.py"
click node_hostapd "https://github.com/p0cl4bs/wifipumpkin3/blob/main/config/hostapd/hostapd.conf"
click node_dhcp "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/dhcp/dhcp.py"
click node_dns "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/dns/pyDNSServer.py"
click node_dns_spoof "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/packets/dnsspoofNF.py"
click node_proxy_modes "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/proxy/proxymode.py"
click node_captive_portal "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/proxy/captiveflask.py"
click node_proxy_plugins "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/plugins/pumpkinproxy/base.py"
click node_command_extensions "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/extensions/ap.py"
click node_wifi_scan "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/modules/wifi/wifiscan.py"
click node_captive_plugin "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/plugins/captiveflask/plugin.py"
click node_rest_app "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/rest/application.py"
click node_accesspoint_api "https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/rest/blueprints/restapi/accesspoint.py"
click node_container "https://github.com/p0cl4bs/wifipumpkin3/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_controllers,node_wireless_controller,node_mitm_controller toneBlue
class node_wireless_modes,node_static_ap,node_hostapd,node_dhcp,node_dns,node_dns_spoof toneAmber
class node_proxy_modes,node_captive_portal,node_portal_templates toneMint
class node_proxy_plugins,node_command_extensions,node_wifi_scan,node_captive_plugin toneRose
class node_rest_app,node_accesspoint_api,node_container toneIndigo
```

## Components

### Control plane

Coordinates AP sessions and privileged services.

- [CLI entry point](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/__main__.py): Python executable · `wifipumpkin3/__main__.py`
- [Session controllers](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/defaultcontroller.py): controller layer · Coordinates lifecycle, wireless mode, MITM, and UI state. · `wifipumpkin3/core/controllers/defaultcontroller.py`
- [Wireless mode controller](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/wirelessmodecontroller.py): controller · `wifipumpkin3/core/controllers/wirelessmodecontroller.py`
- [MITM controller](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/controllers/mitmcontroller.py): controller · `wifipumpkin3/core/controllers/mitmcontroller.py`

### Network plane

Provisions the AP and joined clients.

- [Wireless modes](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/wirelessmode/wirelessmode.py): AP provisioning · Base for static, Karma, Docker, and REST AP modes. · `wifipumpkin3/core/wirelessmode/wirelessmode.py`
- [Static AP mode](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/wirelessmode/static.py): wireless mode · `wifipumpkin3/core/wirelessmode/static.py`
- [hostapd configuration](https://github.com/p0cl4bs/wifipumpkin3/blob/main/config/hostapd/hostapd.conf): AP config · `config/hostapd/hostapd.conf`
- [DHCP service](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/dhcp/dhcp.py): network service · Assigns client network settings. · `wifipumpkin3/core/servers/dhcp/dhcp.py`
- [DNS service](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/dns/pyDNSServer.py): network service · Resolves or redirects client requests. · `wifipumpkin3/core/servers/dns/pyDNSServer.py`
- [DNS spoofing](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/packets/dnsspoofNF.py): packet component · `wifipumpkin3/core/packets/dnsspoofNF.py`

### Interception

Captures and modifies client traffic.

- [Proxy modes](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/proxy/proxymode.py): MITM service · Receives redirected client traffic. · `wifipumpkin3/core/servers/proxy/proxymode.py`
- [Captive Flask portal](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/proxy/captiveflask.py): portal service · `wifipumpkin3/core/servers/proxy/captiveflask.py`
- **Portal templates**: presentation assets

### Extensions

Optional commands, modules, and plugins.

- [Proxy plugins](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/plugins/pumpkinproxy/base.py): plugin boundary · Provides traffic transforms and inspection extensions. · `wifipumpkin3/plugins/pumpkinproxy/base.py`
- [Command extensions](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/extensions/ap.py): command extension · `wifipumpkin3/extensions/ap.py`
- [Wi-Fi scanning module](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/modules/wifi/wifiscan.py): optional module · `wifipumpkin3/modules/wifi/wifiscan.py`
- [Captive portal plugins](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/plugins/captiveflask/plugin.py): plugin boundary · `wifipumpkin3/plugins/captiveflask/plugin.py`

### API & deployment

Programmatic control and container runtime.

- [REST application](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/rest/application.py): Flask REST service · Programmatic alternative to the local control surface. · `wifipumpkin3/core/servers/rest/application.py`
- [Access-point API](https://github.com/p0cl4bs/wifipumpkin3/blob/main/wifipumpkin3/core/servers/rest/blueprints/restapi/accesspoint.py): REST blueprint · `wifipumpkin3/core/servers/rest/blueprints/restapi/accesspoint.py`
- [Container image](https://github.com/p0cl4bs/wifipumpkin3/blob/main/Dockerfile): deployment · `Dockerfile`

## Connections

- CLI entry point → Session controllers: starts
- Session controllers → Wireless mode controller: selects mode
- Session controllers → MITM controller: manages
- Session controllers → Command extensions: exposes commands
- Wireless mode controller → Wireless modes: provisions
- Wireless modes → Static AP mode: implements
- Static AP mode → hostapd configuration: uses
- Wireless modes → DHCP service: serves joined clients
- Wireless modes → DNS service: serves joined clients
- DNS service → DNS spoofing: redirect rules
- MITM controller → Proxy modes: selects
- DHCP service → Proxy modes: client traffic path
- DNS service → Proxy modes: redirects traffic
- Proxy modes → Captive Flask portal: hosts portal
- Captive Flask portal → Portal templates: renders
- Proxy modes → Proxy plugins: loads transforms
- Captive Flask portal → Captive portal plugins: loads variants
- Command extensions → Wi-Fi scanning module: invokes
- REST application → Access-point API: registers
- Access-point API → Session controllers: controls
- Container image → REST application: deploys
- Container image → Wireless modes: packages runtime