Transparent proxy + one-command mobile capture setup#15
Merged
Conversation
Ports the transparent-listener work from #11 onto current main (three subsequent PRs diverged too far to rebase) and adds an orchestrator tool that wires the whole mobile-capture flow through proxy-ap-card. Changes - state.ts: ProxyManager gains startTransparent / stopTransparent / isTransparentRunning / getTransparentPort / getTransparentStatus and an internal buildAndStartTransparent. stop() now stops the transparent listener first. rebuildMockttpRules() rebuilds both listeners so rule changes stay in sync. setupEventListeners(server, source) stamps each CapturedExchange with source: "explicit" | "transparent". pushTraffic increments a dedicated transparentTrafficCount. - tools/transparent.ts: new MCP tools proxy_start_transparent, proxy_stop_transparent, proxy_transparent_status. - tools/traffic.ts: proxy_list_traffic gains source_filter and each summary carries a source field. - interceptors/android-adb.ts: cert injection overhaul. Stages existing certs into /data/local/tmp/cacerts_staging before the tmpfs overlay (prevents the wipe on Android 14-16), unstacks prior overlays, then writes the overlay into zygote's mount namespace via nsenter so already-running apps see the cert after a force-stop. - tools/mobile.ts: new MCP tools proxy_mobile_setup, proxy_mobile_teardown, proxy_mobile_detect_iface. Auto-detects the cdc_ncm USB interface (proxy-ap-card firmware), starts both listeners, optionally injects the CA via AndroidAdbInterceptor, and emits a sudo-runnable script with iptables/sysctl/nmcli commands. MCP can't sudo cleanly, so the tool returns the script path rather than trying to run it. - test/integration/transparent-mode.test.ts, test/integration/transparent_ap_test.sh: coverage for the new lifecycle + end-to-end integration helper. - README.md: new Mobile Capture section with the one-command flow and a Transparent / Mobile Capture (6) row in the tool reference table. Verified - npm run build clean. - npm test: 98/100 (the 2 failures — fingerprint runtime preflight, HAR replay — pre-exist on main). - End-to-end test on Pixel + proxy-ap-card + SHEIN: transparent listener captured HTTPS exchanges with source="transparent" and ja3/ja4 recorded, CA was trusted by apps forked from zygote. Not taken from #11: humanizer, devtools, chrome interceptor, cdp-utils, resources changes — PRs #12-14 have better versions on main.
Restructure the Mobile Capture section with: - Prerequisites (laptop deps, hardware options, Android root requirement) - First-time walkthrough (6 numbered steps from flashing to first capture) - Subsequent-session shortcut (skip cert, just re-run iptables) - Full parameter table for proxy_mobile_setup - Step-by-step verification checklist with exact commands - Troubleshooting table covering the symptoms hit in practice (cdc_ncm missing, iptables not wired, cert not trusted, partial capture, non-standard ports, flaky wireless ADB) - Limitations section (cert pinning, Chrome's own CA bundle, QUIC, native TLS pinning, root requirement) — makes failure modes explicit so users don't spend hours debugging server-side issues.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
main. PRs Replace chrome-launcher + CDP with cloakbrowser + Playwright (v2.0.0) #12-14 landed since the fork, so the transparent-specific slice is applied by hand (state.ts, tools/transparent.ts, tools/traffic.ts source_filter, interceptors/android-adb.ts cert-injection overhaul, transparent integration tests).proxy_mobile_setup/proxy_mobile_teardown/proxy_mobile_detect_ifacetool trio that turns "plug in proxy-ap-card → run one thing → phone traffic is captured" into a single MCP call. Auto-detects thecdc_ncmiface, starts both listeners, injects the CA viaAndroidAdbInterceptor, and emits a sudo-runnable iptables/sysctl/nmcli script (MCP can't sudo cleanly, so the script is emitted rather than executed — auditable and distro-portable).What's NOT taken from #11
Everything under
src/humanizer/,src/devtools/,src/cdp-utils.ts,src/interceptors/browser.ts,src/interceptors/chrome.ts,src/resources.ts,src/tools/devtools.ts,src/tools/humanizer.ts,src/tools/interceptors.ts. PRs #12-14 have better versions onmain.Test plan
npm run build— cleannpm test— 98/100 pass; 2 failures (checks fingerprint runtime preflight,imports HAR and replays entries) pre-exist onmain(92/94 there too)test/integration/transparent-mode.test.ts— 4/4 pass (start/stop, double-start rejection, status merge, shared shutdown)source: "transparent", JA3/JA4 recorded🤖 Generated with Claude Code