drjones/proxy-god
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: README overhaul — sharper voice, same facts

Browse Source 
Made-with: Cursor
This commit is contained in:
Dr Jones
2026-04-15 14:35:18 -07:00
parent 096c5094fb
commit dc1a1c3efd
1 changed files with 75 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
README.md
View File

@@ -1,37 +1,51 @@
# Proxy God — Rotating Proxy Chain Manager for Windows
# Proxy God
Auto-fetches, validates and rotates multi-hop proxy chains with a live GUI, Windows kill-switch firewall, system proxy enforcement, and tray icon. Works on top of NordVPN (or any VPN) as the outer tunnel.
**Multi-hop proxy chains. Self-healing. Windows-native. You pick the exit; the machine enforces the rules.**
Not another toy script. This is a full **rotating chain engine** on top of **GOST**: it pulls lists, stress-tests proxies in parallel, builds random hops, and **keeps checking** until something dies—then it **rotates** and keeps going. Optional **firewall kill-switch** so traffic either goes through your chain or **it doesn’t go out at all** (when you run as Admin). Works **under NordVPN** (or any VPN) so your outer tunnel stays first—then the chaos of public proxies happens **inside** that envelope.
```
YOU → NordVPN (OS tunnel) → Hop 1 → Hop 2 → Hop 3 → Internet
YOU → VPN (outer tunnel) → Hop 1 → Hop 2 → … → Last hop → Internet
```
---
## Features
## What it does (the short version)
- **Auto proxy pool** — fetches from Proxifly CDN every 30 min, validates concurrently
- **Multi-hop GOST chains** — 2–8 hops, randomly picked from validated pool
- **Obfuscation modes** — Auto, HTTP-only, SOCKS5-only, Random Mix
- **Manual chain builder** — drag/reorder hops, pin your own IPs
- **Fixed exit (last hop)** — optional URL used only as the final hop; earlier hops still rotate randomly (ignored when a full manual chain is pinned)
- **Exit IP verification** — checks real exit IP every health cycle, rotates if it matches your real IP
- **Windows system proxy** — sets `HKCU` registry proxy so all WinINet apps use the chain
- **Firewall kill-switch** — `netsh` rules that block all outbound except GOST + NordVPN when running as Admin
- **Tray icon** — green/yellow/red circle, right-click menu
- **Boot persistence** — Task Scheduler logon task
| Layer | What happens |
|--------|----------------|
| **Pool** | Fetches live lists (Proxifly CDN), dedupes, validates like a hammer. |
| **Chain** | Random **N-hop** path through survivors—no lazy repeats in a cycle. |
| **Exit check** | If your “exit IP” looks like your **real** IP, the chain is **dead**—rotate. |
| **System proxy** | WinINet gets the rules—apps that respect Windows proxy **follow the chain**. |
| **Kill-switch** | Optional **netsh** lockdown: **GOST**, **this app**, **NordVPN stack** get out; everything else can **wait** (Admin). |
| **Tray** | Green / yellow / red. You know the state without opening the window. |
| **Boot** | Scheduled task—**fire on logon**, keep the machine in the game. |
---
## Firepower (features)
- **Auto pool** — Pull, validate, shuffle, drain. Rinse on a timer.
- **1–8 hops** — Slider + top-bar **+/−**. You control depth.
- **Obfuscation modes** — Auto, HTTP-only, SOCKS5-only, Random Mix.
- **Fixed exit** — **Last hop only**: yours. Everything else still rotates. Hop count **1** = **only** your exit, no pool.
- **Pinned chain** — Full manual order when you want to **own** the path.
- **Leak sniffing** — Compares exit IP vs direct; mismatch or no exit = **rotate**.
- **GOST** — Downloaded once; **Defender exclusion** on the app folder so AV doesn’t eat the binary.
- **VM-safe** — Listener stays on **127.0.0.1**—clone the box, DHCP can change; **this doesn’t care**.
---
## Requirements
- **Windows 10/11 x64**
- **Python 3.10+** (or use the pre-built `.exe`)
- **NordVPN** (recommended but optional — any VPN works)
- **Python 3.10+** *or* the built **`.exe`**
- **VPN** recommended (Nord or any)—outer tunnel before the proxy zoo
---
## Quick Start (from source)
## Quick start (source)
```cmd
git clone https://gitea.thetempleofdoom.com/drjones/proxy-god.git
@@ -40,92 +54,81 @@ pip install -r requirements.txt
python run.py
```
> Run as **Administrator** for full kill-switch firewall enforcement.
**Administrator** = full kill-switch. No admin = still runs; firewall enforcement steps aside.
---
## Build standalone `.exe`
## Build the binary
```cmd
build_exe.bat
```
Output: `dist\ProxyChainManager.exe` + copied to Desktop.
**Output:** `dist\ProxyChainManager.exe` — script also tries to drop a copy on your **Desktop**.
---
## Usage
## Run it like you mean it
1. Launch `ProxyChainManager.exe` (accept UAC prompt for Admin)
2. Configure settings in **Settings** tab if needed (defaults work fine)
3. Click **▶ Start** — the app will:
- Download GOST (one time, ~9 MB) and add Defender exclusion
- Fetch proxy lists from Proxifly CDN
- Validate them concurrently
- Build a random N-hop chain
- Verify the exit IP is different from your real IP
- Set Windows system proxy
- Engage firewall kill-switch (Admin only)
4. Close window → minimizes to tray (chain keeps running)
5. Click **Quit** or tray → Quit to fully stop
1. Launch **`ProxyChainManager.exe`** (UAC if you want the kill-switch).
2. Tweak **Settings** if you’re picky—defaults are **solid** out of the box.
3. Hit **Start**. First run grabs **GOST**, whitelists the folder in Defender, pulls lists, validates, chains, verifies exit IP, sets **system proxy**, engages **firewall** (if Admin).
4. Close the window → **tray**; the engine **keeps running** until you **Quit**.
---
## Chain Builder Tab
## Chain Builder (where you get surgical)
- **Obfuscation mode** — selects which protocols to include in chains
- **Hop count slider** — 1–8 total hops (top bar ± or slider)
- **Fixed exit (last hop only)** — optional field: your SOCKS/HTTP proxy is always the **last** hop before the internet; all **earlier** hops are still chosen at random from the validated pool. Leave empty for a fully automatic chain. Set hop count to `1` to use **only** your fixed exit (no pool). While **Pin & use this chain** is on, the full pinned list wins and fixed exit is ignored.
- **Manual chain** — enter proxies manually, reorder with ↑↓, enable "Use this chain" to pin it
- **Paste current** — copies the auto-selected chain into the editor
- **Sources** — add/remove proxy list URLs (JSON format from Proxifly)
- **Mode** — Protocol mix for the pool.
- **Hops** — Total length; **fixed exit** always rides **last** (unless you pinned a full manual chain).
- **Manual list** — Add, reorder, **pin** when you don’t trust randomness.
- **Sources** — Your JSON URLs; defaults are Proxifly CDN endpoints.
---
## Settings Reference
## Settings cheat sheet
| Setting | Default | Description |
|---|---|---|
| Local port | 18888 | HTTP proxy port — point apps here |
| Health check sec | 180 | How often to re-verify exit IP |
| Full refresh sec | 1800 | How often to re-fetch + re-validate |
| Concurrency | 64 | Parallel proxy validators |
| Max candidates | 400 | Max proxies sampled for validation per cycle |
| Timeout sec | 12 | Per-proxy validation timeout |
| Kill-switch | ON | Block all outbound traffic except GOST + Nord |
| Setting | Default | Meaning |
|--------|---------|--------|
| Local port | `18888` | Where your HTTP proxy **listens** |
| Health check | `180` s | How often the exit **gets re-proven** |
| Pool refresh | `1800` s | How often lists get **re-fetched** and re-tested |
| Concurrency | `64` | How hard you **spam** validation |
| Max candidates | `400` | Cap per cycle before testing |
| Timeout | `12` s | Per-proxy **patience** |
| Kill-switch | ON | **All-or-nothing** outbound (when Admin + firewall engaged) |
---
## Architecture
## Stack (for people who read code)
```
app.py GUI (CustomTkinter, 3 tabs)
service.py Background thread — pool management, GOST lifecycle, health check
gost_util.py Downloads and manages gost.exe
firewall.py netsh kill-switch rules
sysproxy.py Windows registry system proxy (WinINet broadcast)
tray.py pystray tray icon
config.py Settings dataclass + JSON persistence
validator.py Async proxy validation + exit IP checking
fetcher.py Proxifly JSON fetcher
app.py Dark UI — CustomTkinter, tabs, tray
service.py Async loop — pool, GOST, health, rotation
gost_util.py GOST binary + Defender hook
firewall.py netsh kill-switch
sysproxy.py Registry + WinINet broadcast
tray.py Status icon
validator.py httpx + SOCKS — parallel checks
fetcher.py Proxifly JSON
config.py Settings + sanitization
```
---
## Proxy Sources
## Default sources
Default sources use [proxifly/free-proxy-list](https://github.com/proxifly/free-proxy-list) CDN:
- `https://cdn.jsdelivr.net/gh/proxifly/free-proxy-list@main/proxies/protocols/http/data.json`
- `https://cdn.jsdelivr.net/gh/proxifly/free-proxy-list@main/proxies/protocols/socks5/data.json`
- `https://cdn.jsdelivr.net/gh/proxifly/free-proxy-list@main/proxies/protocols/https/data.json`
You can add any URL returning a JSON array of `{"proxy":"http://ip:port", ...}` objects.
[Proxifly / free-proxy-list](https://github.com/proxifly/free-proxy-list) over jsDelivr—**HTTP**, **SOCKS5**, **HTTPS** JSON feeds. Roll your own: any URL that returns `[{"proxy":"http://ip:port",...}, ...]`.
---
## Notes
## Reality check (read this)
- Free public proxies are **untrusted** — do not send sensitive unencrypted data
- NordVPN (or any VPN) as the OS tunnel means the proxy operators only see the VPN exit IP, not your ISP IP
- Kill-switch requires **Admin** — UAC prompt appears on launch
- Works on cloned VMs — all listeners bind to `127.0.0.1`, not the machine's LAN IP
- **Public proxies are hostile**—treat them as **disposable**. No banking over cleartext.
- **VPN first** means proxy operators see the **VPN exit**, not your home ISP.
- **Kill-switch** is **serious**—it can block apps that don’t play by proxy rules. Know what you’re doing.
- **Clone-friendly**: bind is **loopback**—this repo doesn’t bake in LAN IPs.
---
**Proxy God** — *not because it’s polite. Because it runs.*