From f77a9570e973dda7247c653754e62d5a9a895658 Mon Sep 17 00:00:00 2001 From: srdusr <99972264+srdusr@users.noreply.github.com> Date: Thu, 2 Apr 2026 20:55:00 +0200 Subject: Per-OS CA install instructions (mitmuxd -install-ca) Trusting the CA was previously "import ca.pem into whatever's making the requests" with no further help. -install-ca generates the CA if needed and prints copy-pasteable, OS-specific steps, then exits without starting the proxy. Deliberately instructions-only, never auto-executing anything: Linux trust-store tooling varies enough across distros (trust vs update-ca-trust vs update-ca-certificates) that guessing wrong and running the wrong command unattended is worse than asking, and installing a root CA is a system-wide trust change affecting every TLS connection on the machine, not just mitmux's own traffic - running the printed command themselves keeps the user in control of that. internal/ca/install.go: InstallInstructions(goos, caPath) dispatches by OS. Linux detects trust (p11-kit - Arch, also on Fedora) / update-ca-trust (RHEL/Fedora/CentOS) / update-ca-certificates (Debian/Ubuntu/Gentoo) via PATH lookup and prints whichever is actually present, plus separate certutil/NSS instructions for Firefox/Chrome's own certificate store (which doesn't always follow the system trust store on Linux). macOS (security add-trusted-cert) and Windows (certutil -addstore / Import-Certificate) are implemented from each platform's standard documented tooling but not verified live - no macOS/Windows machine was available to test against, unlike Linux. commandExists is a package var (not a direct exec.LookPath call) so tests can fake which tools are "present" and exercise every detection branch deterministically, independent of what's actually installed on whatever machine runs `go test`. Verified live: built mitmuxd, ran -install-ca against a throwaway CA dir on this (Arch Linux) machine - correctly detected `trust` and `certutil` on PATH and printed accurate commands, confirmed the CA files were actually generated, confirmed no proxy/daemon process was left running (exits immediately after printing), and confirmed running it a second time reuses the existing CA (identical file hash) rather than regenerating. go build/vet/gofmt/test/mod tidy all clean. --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 67536c7..f65e3fe 100644 --- a/README.md +++ b/README.md @@ -94,8 +94,18 @@ go build -o bin/mitmux ./cmd/mitmux 2. **Trust the CA.** To intercept HTTPS without constant certificate warnings, import `ca.pem` into whatever's making the requests - your browser's certificate store, `curl --cacert`, a mobile device's - trusted-certificate settings, etc. (Automated per-OS trust-store - installation isn't implemented yet - see `PLAN.md`.) + trusted-certificate settings, etc. For copy-pasteable, OS-specific + steps (Linux: whichever of `trust`/`update-ca-trust`/ + `update-ca-certificates` is actually on your system, plus Firefox's + own NSS store; macOS: Keychain; Windows: `certutil`/PowerShell), run: + + ```sh + ./bin/mitmuxd -install-ca + ``` + + This only prints commands - it never runs anything against your + trust store itself. Installing a root CA is a system-wide trust + change, so you run the printed command yourself. 3. **Point a client at the proxy.** e.g.: @@ -316,7 +326,8 @@ reasoning behind each: - Match-and-replace: headers only, no body rules yet - Intruder: Sniper attack only (no battering ram / pitchfork / cluster bomb), sequential sending, capped at 1000 requests per attack -- No automated CA installation into OS/browser trust stores +- `mitmuxd -install-ca` prints per-OS trust-store install steps; it + never runs them for you (see Quick start above for why) - No WebSocket interception - No client (mutual-TLS) certificate support - No active or passive vulnerability scanning, no plugin system - this -- cgit v1.2.3