proxy-god/README.md

# Proxy God

**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 → VPN (outer tunnel) → Hop 1 → Hop 2 → … → Last hop → Internet
```

---

## What it does (the short version)

| 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+** 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

---

## Clone / pull → one build script → Desktop

Typical flow:

1. **Clone** (or `git pull` if you already have the 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:
   ```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:
   ```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) |

After a successful build, if the shortcut is missing but the exe exists, you can recreate it:

```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)

```cmd
cd proxy-god
pip install -r requirements.txt
python run.py
```

**Administrator** = full kill-switch. No admin = still runs; firewall enforcement steps aside.

### Self-test (core logic, no GUI)

```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).

---

## Run it like you mean it

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

---

## Chain Builder (where you get surgical)

- **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 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) |

---

## Stack (for people who read code)

```
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
```

---

## 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",...}, ...]`.

---

## Reality check (read this)

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