first commit

docs/OPERATOR_RUNBOOK.md

@@ -0,0 +1,128 @@
+# 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"
+```