proxy-god/docs/AUDIT_FINDINGS.md

Proxy God — Audit Findings

Audit date: 2026-05-21
Scope: Production-readiness gaps, README cross-check, automated tests
Tests run: python -m unittest discover -s tests -v → 47 passed, 0 failed (~25s)

---

Executive Summary

Category	P0	P1	P2	Total
Production readiness gaps (this pass)	15	46	16	77
Critical bugs (separate bug-hunt pass)	—	—	—	pending / parallel

Test status: Core pure-logic modules are covered (config, leak_detect, validator timing, chain_map, browser persona). No automated tests touch service.py, firewall.py, gost_util.py, sysproxy.py, or app.py.

Top 5 P0 production blockers

1. No CI/CD — nothing runs tests or build on push/tag (requirements.txt:1-4, no .github/workflows / .gitea/workflows).
2. No code signing — release .exe is unsigned (ProxyChainManager.spec:70-71).
3. Secrets at rest in plaintext — proxy credentials and signup passwords in %LOCALAPPDATA%\ProxyChainManager\ JSON (config.py:364-368, signup_prep.py:295-296).
4. GOST binary integrity not verified — runtime download with zip magic check only, no SHA256/signature pin (gost_util.py:17-65).
5. Kill-switch recovery gap — outbound BLOCK can persist if process dies mid-run; no standalone recovery tool documented (firewall.py:142-156, service.py:136-143).

---

Production Readiness Gaps

Infrastructure

#	What's missing	Why it matters for prod	Suggested fix	Priority
I-1	No CI/CD pipeline (no GitHub/Gitea workflow YAML in repo)	Regressions ship silently; no reproducible build gate	Add workflow: pip install -r requirements.txt, unittest discover, optional pyinstaller on tag	P0
I-2	No automated test gate on PR/merge	CONTRIBUTING.md says “run tests” but nothing enforces it (CONTRIBUTING.md:9)	Fail CI if python -m unittest discover -s tests fails	P0
I-3	No dependency lockfile (requirements.txt uses >= only)	Non-reproducible builds across machines/time	Generate requirements.lock or pin exact versions in release branch	P1
I-4	PyInstaller not pinned — installed ad hoc in scripts/setup_and_build.ps1:39	Release binaries differ per builder Python/PyInstaller version	Pin pyinstaller==x.y.z in dev requirements; record in release notes	P1
I-5	No release automation — docs/RELEASE_PROCESS.md is manual checklist only	SHA256/commit attachment steps are skipped in practice	Script: build → hash → attach to Gitea release with commit SHA	P1
I-6	No pre-commit / secret scanning	Risk of committing proxy creds or signup JSON from dev machines	gitleaks or similar in CI + pre-commit	P1
I-7	No documented required env vars — MAINTENANCE.md:22 asks for them but none exist	Operators cannot configure corporate proxy, custom data dir, etc.	Document optional LOCALAPPDATA override pattern or explicit env contract	P2
I-8	Stewardship checklists are templates only — all items unchecked in docs/SECURITY_REVIEW.md, docs/PROVENANCE_CHECKLIST.md	Release gate in docs is never enforced	Complete checklists per release or automate in CI	P1

Reliability

#	What's missing	Why it matters for prod	Suggested fix	Priority
R-1	Kill-switch may remain engaged after abnormal exit — fw_disengage() only on stop() / _close() (service.py:136-143, app.py:2877-2886)	Crashed/killed process leaves netsh outbound BLOCK → machine appears “offline”	atexit + signal handlers; ship scripts/disengage_kill_switch.ps1; detect orphan rules at startup	P0
R-2	GOST download without checksum/signature (gost_util.py:49-61)	Supply-chain compromise or CDN swap replaces gost.exe	Pin release URL + publish SHA256; verify before extract; optional minisign	P0
R-3	No settings schema version / migration — load_settings() merges unknown keys silently (config.py:329-361)	Upgrades break or drop fields; no upgrade path for operators	Add settings_version; migration functions per version	P1
R-4	Corrupt settings.json silently reverts to defaults (config.py:335-336)	Operator loses pinned chain/credentials without warning	On parse failure: backup corrupt file, surface UI error, offer restore	P1
R-5	update_settings() while service thread running — no lock around _settings (service.py:112-114, 349+)	Race: health interval / pool refresh reads half-written settings	threading.Lock on settings read/write or restart service on save	P1
R-6	No offline / degraded mode — empty pool sleeps 60s and retries (service.py:402 area)	Air-gapped or CDN-down hosts spin with no cached pool	Persist last-good pool snapshot; UI banner “offline, using cache”	P1
R-7	ChainService thread is daemon (service.py:131-133)	Process exit can abort mid-teardown (proxy/firewall left dirty)	Non-daemon thread + bounded shutdown protocol	P1
R-8	stop() join timeout 15s only (service.py:140-141)	Hung GOST/async loop leaves firewall engaged	Force-kill GOST after timeout; always call fw_disengage() in finally	P0
R-9	Global ThreadPoolExecutors never shut down (service.py:64, pool_ops.py:15)	Interpreter shutdown warnings; resource leaks in long-running tray sessions	shutdown(wait=False) on app exit	P2
R-10	No GOST process watchdog — if GOST dies, behavior depends on loop branch	Silent proxy outage until next health check	Detect proc.poll(); restart or rotate immediately	P1
R-11	Logon scheduled task runs LIMITED (windows_task.py:47-48)	Auto-start cannot engage kill-switch / MAC / HKLM fixes that need Admin	Document “task ≠ full enforcement”; optional elevated task with warning	P1
R-12	No backup/restore for operator data	Reinstall or profile wipe loses chains and signup vault	Export/import ZIP of %LOCALAPPDATA%\ProxyChainManager\	P2
R-13	No rollback to prior release	Bad build bricks operators	Keep previous ProxyChainManager.exe + settings backup; versioned releases	P1

Security

#	What's missing	Why it matters for prod	Suggested fix	Priority
S-1	Plaintext settings.json with embedded proxy auth (config.py:364-368, asdict stores URLs)	Disk theft = credential leak	DPAPI-encrypt sensitive fields or Windows credential locker	P0
S-2	Plaintext signup vault — signup_draft.json, signup_accounts.json (signup_prep.py:252-296)	Passwords/emails readable by any local user/process	Encrypt at rest; redact in logs (partially done for proxy URLs only)	P0
S-3	No TLS/certificate pinning for feed URLs (fetcher.py:11-18)	MITM on jsdivr/GitHub could inject malicious proxy list	Pin certs or use signed offline bundle for sources	P2
S-4	Broad Defender exclusion on entire GOST folder (gost_util.py:23-39)	AV blind spot if folder is poisoned	Exclude only gost.exe; verify hash before exclusion	P1
S-5	ip_check_url and custom sources not URL-validated (config.py:338-340)	Hand-edited JSON could point health checks at internal/metadata endpoints	Allowlist HTTPS hosts; block RFC1918/link-local in validator	P1
S-6	Kill-switch default ON (config.py:186) without mandatory recovery docs in README	Bricked network for non-technical operators	README “emergency disengage” + startup orphan detection	P0
S-7	Always-elevated PyInstaller build (ProxyChainManager.spec:72 uac_admin=True)	Every launch prompts UAC; users may habit-click; not least-privilege	Split “Operator” vs “Enforcer” binaries or manifest optional elevation	P1
S-8	Signup autofill extension writes config into Firefox profile (signup_prep.py:334+)	Local profile theft exposes generated credentials	Document threat model; optional OS-level profile encryption	P1
S-9	No rate limiting on outbound validation fan-out (default concurrency 64, config.py:179)	Can trigger abuse flags on ipify/jsdelivr/proxy sources	Cap per-host concurrency; exponential backoff on 429	P1
S-10	No secrets rotation story	Long-lived proxy passwords in JSON never expire	Export reminder; credential field rotation UX	P2

Observability

#	What's missing	Why it matters for prod	Suggested fix	Priority
O-1	proxy_chain_manager.log has no rotation (app.py:91-98) — unlike gost.log (gost_util.py:98-105)	Long sessions fill disk	RotatingFileHandler or size cap like GOST	P1
O-2	No crash reporting (WER hook, Sentry, minidump)	Field failures are invisible to maintainer	Opt-in crash telemetry with redaction	P1
O-3	Unstructured text logs only	Hard to query in SIEM	Optional JSON log format for file handler	P2
O-4	No metrics (Prometheus/windows perf counters)	Cannot alert on pool size, rotation rate, leak count	Export counters via named pipe or local HTTP if needed	P2
O-5	No external health endpoint	Expected for server apps; desktop app has tray only — gap if headless automation desired	Document N/A for GUI; optional 127.0.0.1:status for scripting	P2
O-6	Broad except Exception: pass in Defender helper (gost_util.py:38-39)	Silent failure to exclude → GOST quarantined with no UI clue	Log warning + surface in Live tab	P1
O-7	UI event queue unbounded (app.py:200)	Log flood can grow memory	queue.Queue(maxsize=N) with drop-oldest policy	P2

Distribution

#	What's missing	Why it matters for prod	Suggested fix	Priority
D-1	No Authenticode signing (ProxyChainManager.spec:70-71 codesign_identity=None)	SmartScreen blocks; enterprise deployment blocked	Sign with cert; document thumbprint in release	P0
D-2	No SHA256 publish step in build script — required by docs/RELEASE_PROCESS.md:10 but setup_and_build.ps1 only copies exe	Users cannot verify download integrity	Emit ProxyChainManager.exe.sha256 in dist/	P1
D-3	UPX compression enabled (ProxyChainManager.spec:66-67)	AV false positives on packed binaries	Disable UPX for release builds	P1
D-4	GOST not shipped in installer — downloaded on first run (gost_util.py:42-65)	First-run requires internet; air-gap fails	Bundle pinned gost.exe in installer or optional offline pack	P1
D-5	No MSI/Inno installer — only raw exe + Desktop copy (setup_and_build.ps1:55-58)	No uninstaller, no Start Menu integration, no upgrade path	Wrap in signed installer with upgrade code	P2
D-6	No in-app auto-update channel	Security patches require manual git pull / rebuild	Check release API + signed delta or full exe	P1
D-7	Version 1.0.0 static (__init__.py:3) — not embedded in Windows file properties	Support cannot map exe → commit	PyInstaller version resource from git tag	P1
D-8	No reproducible build manifest (SBOM)	Supply-chain audits fail	pip freeze + GOST hash in release notes	P1

Documentation

#	What's missing	Why it matters for prod	Suggested fix	Priority
DOC-1	No LICENSE file — LICENSE_STATUS.md:3-9 says “all rights reserved”	Cannot legally redistribute or accept external contributions	Choose SPDX license; add LICENSE	P0
DOC-2	README omits production realities — no mention of: unsigned exe, first-run GOST download, Defender exclusion, kill-switch recovery (README.md:69-114)	Operators misconfigure or panic when network dies	Add “Production deployment” section	P1
DOC-3	README test claim understates gaps — “Covers config… smoke paths” (README.md:124) but no service/firewall/GUI tests	False confidence in release quality	Align README with actual test matrix	P1
DOC-4	CHANGELOG.md Unreleased empty (CHANGELOG.md:5-7)	No user-visible record between tags	Require changelog entry in PR template	P1
DOC-5	No THIRD_PARTY_NOTICES.md for GOST, CustomTkinter, Pystray, Proxifly data	License compliance for binary distribution	Generate notices from pip licenses + GOST MIT	P1
DOC-6	No operator runbook (kill-switch stuck, proxy leak, pool empty)	MTTR high in field	docs/RUNBOOK.md with netsh recovery steps	P0
DOC-7	“Mission-grade” / “fail closed” marketing without SLOs (README.md:5-12)	Enterprise buyers expect defined behavior	Add limitations: public proxy quality, VPN requirement, admin scope	P2
DOC-8	docs/MAINTENANCE.md rate-limit note (MAINTENANCE.md:23) not reflected in product	Release gate incomplete	Implement S-9 or remove claim	P1

Testing

#	What's missing	Why it matters for prod	Suggested fix	Priority
T-1	No CI executing test suite	47 tests only run manually	Wire I-1 to unittest discover	P0
T-2	Zero tests for service.py, firewall.py, gost_util.py, sysproxy.py	Core runtime unverified	Mock subprocess/netsh; test engage/disengage, settings races	P0
T-3	No tests for load_settings / save_settings round-trip	Regression on migration/sanitize	Add TestSettingsPersistence with temp dir	P1
T-4	No frozen-bundle path tests — _MEIPASS branches in signup_prep.py:21-22, chain_map.py:50-51	PyInstaller regressions break map/signup	Test with sys.frozen monkeypatch	P1
T-5	No GUI smoke tests (app.py ~2900 lines)	UI regressions ship every release	Minimal pytest-qt or screenshot smoke on CI Windows runner	P1
T-6	No compileall / lint in pipeline	Syntax errors in rarely-imported modules	Add python -m compileall proxy_chain_manager to CI	P1
T-7	TestFetcher.test_fetch_smoke network-dependent (tests/test_proxy_god.py)	CI flakiness offline	Mark @unittest.skipUnless or mock httpx	P2
T-8	No coverage threshold	Unknown untested lines	coverage run + fail under 60% on core modules	P2

Compliance / Legal

#	What's missing	Why it matters for prod	Suggested fix	Priority
C-1	No SPDX license on repository (LICENSE_STATUS.md)	Blocks open-source and commercial redistribution	Legal review → add LICENSE	P0
C-2	GOST upstream license not bundled in release artifact	Binary distribution obligation	Include go-gost LICENSE in installer	P1
C-3	Signup presets target third-party ToS (signup_prep.py:37-164)	Automation/autofill may violate site policies	Disclaimer in UI; operator assumes liability	P1
C-4	Provenance checklist incomplete (docs/PROVENANCE_CHECKLIST.md all [ ])	docs/ROADMAP.md:14 blocks “first verified release”	Complete before v1.0 tag	P1
C-5	No privacy notice for local JSON stores	GDPR-style transparency if EU operators	Short privacy section: what is stored where	P1

Operator Experience

#	What's missing	Why it matters for prod	Suggested fix	Priority
OP-1	No emergency kill-switch disengage UX — must know netsh or restart app elevated (firewall.py:149-156)	#1 support incident when chain crashes	Tray item “Disengage firewall”; standalone script	P0
OP-2	“Run as Admin” relaunch closes app (app.py:347-350)	Loses unsaved UI state; confusing flow	Relaunch with --elevate handoff file	P1
OP-3	Kill-switch skipped silently when non-admin (service.py:328-330)	User believes they are “fail closed” but are not	Prominent banner when not admin + kill-switch ON	P1
OP-4	No settings export/import	Machine migration painful	JSON export with optional encryption	P2
OP-5	No first-run wizard (GOST download, VPN check, admin recommendation)	High abandonment on first failure	Step-through: VPN → Admin → Test pool	P1
OP-6	Close button minimizes to tray only (app.py:2888) — good for daemon, bad if user expects quit	Document; tray “Exit” must disengage FW	Already in tray; add tooltip on X	P2
OP-7	README says “Accept UAC” but spec forces uac_admin (README.md:131, ProxyChainManager.spec:72)	Confusing for non-admin workflows	Document two launch modes	P1
OP-8	No visible “version / build commit” in UI	Support tickets lack context	Show __version__ + git SHA in About	P1
OP-9	Pool refresh hammers external CDNs (default 1800s, 3 sources)	Operator IP banned from jsdivr	Backoff; custom mirror field	P1
OP-10	Ban tester / leak audit results not persisted	Cannot trend ban rate over sessions	Optional CSV export	P2

---

README Claims vs Implementation

README claim	Status	Evidence
“Self-healing… rotate on failure, repeat forever”	Partial	Rotation exists (service.py main loop); no GOST watchdog (R-10)
“Fail closed” kill-switch	Partial	Requires Admin (service.py:328-330); orphan rules possible (R-1)
“Python not required” for exe	OK	PyInstaller one-file build (ProxyChainManager.spec)
“Works with or without VPN”	OK	leak_detect.py VPN-aware modes; tested
“Validation / tests” coverage	Overstated	47 unit tests; no service/firewall/GUI (T-2, DOC-3)
Default kill-switch ON	OK	config.py:186
VM-safe loopback 127.0.0.1	OK	config.py:22-24, normalize_listen_host
Build via setup_and_build.ps1	OK	Script exists; no signing/checksum (D-1, D-2)
Tray red/yellow/green	OK	tray.py, app.py status handlers
QUIC disabled where needed	Verify manually	Browser/sysproxy paths — not covered by unit tests

---

Test Run Notes (2026-05-21)

Ran 47 tests in ~25s — OK

Modules with tests: config, leak_detect, validator, fetcher (network smoke), leak_audit, privacy_lan, browser_identity, chain_map, exit_intel.

Modules without tests: app, service, gost_util, firewall, sysproxy, tray, ban_tester, dns_leak, webrtc_check, fingerprint, artifact_wipe, windows_task, browser_launcher, signup_prep (integration).

---

Recommended Fix Priority (production)

Priority	Focus
P0	CI + tests (I-1, T-1), code signing (D-1), secrets at rest (S-1, S-2), GOST integrity (R-2), kill-switch recovery (R-1, R-8, OP-1, DOC-6), LICENSE (C-1, DOC-1)
P1	Lockfiles, migrations, runbooks, README honesty, integration tests, rate limits, log rotation, third-party notices
P2	Metrics, installer, backup/restore, coverage gates, TLS pinning

---

Bug-hunt findings (critical bugs, edge cases, UI issues) may be appended by a separate audit pass under sections 2–8 above.