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

Spice up README with mission-control tone.

Browse Source 
Refresh messaging, structure, and section flow while preserving exact build/run commands and operational details.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Indiana Holmes
2026-05-17 22:53:36 -07:00
parent f9c548872b
commit 8258ca0997
1 changed files with 115 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
README.md
View File

@@ -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.**