diff --git a/README.md b/README.md index b313373..00004ed 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,105 @@ # Proxy God -**Multi-hop proxy chains. Self-healing. Windows-native. You pick the exit; the machine enforces the rules.** +**Mission-grade rotating proxy chains for Windows.** +**Self-healing. Leak-aware. Aggressive by default.** -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. +This is not a toy wrapper around random free lists. +Proxy God runs a full chain engine on top of **GOST**: fetch, dedupe, parallel-validate, build hops, verify exit, monitor health, rotate on failure, repeat forever. + +When run as Admin, it can enforce a hard rule: +**traffic goes through the chain, or traffic does not go out.** ``` -YOU → VPN (outer tunnel) → Hop 1 → Hop 2 → … → Last hop → Internet +YOU -> VPN (outer tunnel) -> Hop 1 -> Hop 2 -> ... -> Exit hop -> Internet ``` --- -## What it does (the short version) +## Why it exists -| 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. | +- Public proxies die constantly. This keeps rotating until it finds alive paths. +- "Connected" means nothing without proof. This continuously re-validates exit behavior. +- Browser traffic leaks in weird ways on Windows. This now enforces proxy policy and disables QUIC where needed. +- If the chain breaks, it should fail closed (optional kill-switch), not fail open. --- -## Firepower (features) +## Core capabilities -- **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**. +| Layer | Behavior | +|------|------| +| **Pool engine** | Pulls proxy feeds, dedupes, validates in parallel, keeps survivors only. | +| **Chain engine** | Builds random N-hop paths, avoids lazy repeats during a cycle. | +| **Pinned mode** | Full manual chain order when you want deterministic routing. | +| **Exit control** | Test and save a fixed exit/final hop from GUI (`host:port:user:pass` supported). | +| **Leak checks** | Compares chain exit against direct/VPN identity and rotates on leak signatures. | +| **HTTPS tunnel probe** | Detects HTTP-only chains that would break real browsers (CONNECT failures). | +| **System proxy enforcement** | WinINet + Connections blob + WinHTTP + browser policy integration. | +| **Kill-switch** | `netsh` firewall lockdown (Admin): allow only approved outbound paths. | +| **Tray telemetry** | Red/yellow/green status with live exit visibility. | + +--- + +## Feature set (high level) + +- Auto pool refresh and shuffle-drain rotation model +- 1-8 hop chains +- Obfuscation modes: Auto, HTTP-only, SOCKS5-only, Random Mix +- Fixed-exit and full manual-chain workflows +- Fast per-hop GUI testing with live status colors +- VPN-aware leak logic +- LAN privacy lockdown (LLMNR / NetBIOS / mDNS controls) +- Telemetry hardening and forensic wipe tooling +- Hardened/spoofed Firefox launch profiles with persona and cookie modes +- VM-safe loopback listener (`127.0.0.1`) for clone portability --- ## Requirements - **Windows 10/11 x64** -- **Python 3.10+** on PATH (or the **`py`** launcher with a 3.10+ install) — *only needed to build*; the shipped **`.exe`** runs without Python -- **VPN** recommended (Nord or any)—outer tunnel before the proxy zoo +- **Python 3.10+** on PATH (or `py` launcher) to build from source +- Python is **not required** to run the built `.exe` +- VPN strongly recommended (outer tunnel first) --- -## Clone / pull → one build script → Desktop +## Build to Desktop (recommended) -Typical flow: - -1. **Clone** (or `git pull` if you already have the repo): +1. Clone (or `git pull` in existing repo): ```cmd git clone https://gitea.thetempleofdoom.com/drjones/proxy-god.git cd proxy-god ``` -2. **Python** (first machine only): if `python --version` / `py -3` isn’t 3.10+, install then reopen the terminal: +2. Install Python if needed: ```cmd winget install Python.Python.3.12 --accept-package-agreements --accept-source-agreements ``` -3. **Build** — upgrades **pip**, installs **requirements.txt** + **PyInstaller**, produces **`dist\ProxyChainManager.exe`**, copies **`ProxyChainManager.exe`** to your **Desktop**, and creates **`Proxy God.lnk`** pointing at it: +3. Build: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup_and_build.ps1 ``` - Same steps from **`build_exe.bat`** or double‑click **`FirstRun_Build_And_Install.bat`** (checks Python 3.10+, then runs the same script; pauses at the end so you can read errors). -| Where | What | -|--------|------| -| `dist\ProxyChainManager.exe` | Built app (same bits as Desktop copy) | -| **Desktop → `Proxy God.lnk`** | **Double‑click this** — shortcut to the Desktop exe | -| **Desktop → `ProxyChainManager.exe`** | Same app (refreshed every build) | +Equivalent paths: +- `build_exe.bat` +- `FirstRun_Build_And_Install.bat` -After a successful build, if the shortcut is missing but the exe exists, you can recreate it: +Artifacts: +| Path | Purpose | +|------|------| +| `dist\ProxyChainManager.exe` | Built binary | +| `Desktop\ProxyChainManager.exe` | Refreshed desktop copy | +| `Desktop\Proxy God.lnk` | Shortcut target for daily use | + +Recreate missing shortcut: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\create_desktop_shortcut.ps1 ``` -First run of the **exe**: accept **UAC** if you want the firewall kill-switch. In the app, press **▶ Start**. - -You do **not** need Python installed to **run** the Desktop **`.exe`** — only to **build** it with the script above. - --- -## Quick start (run from source, no exe) +## Run from source (no exe) ```cmd cd proxy-god @@ -90,80 +107,96 @@ pip install -r requirements.txt python run.py ``` -**Administrator** = full kill-switch. No admin = still runs; firewall enforcement steps aside. +- Run as **Administrator** for full firewall and policy features. +- Non-admin mode still works, but privileged controls are skipped. -### Self-test (core logic, no GUI) +--- +## Validation / tests + +Core logic test suite: ```cmd python -m unittest discover -s tests -v ``` -Hits config sanitization, fetcher smoke, validator timeouts, and a live `get_direct_ip` check (skips if you’re offline). +Covers config sanitization, parser behavior, validator timing behavior, leak checks, and smoke paths. --- -## Run it like you mean it +## Operator quickstart -1. Launch **`Proxy God.lnk`** on the Desktop (or **`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**. +1. Launch `Proxy God.lnk` (or `ProxyChainManager.exe`). +2. Accept UAC if you want full enforcement. +3. Configure Chain Builder if you need manual control. +4. Press **Start**. +5. Minimize to tray; engine keeps running until quit. + +First run bootstraps GOST, fetches/validates pool, builds chain, verifies exit, applies proxy stack, then enforces configured protections. --- -## Chain Builder (where you get surgical) +## Chain Builder notes -- **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. +- You can paste exit proxy formats like: + - `host:port:user:pass` + - `user:pass@host:port` + - `scheme://host:port` +- **Test exit** validates the candidate. +- **Save as final hop** appends that exit to your manual chain as the last hop. +- "Use this chain on Start" makes manual routing authoritative. --- ## Settings cheat sheet | 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 | -| Stop after N valid | `20` | **Early-exit** — stop testing as soon as N good proxies found | -| Max candidates | `200` | Cap per cycle (shuffled, so random sample) | -| Timeout | `12` s | Per-proxy **patience** | -| Kill-switch | ON | **All-or-nothing** outbound (when Admin + firewall engaged) | +|------|------|------| +| Local port | `18888` | Local HTTP listener | +| Health check | `180` s | Exit re-validation interval | +| Pool refresh | `1800` s | Re-fetch + re-validate cadence | +| Concurrency | `64` | Validator fan-out | +| Stop after N valid | `20` | Early-exit threshold | +| Max candidates | `200` | Random sample cap per cycle | +| Timeout | `12` s | Per-proxy timeout | +| Kill-switch | ON | Fail-closed outbound policy (Admin) | --- -## Stack (for people who read code) +## Code layout -``` -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 +```text +app.py UI (CustomTkinter), tray wiring, operator workflows +service.py async chain loop, rotation, health, enforcement +gost_util.py GOST bootstrap and process management +firewall.py netsh kill-switch +sysproxy.py WinINet/Connections/WinHTTP/browser policy handling +validator.py parallel checks + exit/HTTPS probes +fetcher.py source ingestion +browser_*.py hardened/spoofed browser profile + launcher +config.py settings model and sanitization ``` --- ## Default sources -[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",...}, ...]`. +Default feeds are from [Proxifly / free-proxy-list](https://github.com/proxifly/free-proxy-list) via jsDelivr (`HTTP`, `SOCKS5`, `HTTPS` JSON). + +Custom source format expected: +```json +[{"proxy":"http://ip:port"}, ...] +``` --- -## Reality check (read this) +## Reality check -- **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. +- Public proxies are hostile and disposable. +- VPN-first masks home ISP from proxy operators. +- Kill-switch is intentionally strict and can block non-compliant apps. +- If HTTPS tunnel probe fails, browsers will fail even if HTTP checks look green. --- -**Proxy God** — *not because it’s polite. Because it runs.* +**Proxy God** +**Built to keep moving when proxies die. Built to fail closed when trust dies.**