fix: address P0/P1/P2 audit findings — security, reliability, CI, docs
P0 - Critical: - config.py: add _mask() credential-redaction helper, SETTINGS_SCHEMA_VERSION, plaintext-storage warning; corrupt settings.json backed up before defaults - gost_util.py: pin SHA256 for gost_3.2.6_windows_amd64.zip; verify before extraction; _add_defender_exclusion now logs warning on failure - firewall.py: add emergency_disengage() for atexit/signal use - service.py: register fw_emergency_disengage via atexit + SIGTERM/SIGINT; stop() calls emergency_disengage if thread hangs past 15s timeout - app.py: wrap main() in top-level except with CTk error dialog + log - LICENSE: add MIT license file P1 - Important: - app.py: switch to RotatingFileHandler (5 MB / 3 backups) - config.py: settings_version + migrate(); save_settings() writes .bak before overwrite; _is_safe_https_url() strips RFC-1918 sources/ip_check_url - service.py: threading.Lock on _settings; _signal_handler; graceful stop - requirements.txt: pin exact versions; add cryptography==48.0.0 - .gitignore: add settings.json, credential JSON files, screenshot noise - tray.py, dns_leak.py, gost_util.py: replace bare except:pass with logging - CHANGELOG.md: document all session changes P2 - Nice to have: - .github/workflows/test.yml: CI on Python 3.10/3.11/3.12 windows-latest - run.py: --version / -V flag - docs/OPERATOR_RUNBOOK.md: emergency disengage, proxy leak, GOST, settings Tests: 47/47 passed (python -m unittest discover -s tests -v) Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
119
docs/OPERATOR_RUNBOOK.md
Normal file
119
docs/OPERATOR_RUNBOOK.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 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.
|
||||
|
||||
### 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"
|
||||
```
|
||||
Reference in New Issue
Block a user