proxy-god/README.md

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