1  # Python mitmproxy Transparent Mode (with Egress)
  2  
  3  Transparent mode starts `mitmdump --mode transparent` inside the sidecar and redirects local outbound `TCP 80/443` traffic to the mitmproxy listener via `iptables`. Its core benefits are:
  4  
  5  - **No application changes**: no need to set `HTTP_PROXY`; app traffic is intercepted transparently.
  6  - **Observability and extensibility**: use mitm scripts for header injection, auditing, and debugging.
  7  - **Controlled bypass**: use `ignore_hosts` for pass-through TLS (forward only, no decryption).
  8  
  9  Typical use case: add L7 visibility/processing at the egress boundary without changing the application networking stack.
 10  
 11  ## Quick Setup (Minimum Working Config)
 12  
 13  ### Prerequisites
 14  
 15  - Linux network namespace with `CAP_NET_ADMIN` in the container.
 16  - `mitmdump` installed and `mitmproxy` user present in the image (included in official egress image).
 17  - Client/system trusts the mitm root CA; otherwise HTTPS handshakes will fail.
 18  
 19  ### Enable Transparent MITM
 20  
 21  ```bash
 22  export OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT=true
 23  ```
 24  
 25  By default, mitmproxy listens on `18081` and transparent redirect rules are set automatically.
 26  
 27  ### Common Optional Settings
 28  
 29  ```bash
 30  # Optional: change listening port (default: 18081)
 31  export OPENSANDBOX_EGRESS_MITMPROXY_PORT=18081
 32  
 33  # Optional: enable mitm addon script (e.g., inject request headers)
 34  export OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT=/opt/opensandbox/mitmscripts/add_header.py
 35  
 36  # Optional: bypass decryption for selected domains (semicolon-separated regex list)
 37  export OPENSANDBOX_EGRESS_MITMPROXY_IGNORE_HOSTS='.*\.log\.aliyuncs\.com;.*\.example\.internal'
 38  ```
 39  
 40  ## Configuration Reference
 41  
 42  | Variable | Required | Purpose | Default |
 43  |------|----------|------|--------|
 44  | `OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT` | Yes | Enable transparent mitmproxy (`1/true/on`, etc.) | Disabled |
 45  | `OPENSANDBOX_EGRESS_MITMPROXY_PORT` | No | mitmdump listen port; `iptables` redirects `80/443` here | `18081` |
 46  | `OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT` | No | mitm addon script path (`-s`) | Empty |
 47  | `OPENSANDBOX_EGRESS_MITMPROXY_IGNORE_HOSTS` | No | Host/IP regex list for TLS pass-through (`;` separated) | Empty |
 48  | `OPENSANDBOX_EGRESS_MITMPROXY_CONFDIR` | No | mitm config and CA directory (passed as `--set confdir=`, also used as `HOME`) | Default directory under `/var/lib/mitmproxy` |
 49  | `OPENSANDBOX_EGRESS_MITMPROXY_UPSTREAM_TRUST_DIR` | No | Trust directory for upstream TLS verification (OpenSSL style) | `/etc/ssl/certs` |
 50  
 51  Notes:
 52  
 53  - `OPENSANDBOX_EGRESS_MITMPROXY_IGNORE_HOSTS` means **no decryption**, not “completely bypass mitm process”.
 54  - In transparent mode, mitmproxy generally recommends matching by IP/range; verify SNI/resolve behavior if using domain regex only.
 55  - Before mitm, `iptables`, and CA export are ready, `GET /healthz` returns `503 (mitm not ready)` to prevent premature readiness.
 56  
 57  ## Common Configuration Templates
 58  
 59  ### 1) Enable Transparent MITM Only
 60  
 61  ```bash
 62  export OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT=true
 63  ```
 64  
 65  ### 2) Enable with Header Injection
 66  
 67  ```bash
 68  export OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT=true
 69  export OPENSANDBOX_EGRESS_MITMPROXY_SCRIPT=/opt/opensandbox/mitmscripts/add_header.py
 70  ```
 71  
 72  Built-in example script: `/opt/opensandbox/mitmscripts/add_header.py` (adds `X-OpenSandbox-Egress: 1`).
 73  
 74  ### 3) Bypass Decryption for Specific Domains (e.g. log upload)
 75  
 76  ```bash
 77  export OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT=true
 78  export OPENSANDBOX_EGRESS_MITMPROXY_IGNORE_HOSTS='.*\.log\.aliyuncs\.com'
 79  ```
 80  
 81  ### 4) Use a Fixed CA (consistent fingerprint across replicas)
 82  
 83  If CA files already exist in `confdir`, mitmproxy reuses them instead of regenerating on each startup. Typical paths:
 84  
 85  - `/var/lib/mitmproxy/.mitmproxy/mitmproxy-ca.pem` (private key)
 86  - `/var/lib/mitmproxy/.mitmproxy/mitmproxy-ca-cert.pem` (public cert)
 87  
 88  Ensure correct permissions (for example `mitmproxy:mitmproxy`, private key mode `600`).
 89  
 90  ## Relationship with Policy/DNS
 91  
 92  Transparent mitmproxy does not automatically consume egress `NetworkPolicy`. Domain allow/deny behavior is still determined by DNS + (optional) nft rules. If L7 policy enforcement is needed, implement it in mitm scripts.
 93  
 94  ## Implementation Notes and Limits
 95  
 96  Startup flow (high level):
 97  
 98  1. Start mitmdump as user `mitmproxy`, listening on `127.0.0.1:<port>`.
 99  2. Wait until the local listener is reachable.
100  3. Apply IPv4 `iptables` redirect rules: except loopback and mitmproxy-owned traffic, redirect outbound `80/443` to mitm port.
101  
102  Limits:
103  
104  - Currently IPv4 `iptables` only; IPv6 is not automatically handled.
105  - Non-Linux environments (for example local macOS runtime) are not supported for transparent mode.
106  - Full HTTPS decryption introduces CPU/memory and certificate trust overhead; benchmark before production rollout.