GhostVPN 👻

A rotating-IP VPN that routes your traffic through a pool of free SOCKS5 proxies and changes your public IP every N minutes. No paid APIs, no subscriptions.

How it works

                          ┌──────────────────────────┐
Your browser ──▶ tun0 ──▶ │ iptables REDIRECT        │
      │                   │  TCP :80/443 → :12345     │
      │                   │  UDP :53    → :5353       │
      │                   └────────────┬─────────────┘
      │                                │
      │  ┌─────────────────────────────▼─────────────────┐
      │  │          TransProxy (:12345)                   │
      │  │    TCP through SOCKS5 proxy pool               │
      │  └─────────────────────────────┬─────────────────┘
      │                                │
      │  ┌─────────────────────────────▼─────────────────┐
      │  │          DnsProxy (:5353)                     │
      │  │    DNS over TCP through SOCKS5 → 1.1.1.1      │
      │  └───────────────────────────────────────────────┘
      │
      │              ┌──────────────────────────────┐
      └──────────────│ SOCKS5 proxy pool            │
                     │  (rotates every N s)         │
                     │  proxy1 ──▶ internet (IP 1)  │
                     │  proxy2 ──▶ internet (IP 2)  │
                     │  proxy3 ──▶ internet (IP 3)  │
                     └──────────────────────────────┘

Three modes:

• TUN mode (Linux) — system-wide VPN using tun + iptables. All TCP traffic goes through the proxy automatically. DNS queries are forwarded through the proxy via a local DNS forwarder to prevent leaks.
• Wintun mode (Windows) — system-wide VPN using Wintun TAP adapter. Routes all TCP traffic through the SOCKS5 proxy pool. DNS forwarded through the tunnel.
• SOCKS mode (Linux, macOS, Windows) — local SOCKS5 proxy on 127.0.0.1:10800. Configure your apps or system proxy to use it.

Quick start

Linux (TUN mode — full system VPN)

cd GhostVPN
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Interactive menu (recommended)
sudo .venv/bin/python3 vpn.py

# CLI mode (for scripts)
sudo .venv/bin/python3 vpn.py --cli --interval 30

The interactive menu starts the VPN from option [1]. Configure settings via option [2].

macOS (SOCKS mode)

cd GhostVPN
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Interactive menu (no root needed)
python3 vpn.py

# Or use settings → enable system proxy, or run directly:
python3 vpn.py --cli --mode socks --sys-proxy

Configure your browser to use SOCKS5 127.0.0.1:10800, or let GhostVPN set the system proxy automatically.

Windows (Wintun mode — full system VPN)

cd GhostVPN
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Interactive menu (no admin needed, Wintun auto-downloaded)
python vpn.py

# CLI mode
python vpn.py --cli --mode windows

Usage

Interactive menu (default)

Run python vpn.py to see:

   ________  ______  ____________    ______  _   __
  / ____/ / / / __ \/ ___/_  __/ |  / / __ \/ | / /
 / / __/ /_/ / / / /\__ \ / /  | | / / /_/ /  || /
/ /_/ / __  / /_/ /___/ // /   | |/ / ____/ /|  /
\____/_/ /_/\____//____//_/    |___/_/   /_/ |_/

              👻  ROTATING IP VPN  👻

  MAIN MENU

     [1] ▶  START VPN  (TUN (Linux) / Wintun (Windows))
          interval=180s  port=10800

     [2] Settings
     [3] About
     [4] Exit

  └─ Choice:

• [1] — starts the VPN with current settings
• [2] — configure mode, interval, port, proxy source, system proxy, kill switch
• [3] — version, license, repo link
• [4] — exit

CLI mode (--cli)

python vpn.py --cli [options]

Flag	Default	Description
--mode	tun (Linux), windows (Win), socks (else)	tun = system VPN (Linux), windows = Wintun VPN (Windows), socks = local proxy
--interval	180	Seconds between IP rotations
--proxies	—	Path to custom proxy list (host:port per line)
--proxy-port	10800	Local SOCKS proxy port (socks mode)
--sys-proxy	off	Automatically set system proxy (macOS/Windows)
--kill-switch	off	Drop connections if all proxies fail (no IP leak)
--verbose	off	Debug-level logs

Custom proxy lists

python vpn.py --cli --mode socks --proxies proxies.txt

Platform comparison

Feature	Linux (TUN)	macOS (SOCKS)	Windows (Wintun)
System-wide routing	✅ Automatic	⚠️ Manual app config	✅ Automatic
Root required	✅ Yes	❌ No	❌ No
Proxy rotation	✅	✅	✅
Kill switch	✅ --kill-switch	✅	✅
DNS leak protection	✅ Built-in	⚠️ Manual app config	✅ Built-in
Auto system proxy	❌	✅ --sys-proxy	❌
UDP/ICMP	❌ Not supported	❌ Not supported	❌ Not supported

Verification

watch -n 10 curl -s ifconfig.me

Security

GhostVPN has the following security features enabled:

• Private vulnerability reporting — report issues privately at https://github.com/20player11/GhostVPN/security/advisories
• Dependabot alerts — automatic notifications for vulnerable dependencies
• Dependabot security fixes — auto-generated PRs for patched dependencies
• CodeQL code scanning — runs on every push/PR via GitHub Actions
• SECURITY.md — disclosure policy with 24h/7d/30d response timeline

Known limitations

• Encryption — GhostVPN does not encrypt traffic end-to-end. SOCKS5 proxies see plaintext data. Use HTTPS/TLS for sensitive traffic.
• Privilege separation — The VPN runs in a single process. No sandboxing or seccomp is applied.
• DNS — DNS queries are redirected through the VPN via the built-in DNS proxy (dns.py). No more DNS leaks.
• IPv6 — IPv6 traffic is blocked in TUN mode to prevent leaks. SOCKS mode only handles IPv4.

Project structure

vpn/
├── vpn.py            # CLI entry — interactive menu or --cli mode
├── ui.py             # Rich terminal UI (menus, status display, about)
├── windows_vpn.py    # Windows Wintun adapter, TCP forwarding, DNS tunnel
├── wintun_dl.py      # Auto-downloads wintun.dll at runtime
├── tun.py            # Linux TUN device, routing, iptables
├── transproxy.py     # Linux transparent TCP → SOCKS5 proxy
├── local_proxy.py    # Cross-platform SOCKS5 proxy server
├── proxy_pool.py     # Auto-fetch, health-check, rotation
├── dns.py            # DNS forwarder (prevents DNS leaks in TUN mode)
├── utils.py          # Logging, IP lookup, helpers
├── requirements.txt  # PySocks, pyfiglet, rich, questionary
├── LICENSE           # MIT
└── README.md

Troubleshooting

Linux: "Failed to create tun"

sudo modprobe tun

macOS: "networksetup" errors

Approve Terminal in System Settings → Privacy & Security → Accessibility.

No working proxies found

Proxy lists change. Try again later or use --proxies with your own list.

Internet stops after Ctrl+C (Linux)

sudo iptables -t nat -F OUTPUT
sudo ip rule del pref 20000 2>/dev/null
sudo ip rule del pref 1000 2>/dev/null
sudo ip link del tun0 2>/dev/null

Dependencies

• PySocks — SOCKS5 client protocol
• pyfiglet — ASCII art generation
• rich — Terminal UI components
• questionary — Interactive prompts

License

MIT