# mitmux

A terminal-based intercepting proxy for manual pentest work - a
daily-driver alternative to Burp Suite, Caido, or OWASP ZAP that runs
entirely in your terminal, with vi-style modal editing for raw
requests.

mitmux is two binaries: `mitmuxd`, a headless daemon that owns the
proxy listener and the SQLite history database, and `mitmux`, a Bubble
Tea TUI that talks to it over a Unix socket. The daemon keeps running
(and keeps capturing traffic) independently of the TUI - close the UI,
reopen it later, the proxy never stopped.

For the build history, the architectural decisions behind it, and a
list of what's deliberately not implemented (and why), see
[`PLAN.md`](PLAN.md).

## Features

- **Intercepting proxy**: plaintext HTTP passthrough and TLS
  interception (per-host leaf certificates signed by a locally
  generated CA), with HTTP/1.1 and HTTP/2 handled natively and
  independently on the client and upstream legs - a client that only
  speaks HTTP/1.1 and an origin that prefers HTTP/2 both work correctly
  in the same request.
- **History**: every request/response captured to SQLite. Raw wire
  bytes are preserved byte-for-byte on HTTP/1.1 legs (what request
  smuggling and parser-differential analysis actually needs); HTTP/2
  legs - which have no single "raw bytes" representation, being
  multiplexed HPACK-compressed framing - are reconstructed and marked
  as such, never silently presented as exact.
- **Search**: full-text search (FTS5) across headers and bodies, plain
  text just works (`example.com`, `x-forwarded-for`, `192.168.1.1` -
  no quoting needed), plus structured filters: `status:404`,
  `status:4xx`, `status:>=400`, `source:repeater`, `flagged:true`,
  column filters like `host:example.com`, and `AND`/`OR`/`NOT`.
- **Repeater**: edit and resend a raw request. What you type is what
  goes on the wire - no normalization, no auto-fixed `Content-Length`,
  no "helpful" reformatting. That's the point of a Repeater.
- **Intruder** (Sniper only): mark positions in a request template
  with `§markers§`, supply a payload list, fuzz one position at a time
  against a shared payload set. Results land in the same history table
  as everything else, searchable the same way.
- **Match-and-replace**: header rewrite rules (add, remove, or modify)
  for requests and/or responses, applied live as traffic passes
  through. History still shows what was actually sent/received on each
  side - match-and-replace transforms the wire, it doesn't rewrite the
  audit trail.
- **Flagging**: mark an entry to revisit later (★), filterable via
  `flagged:true`.
- **Comparer**: mark one entry (`c`), then `c` on a different entry to
  see a colored unified diff of either side's request or response.
- **Vi-modal editing**: the raw request editors (Repeater, Intruder)
  are real modal editors - normal mode by default, `i`/`a`/`o`/etc. to
  insert, `hjkl`, `dd`/`yy`/`p`, word motions, `gg`/`G`. See
  [Vi bindings](#vi-bindings) below. Everywhere else (history table,
  read-only response views), standard vi navigation (`j`/`k`, `g`/`G`,
  `ctrl+u`/`ctrl+d`) already works - that's the underlying TUI
  library's default, not something layered on top.

## Install / build

Requires Go 1.26.5+ (see `go.mod`).

```sh
git clone <this repo>
cd mitmux
go build -o bin/mitmuxd ./cmd/mitmuxd
go build -o bin/mitmux  ./cmd/mitmux
```

## Quick start

1. **Start the daemon.** By default it listens on `127.0.0.1:8080` and
   stores its CA and history database under `~/.config/mitmux` (XDG
   config dir):

   ```sh
   ./bin/mitmuxd
   ```

   On first run it generates a root CA and prints where the cert
   landed, e.g. `~/.config/mitmux/ca.pem`.

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`.)

3. **Point a client at the proxy.** e.g.:

   ```sh
   curl -x http://127.0.0.1:8080 --cacert ~/.config/mitmux/ca.pem https://example.com/
   ```

   Or configure your browser's proxy settings to `127.0.0.1:8080`.

4. **Open the TUI** (in another terminal - the daemon keeps running
   independently):

   ```sh
   ./bin/mitmux
   ```

Both binaries take flags for non-default setups - `-listen`, `-socket`,
`-ca-dir`, `-db` on `mitmuxd`; `-socket` on `mitmux`. Run either with
`-h` for the full list.

## Usage

Press `?` from any screen in the TUI for the full, current keybinding
reference - it's generated from the same source as this document, so
it never drifts out of date the way a static list can. The summary
below is enough to get going.

### History (the default view)

| Key | Action |
|---|---|
| `↑`/`↓` or `j`/`k` | navigate (also `g`/`G` top/bottom, `ctrl+u`/`ctrl+d` half-page) |
| `enter` | view request/response detail |
| `r` | open in Repeater |
| `i` | open in Intruder |
| `f` | toggle flag |
| `c` | mark for comparison - press `c` on another entry to diff |
| `/` | search |
| `m` | match-and-replace rules |
| `q` | quit |

### Detail view

`tab` switches request/response, `p` toggles pretty-printed JSON on the
response (display-only - never touches the stored or resent bytes), `c`
mark/compare (same as the history list), `r`/`i` jump straight to
Repeater/Intruder seeded from this entry, `esc` back.

### Comparer

Reachable by pressing `c` on two different history entries (from either
the list or detail view). Shows a colored unified diff - `diff -u`
style, `+`/`-` lines - of the two entries' requests or responses,
`tab` to switch between them. CRLF is normalized before diffing so an
exact HTTP/1.1 capture doesn't show every line as changed purely from
the invisible `\r`.

### Search syntax

Plain text searches headers and bodies on both sides of the exchange.
A handful of characters that are FTS5 syntax rather than literal text
(`.`, `-`, `/`, `@`, and more) are handled transparently - you don't
need to quote a domain name or an IP address for it to work.

- `example.com`, `x-forwarded-for`, `192.168.1.1` - literal text, just works
- `host:example.com`, `AND`, `OR`, `NOT` - FTS5 syntax for column
  filters and boolean queries
- `status:404` - exact status code
- `status:4xx` (also `2xx`/`3xx`/`5xx`) - status range shorthand
- `status:>=400`, `status:!=200` - status comparison operators
- `source:proxy` / `source:repeater` / `source:intruder` - where the
  request came from
- `flagged:true` / `flagged:false`
- Combine freely: `admin status:200 source:repeater`

### Repeater / Intruder - vi bindings

The request editors start in **normal mode**, not insert mode - like
real vi. Press `i` (or `a`/`I`/`A`/`o`/`O`) to start typing, `esc` to
go back to normal mode. The mode indicator (`-- NORMAL --` /
`-- INSERT --`) is always visible while one of these editors is
focused.

| Normal-mode key | Action |
|---|---|
| `h` `j` `k` `l` | left / down / up / right |
| `0` / `$` | line start / end |
| `w` / `b` | word forward / back |
| `x` | delete character |
| `i` `a` `I` `A` | insert: before cursor / after cursor / line start / line end |
| `o` / `O` | open a line below / above and insert |
| `dd` / `yy` | delete / yank the current line |
| `p` / `P` | paste below / above |
| `dw` `d$` `d0` | delete word / to end of line / to start of line |
| `gg` / `G` | top / bottom of the buffer |
| `esc` | (in insert mode) back to normal mode - never leaves the view |

This is a genuine, if intentionally scoped, modal editor: it translates
these commands into the underlying text widget's own editing primitives
rather than reimplementing cursor and line manipulation. Not
implemented: registers beyond a single yank slot, visual mode, ex
commands, macros, and counts (`3dd`, `5j`). There's no undo, because
the underlying text widget doesn't have one either.

`ctrl+r` sends (Repeater) or starts the attack (Intruder). `tab`
switches panes. In Intruder's template pane specifically, `ctrl+g`
inserts a `§` marker at the cursor if typing the character directly
isn't convenient on your keyboard/terminal.

### Match-and-replace rules

Press `m` from the history view. Rules match request or response
headers (`a` add, `enter`/`e` edit, `d` delete, `space` toggle
enabled). Matching is literal-substring by default, or regex if the
rule's Regex toggle is on. Rules operate on the raw header *block* as
text, not per-value substitution, so a rule can add or remove a header
entirely, not just rewrite an existing one. Currently headers only -
see `PLAN.md` for why body rules are a separate, harder problem.

## Architecture

`mitmuxd` owns the proxy listener and the SQLite database; `mitmux` is
a thin client that only ever talks to the daemon over a Unix socket
(`internal/ipc`). This split is deliberate: a web UI, a CLI scanner, or
any other client could be bolted on later without touching the proxy
engine, and the TUI restarting (or crashing) never interrupts capture.

Capture fidelity is the other core design constraint: for HTTP/1.1
traffic, request and response bytes stored in history are exactly what
was read off the wire - captured via a `net.Conn` wrapper that records
bytes as `net/http`'s own (memory-safe, battle-tested) parser consumes
them, rather than re-serializing a parsed representation. For HTTP/2,
which has no meaningful single "raw bytes" form, the stored
representation is a reconstruction, and every stored entry says which
kind it is (`request_exact`/`response_exact` in the database, "exact"
vs. "reconstructed" in the UI). Repeater and Intruder both write raw
bytes straight to the wire for the same reason - the whole point of a
Repeater is that a deliberately malformed request reaches the target
unmodified.

Package layout:

```
cmd/mitmuxd/    daemon entrypoint
cmd/mitmux/     TUI entrypoint
internal/ca/    root CA + per-host leaf certificate generation
internal/proxy/ proxy engine: HTTP/CONNECT handling, capture, Repeater, Intruder
internal/rules/ match-and-replace engine
internal/store/ SQLite storage, FTS5 search
internal/ipc/   daemon <-> client protocol (JSON over a Unix socket)
```

## Development

```sh
go build ./...
go vet ./...
gofmt -l .          # should print nothing
go test ./...
```

There's no mock traffic layer - the test suite covers pure logic
(marker parsing, search-query parsing) that's worth locking down with
real tests rather than trusting by inspection. Everything that touches
the network, the daemon, or the TUI has been verified by actually
running it against real traffic during development; see commit
messages for what was checked and how.

## Known limitations

Deliberate scope decisions, not oversights - see `PLAN.md` for the
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
- No WebSocket interception
- No client (mutual-TLS) certificate support
- No active or passive vulnerability scanning, no plugin system - this
  is a manual-testing tool, not a scanner