2ba43c3ff9
Embed Screenshot 2026-05-21 173255.png at the top of README.md so the repo landing page shows the Proxy God v2 UI. Co-authored-by: Cursor <cursoragent@cursor.com>
205 lines
6.2 KiB
Markdown
205 lines
6.2 KiB
Markdown
# Proxy God
|
|
|
|
|
|
|
|
**Mission-grade rotating proxy chains for Windows.**
|
|
**Self-healing. Leak-aware. Aggressive by default.**
|
|
|
|
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 -> ... -> Exit hop -> Internet
|
|
```
|
|
|
|
---
|
|
|
|
## Why it exists
|
|
|
|
- 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.
|
|
|
|
---
|
|
|
|
## Core capabilities
|
|
|
|
| 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 `py` launcher) to build from source
|
|
- Python is **not required** to run the built `.exe`
|
|
- VPN strongly recommended (outer tunnel first)
|
|
|
|
---
|
|
|
|
## Build to Desktop (recommended)
|
|
|
|
1. Clone (or `git pull` in existing repo):
|
|
```cmd
|
|
git clone https://gitea.thetempleofdoom.com/drjones/proxy-god.git
|
|
cd proxy-god
|
|
```
|
|
2. Install Python if needed:
|
|
```cmd
|
|
winget install Python.Python.3.12 --accept-package-agreements --accept-source-agreements
|
|
```
|
|
3. Build:
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup_and_build.ps1
|
|
```
|
|
|
|
Equivalent paths:
|
|
- `build_exe.bat`
|
|
- `FirstRun_Build_And_Install.bat`
|
|
|
|
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
|
|
```
|
|
|
|
---
|
|
|
|
## Run from source (no exe)
|
|
|
|
```cmd
|
|
cd proxy-god
|
|
pip install -r requirements.txt
|
|
python run.py
|
|
```
|
|
|
|
- Run as **Administrator** for full firewall and policy features.
|
|
- Non-admin mode still works, but privileged controls are skipped.
|
|
|
|
---
|
|
|
|
## Validation / tests
|
|
|
|
Core logic test suite:
|
|
```cmd
|
|
python -m unittest discover -s tests -v
|
|
```
|
|
|
|
Covers config sanitization, parser behavior, validator timing behavior, leak checks, and smoke paths.
|
|
|
|
---
|
|
|
|
## Operator quickstart
|
|
|
|
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 notes
|
|
|
|
- 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` | 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) |
|
|
|
|
---
|
|
|
|
## Code layout
|
|
|
|
```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
|
|
|
|
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
|
|
|
|
- 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**
|
|
**Built to keep moving when proxies die. Built to fail closed when trust dies.**
|