drjones/proxy-god
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
792b320257eb20eedeb9151ca77226a2f9af0ecc
proxy-god/docs/OPERATOR_RUNBOOK.md
Dr Jones 792b320257
Some checks failed
CI / Test Python 3.10 (push) Has been cancelled
Details
CI / Test Python 3.11 (push) Has been cancelled
Details
CI / Test Python 3.12 (push) Has been cancelled
Details
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>
2026-05-21 23:49:02 -07:00

3.5 KiB
Raw Blame History

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:

# 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

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

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:

    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:

$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:

explorer "$env:LOCALAPPDATA\ProxyChainManager"
Reference in New Issue View Git Blame Copy Permalink