proxy-lab 1.0.1__py3-none-any.whl

proxy_lab/android/start-proxy.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+#
+# Start a mitmproxy for the Android emulator: pre-flight checks, one-time
+# device trust setup, then mitmdump — alive only while this script is alive.
+#
+#   ./android/start-proxy.sh                    # stop with Ctrl-C (or kill this script)
+#   AVD=Pixel_10a PORT=8081 ./android/start-proxy.sh
+#
+# The debug build trusts user-installed CAs (see README), so the mitmproxy CA
+# goes into the user trust store — no root remounts, no /system writes,
+# survives reboots. An emulator booted here keeps running after the proxy stops.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROUTER="$(cd "$SCRIPT_DIR/.." && pwd)/local_router.py"
+CONFIG="${PROXY_LAB_CONFIG:-$(cd "$SCRIPT_DIR/.." && pwd)/domains.yaml}"
+MITMPROXY_VERSION="12.2.3"
+MITMDUMP=(uv tool run --from "mitmproxy==$MITMPROXY_VERSION" mitmdump)
+PORT="${PORT:-8080}"
+DEVICE_PROXY="10.0.2.2:${PORT}" # 10.0.2.2 = the host, from the emulator's view
+CERT="$HOME/.mitmproxy/mitmproxy-ca-cert.pem"
+USER_CA_DIR="/data/misc/user/0/cacerts-added"
+BOOT_TIMEOUT="${BOOT_TIMEOUT:-240}"
+LOCK="${TMPDIR:-/tmp}/start-proxy-${PORT}.lock"
+EMULATOR_LOG=""
+
+# Later runs overwrite this. cleanup() only clears the device's proxy setting
+# when no live instance owns the port, so taking over from a running copy
+# doesn't leave the emulator without a proxy.
+printf '%s\n' "$$" >"$LOCK"
+
+info() { printf '  %s %-11s %s\n' "$1" "$2" "$3"; }
+
+fail() {
+  local label="$1" msg="$2" hint
+  shift 2
+  printf '  ✗ %-11s %s\n' "$label" "$msg" >&2
+  for hint in "$@"; do printf '      ↳ %s\n' "$hint" >&2; done
+  exit 1
+}
+
+find_emulator() {
+  adb devices | awk '$2 == "device" && $1 ~ /^emulator-/ { print $1; exit }'
+}
+
+wait_boot() {
+  local deadline=$((SECONDS + BOOT_TIMEOUT))
+  until [ "$(adb shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')" = "1" ]; do
+    [ "$SECONDS" -lt "$deadline" ] || fail 'emulator' "not finished booting after ${BOOT_TIMEOUT}s" \
+      'Watch the emulator window, check: adb devices' \
+      "Log: ${EMULATOR_LOG:-n/a}"
+    sleep 2
+  done
+}
+
+preflight_tools() {
+  local missing=() hints=() c warm_pid t
+  for c in adb uv openssl lsof; do
+    command -v "$c" >/dev/null 2>&1 || missing+=("$c")
+  done
+  if [ ${#missing[@]} -gt 0 ]; then
+    for c in "${missing[@]}"; do
+      # shellcheck disable=SC2016 # hint is copy-paste text — $PATH must stay literal
+      case "$c" in
+        uv) hints+=('uv: brew install uv — https://docs.astral.sh/uv/getting-started/installation/') ;;
+        adb) hints+=('adb: install Android Studio, then export PATH="$PATH:$HOME/Library/Android/sdk/platform-tools" — https://developer.android.com/studio') ;;
+        *) hints+=("$c: not found — check your PATH") ;;
+      esac
+    done
+    fail 'tools' "missing: ${missing[*]}" "${hints[@]}"
+  fi
+  [ -f "$ROUTER" ] ||
+    fail 'tools' 'local_router.py missing (repo root)' 'use a complete checkout of this repo'
+  [ -f "$CONFIG" ] ||
+    fail 'tools' "config missing: $CONFIG" 'use a complete checkout of this repo'
+  # Warm uv's mitmproxy cache so start_proxy's up-poll never races a
+  # first-time download; announce it only when the run is actually slow.
+  "${MITMDUMP[@]}" --version >/dev/null 2>&1 &
+  warm_pid=$!
+  t=0
+  while kill -0 "$warm_pid" 2>/dev/null && [ "$t" -lt 15 ]; do sleep 0.1; t=$((t + 1)); done
+  if kill -0 "$warm_pid" 2>/dev/null; then
+    info '…' 'mitmproxy' "$MITMPROXY_VERSION via uv — downloading (first run)"
+  fi
+  wait "$warm_pid" ||
+    fail 'tools' "uv could not run mitmproxy $MITMPROXY_VERSION" \
+      "check: ${MITMDUMP[*]} --version" \
+      'https://docs.mitmproxy.org/stable/'
+  info '✓' 'tools' 'adb, uv, openssl, lsof'
+}
+
+ensure_host_ca() {
+  if [ ! -f "$CERT" ]; then
+    info '…' 'host CA' 'generating ~/.mitmproxy (first run)'
+    # Any mitmproxy tool mints the CA on startup; port 0 = OS-assigned, no conflicts.
+    "${MITMDUMP[@]}" --listen-port 0 >/dev/null 2>&1 &
+    local gen=$!
+    for _ in {1..25}; do [ -f "$CERT" ] && break; sleep 0.2; done
+    kill "$gen" 2>/dev/null || true
+    wait "$gen" 2>/dev/null || true
+    [ -f "$CERT" ] || fail 'host CA' 'could not generate the mitmproxy CA' \
+      "Run once: ${MITMDUMP[*]}" \
+      'https://docs.mitmproxy.org/stable/concepts/certificates/'
+  fi
+  # shellcheck disable=SC2088 # display path — the literal ~ is what we mean
+  info '✓' 'host CA' '~/.mitmproxy/mitmproxy-ca-cert.pem'
+}
+
+boot_emulator() {
+  local serial pending avd start root_out deadline
+  serial="$(find_emulator)"
+  if [ -n "$serial" ]; then
+    export ANDROID_SERIAL="$serial"
+    info '✓' 'emulator' "$serial running"
+  else
+    pending="$(adb devices | awk '$1 ~ /^emulator-/ && $2 != "device" { print $1; exit }')"
+    if [ -n "$pending" ]; then
+      export ANDROID_SERIAL="$pending"
+      info '…' 'emulator' "waiting for $pending"
+      wait_boot
+      info '✓' 'emulator' "$pending ready"
+    else
+      # shellcheck disable=SC2016 # hint is copy-paste text — $PATH must stay literal
+      command -v emulator >/dev/null 2>&1 || fail 'emulator' 'not on PATH' \
+        'Install Android Studio, then: export PATH="$PATH:$HOME/Library/Android/sdk/emulator" — https://developer.android.com/studio'
+      if [ -n "${AVD:-}" ]; then
+        avd="$AVD"
+        emulator -list-avds 2>/dev/null | grep -Fxq "$avd" ||
+          fail 'emulator' "AVD '$avd' does not exist" "Available: $(emulator -list-avds 2>/dev/null | paste -sd', ' -)"
+      else
+        avd="$(emulator -list-avds 2>/dev/null | sed '/^$/d' | head -1)"
+        [ -n "$avd" ] || fail 'emulator' 'no AVDs found' \
+          'Create one: Android Studio → Tools → Device Manager (Google APIs image)' \
+          'https://developer.android.com/studio/run/managing-avds'
+      fi
+      EMULATOR_LOG="${TMPDIR:-/tmp}/emulator-${avd}.log"
+      start=$SECONDS
+      info '…' 'emulator' "booting $avd"
+      { set -m; } 2>/dev/null # own process group, so Ctrl-C doesn't kill the emulator
+      emulator -avd "$avd" >"$EMULATOR_LOG" 2>&1 &
+      { set +m; } 2>/dev/null
+      serial=''
+      deadline=$((SECONDS + 60))
+      while [ -z "$serial" ]; do
+        serial="$(find_emulator)"
+        [ -n "$serial" ] && break
+        [ "$SECONDS" -lt "$deadline" ] || fail 'emulator' 'never showed up in adb devices' \
+          "Log: $EMULATOR_LOG"
+        sleep 1
+      done
+      export ANDROID_SERIAL="$serial"
+      wait_boot
+      info '✓' 'emulator' "$avd booted in $((SECONDS - start))s"
+    fi
+  fi
+  # Root is only needed to install the CA into the user trust store.
+  root_out="$(adb root 2>&1 || true)"
+  case "$root_out" in
+    *'cannot run as root'*)
+      fail 'root' 'this AVD image refuses adb root' \
+        'Use a "Google APIs" image, not "Google APIs Play Store" — see README.md, Requirements' ;;
+  esac
+  adb wait-for-device
+}
+
+ensure_device_ca() {
+  local hash remote out
+  hash="$(openssl x509 -inform PEM -subject_hash_old -in "$CERT" | head -1)" ||
+    fail 'device CA' "could not hash $CERT"
+  remote="$USER_CA_DIR/${hash}.0"
+  if adb shell "test -f $remote" 2>/dev/null; then
+    info '✓' 'device CA' "${hash}.0 in user store"
+    return 0
+  fi
+  info '…' 'device CA' "installing ${hash}.0 — one reboot, once per AVD"
+  adb shell "mkdir -p $USER_CA_DIR && chmod 755 $USER_CA_DIR" ||
+    fail 'device CA' "cannot create $USER_CA_DIR" 'check: adb root'
+  out="$(adb push "$CERT" "$remote" 2>&1)" ||
+    fail 'device CA' "could not push ${hash}.0" "${out##*$'\n'}"
+  out="$(adb shell "chmod 644 $remote && restorecon $remote $USER_CA_DIR" 2>&1)" || {
+    adb shell "rm -f $remote" >/dev/null 2>&1 || true # never leave an unlabeled cert behind
+    fail 'device CA' 'permissions/SELinux label failed (rolled back)' "${out##*$'\n'}"
+  }
+  adb reboot
+  wait_boot
+  adb root >/dev/null 2>&1 || true # adbd drops back to shell after a reboot,
+  adb wait-for-device # and shell can't read the user trust store
+  adb shell "test -f $remote" 2>/dev/null ||
+    fail 'device CA' 'cert did not survive reboot' "check: adb root && adb shell ls $USER_CA_DIR"
+  info '✓' 'device CA' "${hash}.0 trusted"
+}
+
+set_device_proxy() {
+  local current
+  current="$(adb shell settings get global http_proxy 2>/dev/null | tr -d '\r')" || current=""
+  if [ "$current" = "$DEVICE_PROXY" ]; then
+    info '✓' 'proxy' "$DEVICE_PROXY"
+  else
+    adb shell settings put global http_proxy "$DEVICE_PROXY" ||
+      fail 'proxy' "could not set $DEVICE_PROXY" 'try: adb shell settings get global http_proxy'
+    info '✓' 'proxy' "$DEVICE_PROXY set"
+  fi
+}
+
+free_port() {
+  local pid args pids
+  local stale=() foreign=()
+  pids="$(lsof -t -nP -iTCP:"$PORT" -sTCP:LISTEN 2>/dev/null || true)"
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    args="$(ps -p "$pid" -o args= 2>/dev/null || true)"
+    case "$args" in
+      *mitmdump*) stale+=("$pid") ;;
+      *) foreign+=("$pid ${args:-unknown}") ;;
+    esac
+  done <<<"$pids"
+  if [ ${#foreign[@]} -gt 0 ]; then
+    fail "port $PORT" "used by: ${foreign[*]}" \
+      'Stop that process, or run: PORT=<other> ./android/start-proxy.sh'
+  fi
+  if [ ${#stale[@]} -gt 0 ]; then
+    for pid in "${stale[@]}"; do kill "$pid" 2>/dev/null || true; done
+    for _ in {1..15}; do # give them a moment before forcing
+      lsof -t -nP -iTCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1 || break
+      sleep 0.2
+    done
+    for pid in "${stale[@]}"; do kill -9 "$pid" 2>/dev/null || true; done
+    lsof -t -nP -iTCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1 &&
+      fail "port $PORT" 'still busy after stopping stale proxies' "try: lsof -nP -iTCP:$PORT"
+    info '✓' "port $PORT" "stopped ${#stale[@]} previous run(s)"
+  else
+    info '✓' "port $PORT" 'free'
+  fi
+}
+
+cleanup() {
+  trap - EXIT INT TERM
+  kill "$PROXY_PID" 2>/dev/null || true
+  wait "$PROXY_PID" 2>/dev/null || true
+  local owner=''
+  owner="$(cat "$LOCK" 2>/dev/null || true)"
+  if [ -z "$owner" ] || [ "$owner" = "$$" ] || ! kill -0 "$owner" 2>/dev/null; then
+    adb shell settings delete global http_proxy >/dev/null 2>&1 || true
+    info '✓' 'mitmdump' 'stopped — device proxy cleared'
+  else
+    info '✓' 'mitmdump' "stopped — instance $owner owns the port now"
+  fi
+}
+
+start_proxy() {
+  "${MITMDUMP[@]}" --listen-host 0.0.0.0 --listen-port "$PORT" --set ssl_insecure=true \
+    -s "$ROUTER" &
+  PROXY_PID=$!
+  trap cleanup EXIT
+  trap 'cleanup; exit 130' INT
+  trap 'cleanup; exit 143' TERM
+  local up=''
+  for _ in {1..20}; do
+    lsof -t -nP -iTCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1 && { up=1; break; }
+    kill -0 "$PROXY_PID" 2>/dev/null || break
+    sleep 0.25
+  done
+  if [ -z "$up" ]; then
+    wait "$PROXY_PID" 2>/dev/null || true
+    fail 'mitmdump' "exited before listening on :$PORT" 'the output above says why'
+  fi
+  info '✓' 'mitmdump' "0.0.0.0:$PORT — Ctrl-C to stop"
+  printf '\n'
+  wait "$PROXY_PID"
+}
+
+preflight_tools
+ensure_host_ca
+boot_emulator
+ensure_device_ca
+free_port
+set_device_proxy
+start_proxy

proxy_lab/cli.py

@@ -0,0 +1,40 @@
+# Entry point for `uvx --from git+https://github.com/kibotu/proxy-lab.sh proxy-lab`.
+# The actual work stays in android/ and ios/ — this only dispatches and passes
+# the domains file through.
+import argparse
+import os
+from pathlib import Path
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="proxy-lab",
+        description="Start a mitmproxy for the Android emulator or the iOS simulator.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    start = commands.add_parser(
+        "start", help="run the platform's proxy — stop with Ctrl-C"
+    )
+    start.add_argument(
+        "platform", choices=("android", "ios"), help="which device to proxy"
+    )
+    start.add_argument(
+        "config",
+        nargs="?",
+        metavar="domains.yml",
+        help="domain list to log (default: the bundled domains.yaml)",
+    )
+    args = parser.parse_args()
+
+    if args.config is not None:
+        config = Path(args.config).expanduser()
+        if not config.is_file():
+            parser.error(f"config not found: {config}")
+        os.environ["PROXY_LAB_CONFIG"] = str(config.resolve())
+
+    script = PACKAGE_DIR / args.platform / "start-proxy.sh"
+    # exec: this process becomes the script, so Ctrl-C and the exit code
+    # propagate exactly as if the script had been run directly.
+    os.execvp("bash", ["bash", str(script)])

proxy_lab/domains.yaml

@@ -0,0 +1,5 @@
+# Host suffixes logged as [local_router] … — read by local_router.py,
+# shared by android/ and ios/. Leading dot = subdomains only;
+# without it ("example.com") the apex matches too.
+domains:
+  - ".example.com"

proxy_lab/ios/start-proxy.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Start mitmdump for the iOS simulator with the shared local_router addon.
+# The simulator shares the host's network — no device changes, no root.
+# Stop with Ctrl-C (or kill this script); uv takes the proxy down with it.
+#
+#   ./ios/start-proxy.sh                    # PORT=8081 ./ios/start-proxy.sh
+#
+# Point your debug build at localhost:8080. If HTTPS reports a trust error,
+# install the CA once in the simulator: http://mitm.it
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROUTER="$(cd "$SCRIPT_DIR/.." && pwd)/local_router.py"
+CONFIG="${PROXY_LAB_CONFIG:-$(cd "$SCRIPT_DIR/.." && pwd)/domains.yaml}"
+PORT="${PORT:-8080}"
+MITMPROXY_VERSION="12.2.3"
+MITMDUMP=(uv tool run --from "mitmproxy==$MITMPROXY_VERSION" mitmdump)
+
+fail() {
+  printf '  ✗ %s\n' "$1" >&2
+  exit 1
+}
+
+command -v uv >/dev/null ||
+  fail 'uv not found — brew install uv — https://docs.astral.sh/uv/getting-started/installation/'
+[ -f "$ROUTER" ] ||
+  fail "router missing: $ROUTER — use a complete checkout of this repo"
+[ -f "$CONFIG" ] ||
+  fail "config missing: $CONFIG — use a complete checkout of this repo, or pass an existing domains file"
+
+# exec: this script becomes mitmdump (via uv), so killing it kills the proxy.
+exec "${MITMDUMP[@]}" \
+  --listen-host 0.0.0.0 \
+  --listen-port "$PORT" \
+  --set ssl_insecure=true \
+  -s "$ROUTER"

proxy_lab/local_router.py

@@ -0,0 +1,26 @@
+# Shared by android/ and ios/ — loads the domain list from domains.yaml
+# once at startup. Edit domains.yaml, not this file.
+import os
+from pathlib import Path
+
+import ruamel.yaml
+from mitmproxy import http
+
+# PROXY_LAB_CONFIG is set by the proxy-lab CLI when a domains file is passed;
+# without it, the domains.yaml next to this file (repo checkout or package).
+CONFIG = Path(os.environ.get("PROXY_LAB_CONFIG") or Path(__file__).with_name("domains.yaml"))
+
+with CONFIG.open() as fh:
+    _config = ruamel.yaml.YAML(typ="safe").load(fh) or {}
+LOCAL_DOMAIN_SUFFIXES = tuple(_config["domains"])
+
+
+def request(flow: http.HTTPFlow) -> None:
+    host = flow.request.pretty_host
+
+    if not any(host.endswith(s) for s in LOCAL_DOMAIN_SUFFIXES):
+        return
+
+    # flush: this marker must be visible the moment the request happens —
+    # stdout is block-buffered when redirected (CI logs, | grep pipelines).
+    print(f"[local_router] {flow.request.scheme}://{host}{flow.request.path}", flush=True)

proxy_lab-1.0.1.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: proxy-lab
+Version: 1.0.1
+Summary: One command to see your app's HTTPS traffic: a mitmproxy setup for the Android emulator and the iOS simulator.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# proxy-lab.sh
+
+[![CI](https://github.com/kibotu/proxy-lab.sh/actions/workflows/ci.yml/badge.svg)](https://github.com/kibotu/proxy-lab.sh/actions/workflows/ci.yml)
+[![Release](https://github.com/kibotu/proxy-lab.sh/actions/workflows/release.yml/badge.svg)](https://github.com/kibotu/proxy-lab.sh/actions/workflows/release.yml)
+[![GitHub Release](https://img.shields.io/github/v/release/kibotu/proxy-lab.sh)](https://github.com/kibotu/proxy-lab.sh/releases)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](#requirements)
+[![Shell](https://img.shields.io/badge/shell-bash-informational)](#project-layout)
+
+**See your app's HTTPS traffic with one command.** proxy-lab.sh starts [mitmproxy](https://www.mitmproxy.org/) for the **Android emulator** and the **iOS simulator**, and it does the certificate work for you. No `/system` remount, no Magisk, no stale proxy setting.
+
+```bash
+# iOS
+uvx --from git+https://github.com/kibotu/proxy-lab.sh proxy-lab start ios domains.yml
+
+# android
+uvx --from git+https://github.com/kibotu/proxy-lab.sh proxy-lab start android domains.yml
+```
+
+![proxy-lab.sh terminal output showing intercepted HTTPS requests](docs/teaser.png)
+
+## Contents
+
+- [Quickstart](#quickstart) — [Android](#android), [iOS](#ios)
+- [Choose the domains to log](#choose-the-domains-to-log)
+- [Options](#options)
+- [Run from a clone](#run-from-a-clone)
+- [Requirements](#requirements)
+- [Troubleshooting](#troubleshooting)
+- [How it works](#how-it-works)
+- [Why Android needs this](#why-android-needs-this)
+- [Scope and alternatives](#scope-and-alternatives)
+- [Versions and releases](#versions-and-releases)
+- [Project layout](#project-layout)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
+## Quickstart
+
+Install [uv](https://docs.astral.sh/uv/). It runs mitmproxy at a pinned version for you, so there is no Python setup and nothing global to install:
+
+```bash
+brew install uv
+```
+
+Then follow the path for your platform. The first run takes a few minutes, because it downloads mitmproxy and prepares the device. Later runs start in seconds.
+
+### Android
+
+**1. Let your debug build trust user-installed certificates.** Android apps ignore them by default, so your app must opt in. Add `res/xml/network_security_config.xml` to your **debug** source set:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+   <debug-overrides>
+      <trust-anchors>
+         <certificates src="user" />
+      </trust-anchors>
+   </debug-overrides>
+</network-security-config>
+```
+
+Point to it from the `<application>` tag in `AndroidManifest.xml`:
+
+```xml
+<application
+        android:networkSecurityConfig="@xml/network_security_config"
+        ... >
+```
+
+`<debug-overrides>` applies only when the build is debuggable, so it cannot weaken a release build. Keep it in the debug source set anyway. See the [network security config docs](https://developer.android.com/privacy-and-security/security-config) and [why this is necessary](#why-android-needs-this).
+
+**2. Start the proxy:**
+
+```bash
+uvx --from git+https://github.com/kibotu/proxy-lab.sh@ proxy-lab start android
+```
+
+The script checks your tools, reuses a running emulator or boots one, installs the mitmproxy CA into the user trust store, and sets the emulator proxy to `10.0.2.2:8080`. The CA install reboots the emulator one time per AVD.
+
+**3. Start your debug build.** Requests print in the terminal as they happen.
+
+**4. Press `Ctrl-C`.** The proxy stops and the emulator's proxy setting is cleared. The emulator keeps running.
+
+> Use a **Google APIs** AVD image. "Google APIs Play Store" images refuse `adb root`, and the CA install needs it.
+
+### iOS
+
+**1. Start the proxy:**
+
+```bash
+uvx --from git+https://github.com/kibotu/proxy-lab.sh@ proxy-lab start ios
+```
+
+**2. Send the simulator's traffic through it.** The simulator uses your Mac's network stack, so it has no proxy setting of its own. Pick one:
+
+- **System proxy** — **System Settings → Network → (your interface) → Details → Proxies**. Turn on *Web proxy* and *Secure web proxy*, both `127.0.0.1` port `8080`. Every app on the Mac goes through the proxy while this is on.
+- **App only** — point your debug build at `localhost:8080`, for example with `URLSessionConfiguration.connectionProxyDictionary`.
+
+**3. Trust the CA, one time per simulator:**
+
+1. Open [`mitm.it`](http://mitm.it) in the simulator's Safari and download the profile. The page is served by the proxy, so step 2 must work first.
+2. Install it: **Settings → General → VPN & Device Management**.
+3. Turn on full trust: **Settings → General → About → Certificate Trust Settings**.
+
+**4. Start your app.** Press `Ctrl-C` to stop the proxy.
+
+No root, no reboot, nothing to undo in the app.
+
+## Choose the domains to log
+
+Every request goes through the proxy and appears in the mitmdump output. On top of that, hosts you list get a `[local_router]` line, which makes your own API easy to find in a busy log.
+
+Write your list in a YAML file:
+
+```yaml
+domains:
+   - ".example.com"   # subdomains only: api.example.com yes, example.com no
+   - "acme.dev"       # the host itself and its subdomains
+```
+
+Entries match the end of the host name. A leading dot excludes the apex domain.
+
+Pass the file as the last argument:
+
+```bash
+uvx --from git+https://github.com/kibotu/proxy-lab.sh@ proxy-lab start android my-domains.yml
+```
+
+Without an argument you get the [bundled `domains.yaml`](domains.yaml), which lists `.example.com` only. Keep your own file next to your project and commit it, so the team logs the same hosts.
+
+## Options
+
+The command surface is one line:
+
+```
+proxy-lab start <android|ios> [domains.yml]
+```
+
+Environment variables cover the rest:
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `PORT` | `8080` | Port for mitmdump on the host. Android points the emulator at `10.0.2.2:$PORT`. |
+| `AVD` | first entry of `emulator -list-avds` | AVD to boot when none is running. Android only. |
+| `BOOT_TIMEOUT` | `240` | Seconds to wait for the emulator to finish booting. Android only. |
+| `PROXY_LAB_CONFIG` | bundled `domains.yaml` | Path to your domains file. Same effect as the argument above. |
+
+```bash
+PORT=8081 AVD=Pixel_10a uvx --from git+https://github.com/kibotu/proxy-lab.sh@ proxy-lab start android
+```
+
+If you run this daily, install the command once and keep the line short:
+
+```bash
+uv tool install git+https://github.com/kibotu/proxy-lab.sh@
+proxy-lab start android
+```
+
+Move to a newer version with `uv tool install --force git+https://github.com/kibotu/proxy-lab.sh@<X.Y.Z>`.
+
+## Run from a clone
+
+Use a clone when you change the scripts or the addon:
+
+```bash
+git clone https://github.com/kibotu/proxy-lab.sh
+cd proxy-lab.sh
+./android/start-proxy.sh        # or ./ios/start-proxy.sh
+```
+
+The scripts are the same code that `uvx` runs. Edit [`domains.yaml`](domains.yaml) in place, or set `PROXY_LAB_CONFIG`. All environment variables above apply.
+
+## Requirements
+
+- **macOS.** The iOS Simulator needs Xcode, and Xcode needs macOS. The Android script uses portable tools only, so Linux probably works, but nobody tests it there.
+- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — `brew install uv`. It runs [mitmproxy](https://www.mitmproxy.org/) at a pinned version. No Python install of your own is necessary.
+- **Android:** [Android Studio](https://developer.android.com/studio) with `adb` and `emulator` on your `$PATH`, plus a Google APIs AVD. Your debug build must trust user CAs, as shown in [the Android quickstart](#android).
+- **iOS:** Xcode.
+
+The Android script also uses `openssl` and `lsof`, which macOS ships. It tells you if something is missing, and it prints the command that fixes it.
+
+## Troubleshooting
+
+The scripts fail loudly, and the error line usually contains the answer. These are the recurring ones:
+
+- **`adbd cannot run as root in production builds`** — the AVD uses a Play Store image. Check with `grep image.sysdir ~/.android/avd/<AVD>.avd/config.ini` and create a Google APIs AVD instead.
+- **`net::ERR_CERT_AUTHORITY_INVALID`** — the app does not trust the CA. Confirm the [network security config](#android) is in the build you are running, and that it is a debug build. To reinstall the certificate: `adb root && adb shell rm /data/misc/user/0/cacerts-added/<hash>.0`, then run the script again. Restart the app afterwards, because a running process keeps its trust anchors.
+- **Requests time out** — the proxy stopped while the emulator still points at it. `adb shell settings get global http_proxy` prints `10.0.2.2:8080` when the script runs, and `null` after a clean exit. If it prints an address and nothing listens, start the script again, or clear it with `adb shell settings delete global http_proxy`.
+- **"No internet connection" while proxied** — Android's connectivity check does not trust user CAs, so the system reports partial connectivity. Your app traffic works. Ignore it.
+- **Nothing shows up on iOS** — the simulator does not use the proxy. Go back to [step 2 of the iOS quickstart](#ios).
+- **No `[local_router]` lines** — the host is not in the domains file in use. See [Choose the domains to log](#choose-the-domains-to-log).
+
+Still stuck? [Open an issue](https://github.com/kibotu/proxy-lab.sh/issues) with the exact error line.
+
+## How it works
+
+```
+Android emulator ──▶ 10.0.2.2:$PORT ─┐
+                                     ├──▶ mitmdump on the host ──▶ upstream, or 127.0.0.1 for local dev domains
+iOS simulator ─────▶ 127.0.0.1:$PORT ┘
+```
+
+`mitmdump` terminates TLS with its own CA, prints what it sees, and forwards the request. `10.0.2.2` is the host address as the emulator sees it ([emulator networking](https://developer.android.com/studio/run/emulator-networking)). Name resolution happens on the host, so an `/etc/hosts` entry sends a dev domain to a server on your machine.
+
+`local_router.py` is a [mitmproxy addon](https://docs.mitmproxy.org/stable/addons/overview/). The name promises more than it delivers: it logs matching hosts, it does not route. Both platforms load it.
+
+## Why Android needs this
+
+Since Android 7, apps that target API 24 and higher ignore user-installed CAs unless they opt in ([Android Developers Blog](https://android-developers.googleblog.com/2016/07/changes-to-trusted-certificate.html)). The common answer is to put the CA in the *system* store. That answer keeps getting more expensive:
+
+- The [mitmproxy guide](https://docs.mitmproxy.org/stable/howto/install-system-trusted-ca-android/) hashes the certificate by hand, remounts `/system`, and needs `-writable-system` on every boot.
+- Android 14 moved the store into the immutable Conscrypt APEX ([AOSP](https://source.android.com/docs/core/ota/modular-system/conscrypt)). That mount is private per process, so even root edits stay invisible to apps ([HTTP Toolkit](https://httptoolkit.com/blog/android-14-breaks-system-certificate-installation/)). The known workarounds are a Magisk module, or `nsenter` into Zygote's mount namespace.
+
+proxy-lab.sh takes the other door: your debug build opts into the **user** store, and the script installs the CA there (`/data/misc/user/0/cacerts-added/`). That needs `adb root` once and one reboot per AVD. The certificate survives later reboots. Release builds are unaffected.
+
+The second half of the problem is routing. The emulator must point at `10.0.2.2`, not `localhost`, through a setting that goes stale in silence. The script writes that setting after it owns the port, and clears it on exit.
+
+iOS has neither problem. The iOS side is a thin mitmdump wrapper, and this repo will not pretend otherwise.
+
+What you get for the Android run:
+
+| Step | Behaviour |
+| --- | --- |
+| Tools | Checks `adb`, `uv`, `openssl`, `lsof` and the addon, with install hints. Warms the mitmproxy download. |
+| Host CA | Generates `~/.mitmproxy/` on the first run. |
+| Emulator | Reuses a running emulator, or boots one and waits for it. |
+| Device CA | Installs the certificate if it is missing. One reboot, one time per AVD. Rolls back a failed install. |
+| Port | Stops stale proxies from earlier runs. Refuses to touch a process it does not own. |
+| Proxy setting | Writes `10.0.2.2:$PORT` after the port is confirmed. Clears it on exit. |
+
+Re-run it as often as you want. The steps are idempotent.
+
+## Scope and alternatives
+
+Out of scope, on purpose:
+
+- **Physical devices.** Emulator and simulator only.
+- **Release builds.** They do not trust user CAs, and that is correct.
+- **Certificate pinning.** A pinning app rejects the proxy CA. Turn pinning off in debug builds, or use a pin bypass.
+- **Response rewriting and mocking.** mitmproxy does all of that. Write your own [addon](https://docs.mitmproxy.org/stable/addons/overview/) next to `local_router.py`.
+
+If you need those, or a GUI, look at [HTTP Toolkit](https://httptoolkit.com/), [Proxyman](https://proxyman.io/), or [Charles](https://www.charlesproxy.com/). proxy-lab.sh stays a small, scriptable, reviewable pile of bash instead.
+
+## Versions and releases
+
+- **mitmproxy** is pinned to `12.2.3` inside the scripts, so the whole team sees the same behaviour.
+- **proxy-lab.sh** is pinned by you: `@1.0.0` in the `uvx` command. Without a tag you get `main`. Put the pinned command in your project README or a Makefile, and the team runs one version.
+- Tags are `X.Y.Z`, with no `v` prefix. A tag push builds the wheel and sdist at that version and publishes a [GitHub Release](https://github.com/kibotu/proxy-lab.sh/releases). [CHANGELOG.md](CHANGELOG.md) has the per-version detail.
+
+## Project layout
+
+| Path | What it is |
+| --- | --- |
+| [`android/start-proxy.sh`](android/start-proxy.sh) | The full Android flow: checks, CA, emulator, port, proxy setting, mitmdump. |
+| [`ios/start-proxy.sh`](ios/start-proxy.sh) | mitmdump with the shared addon. |
+| [`local_router.py`](local_router.py) | mitmproxy addon. Logs hosts from the domains file. |
+| [`domains.yaml`](domains.yaml) | Default host list. |
+| [`proxy_lab/cli.py`](proxy_lab/cli.py) | The `proxy-lab` entry point for `uvx`. Dispatches to the scripts. |
+| [`.github/workflows/ci.yml`](.github/workflows/ci.yml) | shellcheck, plus a proxy smoke test on macOS and Ubuntu. |
+
+## Contributing
+
+Issues and pull requests are welcome, in particular real failure modes the pre-flight checks miss.
+
+Run [shellcheck](https://www.shellcheck.net/) on the scripts before you push, because CI does. Add notable changes to [CHANGELOG.md](CHANGELOG.md) under `Unreleased`.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).
+
+## Support
+
+If proxy-lab.sh saved you an afternoon, or one `ERR_CERT_AUTHORITY_INVALID` hunt, consider [buying me a coffee](https://buymeacoffee.com/kibotu).

proxy_lab-1.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+proxy_lab/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxy_lab/cli.py,sha256=CTzYd66l3gsS6C3R-FklSA8gZrHR_evDsqCy3HsxZOg,1432
+proxy_lab/android/start-proxy.sh,sha256=xave6zaFQgPAYR_CxODTDzDTQNDAybOVPQN8BHk3kXo,10913
+proxy_lab/domains.yaml,sha256=hC1-omwcxDROW1dlgp__H2tzlYVRzngKF3iXrCS4H3Q,215
+proxy_lab/ios/start-proxy.sh,sha256=HIhzOBQXdbV9pgfMOwrXP2vh_bwZZ5tRgfGY_xRisY0,1372
+proxy_lab/local_router.py,sha256=TKTbtU3k6Ps8m7JJ1U1nyuJFqb3tOxx_LMpNFMBSWr0,999
+proxy_lab-1.0.1.dist-info/METADATA,sha256=woJQopnQfvm0klyYK8nfgDlzvRjkX8aNSe6JQiZ_Y5I,15158
+proxy_lab-1.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+proxy_lab-1.0.1.dist-info/entry_points.txt,sha256=0VKG3FLp8EEJmOQhGxjwD4v3ZULib-9ECtl2G9QDQ0I,49
+proxy_lab-1.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+proxy_lab-1.0.1.dist-info/RECORD,,

proxy_lab-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

proxy_lab-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proxy-lab = proxy_lab.cli:main

proxy_lab-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.