diff --git a/README.md b/README.md index 8b4cf72..595c2bb 100644 --- a/README.md +++ b/README.md @@ -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.*