# Proxy God — Operator Runbook

**Version:** 1.0  
**Last updated:** 2026-05-21

---

## Emergency: Firewall Kill-Switch Stuck (Network Appears Offline)

If the application crashes or is force-killed while the kill-switch is engaged,
outbound traffic will remain blocked.  Follow these steps to restore connectivity.

### Option 1 — Run the standalone disengage script (fastest)

Open an **elevated** (Run as Administrator) PowerShell terminal and run:

```powershell
# Remove all PCM_ firewall rules
netsh advfirewall firewall delete rule name=all
# Restore default outbound policy
netsh advfirewall set allprofiles firewallpolicy blockinbound,allowoutbound
```

### Option 2 — Restart the application elevated

1. Right-click `ProxyChainManager.exe` → **Run as administrator**.
2. The application detects orphan firewall rules on startup and removes them.
3. Click **Stop** if the service does not start, to force disengage.

### Option 3 — Restart Windows Firewall service

```powershell
Restart-Service -Name MpsSvc -Force
```

This resets all runtime firewall state (not persistent rules).  You may still
need to remove the `PCM_*` rules afterward with Option 1.

### How the application handles this automatically

`firewall.py` exposes `emergency_disengage()`, which is registered via
`atexit` and `signal.SIGTERM`/`SIGINT` in `service.py`.  A clean exit or
SIGTERM will call `emergency_disengage()` automatically, removing all
`PCM_*` rules and restoring `allowoutbound` before the process terminates.
Only a hard kill (`SIGKILL`, power loss, BSOD) can bypass this handler —
in those cases use Option 1 or Option 2 above.

### Verify rules are gone

```powershell
netsh advfirewall firewall show rule name=all dir=out | Select-String "PCM_"
# Should return no output when clean
```

---

## Emergency: Proxy Leak Detected

If the Live tab reports a leak (exit IP matches your real IP or VPN IP):

1. Click **Rotate Now** to pick fresh proxies.
2. If leaks persist, click **Stop**, then re-enable the kill-switch and click **Start**.
3. Check the pool size — if < 5 proxies, force a full pool refresh by stopping
   and restarting the service.
4. Enable VPN before starting if leak detection mode is "strict (exact IP)" —
   a VPN provides a larger subnet mask for the leak check.

---

## Empty Pool / CDN Down

If every pool refresh returns 0 proxies:

1. Check internet connectivity (browser → any site through system proxy OFF).
2. Verify the proxy source URLs in **Settings** are reachable.
3. The default sources use `cdn.jsdelivr.net` — if blocked on your network,
   replace with a mirror or local JSON file (use `file:///path/to/proxies.json`
   format).
4. Temporarily lower `Max candidates` to speed up validation if the CDN is
   slow.

---

## GOST Binary Missing or Quarantined

Symptoms: "GOST setup failed" or "GOST appears quarantined" in the Live log.

1. Check Windows Defender: **Windows Security → Protection history** — look for
   a quarantine event on `gost.exe`.
2. Restore and exclude `gost.exe` from Defender, or re-download by deleting the
   GOST folder:

   ```powershell
   Remove-Item "$env:LOCALAPPDATA\ProxyChainManager\gost" -Recurse -Force
   ```

3. Restart the application — it will re-download and re-verify GOST via SHA256.

---

## Settings Corrupted / Reset to Defaults

A corrupt `settings.json` is automatically backed up to `settings.json.corrupt`
and the application reverts to defaults.

To restore:

```powershell
$dir = "$env:LOCALAPPDATA\ProxyChainManager"
Copy-Item "$dir\settings.json.corrupt" "$dir\settings.json" -Force
```

A rolling backup is also kept at `settings.json.bak` (last successful save).

---

## Log Files

| File | Location | Purpose |
|------|----------|---------|
| `proxy_chain_manager.log` | `%LOCALAPPDATA%\ProxyChainManager\` | Main app log (5 MB × 3 backups) |
| `gost.log` | `%LOCALAPPDATA%\ProxyChainManager\` | GOST process output (512 KB rolling) |

To open the log directory:

```powershell
explorer "$env:LOCALAPPDATA\ProxyChainManager"
```