diff options
| author | srdusr <[email protected]> | 2026-08-04 09:35:00 +0200 |
|---|---|---|
| committer | srdusr <[email protected]> | 2026-08-04 09:35:00 +0200 |
| commit | dde73a349a68f942a5bd89b27ac980d7973148e0 (patch) | |
| tree | cec48acc8d65d2610f74752eab4db0705a2d38a1 /PLAN.md | |
| parent | 4c4c8dd4983092ffa5c6602ed070f401bbbf74f1 (diff) | |
| download | mitmux-dde73a349a68f942a5bd89b27ac980d7973148e0.tar.gz mitmux-dde73a349a68f942a5bd89b27ac980d7973148e0.zip | |
Plugin protocol foundation: tag_entry, tag search/sort, TUI tag view
The prerequisite for the plugin ecosystem: any external process - any
language - that can reach the control socket can now tag a history
entry with a short string marker and an opaque JSON data blob, stored
in a new entry_tags table rather than requiring the plugin stay
connected for a later live round-trip. A plugin does its analysis
once; the data it attaches is what a human reviewing the entry later
actually sees.
internal/ipc: new "tag_entry" request (id, tag_plugin, tag, tag_data)
and EntryDetail.Tags (the full record for one entry, populated by
"get"). internal/store: entry_tags table, EntryTag struct, AddEntryTag/
ListEntryTags, a comma-joined Tags aggregate added to List/Search via
a correlated subquery (cheap enough per row that showing a tag badge
in the history list needs no N+1 query), and a new tag: search filter
alongside the existing status:/source:/flagged:.
TUI: a Tags column in the history table (sortable via o/O, the eighth
sort column), T from detail view opens a tag list (mirroring the
WebSocket-messages view's table-then-detail-viewport pattern), enter
on one shows its data - JSON-colorized via the existing jsoncolor.go
if it parses as JSON, sanitized plain text otherwise. Also fixed a
pre-existing gap while touching this: the WebSocket-messages view
never got mouse wheel support when it shipped; wired both it and the
new tags view up together.
PLUGINS.md documents the wire protocol for non-Go plugin authors -
connection model (subscribe vs request/response), the handful of
request types a plugin actually needs, and the trust boundary (the
socket has no auth beyond OS file permissions, same as the TUI's own
access). PLAN.md records the architecture decision (external process
over an embedded scripting language - mirrors the daemon/TUI split
already in place, no interpreter to sandbox, any language) and groups
~20 researched Burp extensions/Pro features into what Phase 1 already
covers (Autorize, Param Miner, Backslash Powered Scanner, Retire.js -
all just subscribe+repeat+tag, no new capability needed), what needs a
second protocol addition (JWT Editor, SAML Raider - live RPC to a
specific connected plugin for interactive actions like re-signing),
and what deserves its own separate project rather than a plugin
(active vulnerability scanning, Collaborator/OAST, a crawler).
Verified live end to end against a real daemon: a throwaway program
simulating a real plugin tagged a captured entry with structured JWT
data over the actual wire protocol; confirmed the tag badge, tag:
search filter, and full tag record all round-tripped correctly through
List/Search/Get. Confirmed in the TUI itself (tmux, real keystrokes):
the Tags column renders, T opens the tag list, entering it shows the
JSON data with real ANSI-verified syntax highlighting (not just
eyeballed), and tag: search filtering works from the history list.
Diffstat (limited to 'PLAN.md')
| -rw-r--r-- | PLAN.md | 93 |
1 files changed, 93 insertions, 0 deletions
@@ -775,3 +775,96 @@ real Actions run to execute) against a real `make release` output - confirmed all 6 platform archives (2 macOS, 2 Linux, 1 Windows, 1 FreeBSD) build with correct internal structure, `zip` selected only for the Windows target, and `SHA256SUMS` covers all of them. + +## Plugin ecosystem + +The goal, per direct request: parity with the extensions/Pro features +working Burp users actually rely on - "the best plugins, especially the +paid ones" - not a single proof-of-concept. Researched the current +BApp Store landscape and Burp Pro's paid-tier feature set to ground +this rather than guess from memory; see the grouping below. + +### Architecture decision + +Considered two shapes: an embedded scripting language (Lua/Starlark +interpreter in mitmuxd, plugins as hooked scripts) versus external +processes speaking mitmux's own existing IPC protocol. Chose the +latter, explicitly: any language (a plugin doing crypto work might +want Python's `jwcrypto`, a fast passive scanner might want Go - no +reason to lock authors into one embedded language), no new interpreter +dependency or sandboxing model to design and maintain, and it mirrors +the daemon/TUI split already in place - a plugin is architecturally +just another TUI, watching and acting on the same socket. Documented +in full, protocol-first (any-language authors need a real spec, not Go +doc comments), in `PLUGINS.md`. + +### Phase 1: tag + stored data (shipped) + +The prerequisite for everything else: a `tag_entry` IPC request lets +any connected process mark a history entry with a short string tag and +an opaque, plugin-defined JSON data blob, stored in a new `entry_tags` +table. Deliberately NOT a live round-trip to a still-connected plugin +process for every view - a plugin does its analysis once, tags the +entry with whatever data a human will want to see later, and the panel +just reads what got stored. Simpler, and works even if the plugin has +long since exited by the time someone reviews the entry. + +This one capability, paired with the IPC surface that already existed +(`subscribe` for live traffic, `repeat` for sending probe requests, +`list`/`search`/`get` for reading history), is enough for an entire +tier of plugins with no further protocol work: Autorize (replay with a +different session token, diff, tag likely IDORs), Param Miner (probe +for hidden parameters/cache poisoning, tag hits), Backslash Powered +Scanner (payload-variant diffing for injection), Retire.js (passive +scan of response bodies against a known-vulnerable-JS-library list). +Logger++/Content-Type-Converter/JSON-Beautifier-class extensions were +considered and skipped - mitmux's own History+FTS5 search and Decoder +tool already outperform what they'd add. + +TUI integration: `Summary.Tags` (a comma-joined, correlated-subquery +aggregate - cheap enough per row that List/Search need no N+1 query) +renders as a new `Tags` column in the history table, sortable via +`o`/`O` like any other column, and matchable via a new `tag:name` +search filter (same `extractStructured` mechanism as `status:`/ +`source:`/`flagged:`). `EntryDetail.Tags` carries the full record +(plugin name + tag + data) for the entry currently open; `T` from +detail view opens a list of them (mirroring the WebSocket-messages +view's own table-then-detail-viewport pattern, added earlier), `enter` +on one shows its data - JSON-colorized via the same `jsoncolor.go` +already built for pretty-printed response bodies if it parses as JSON, +plain sanitized text otherwise. Tag data goes through the same +sanitizeBlock treatment as any other externally-sourced text reaching +the real terminal - a plugin can echo back attacker-influenced content +(e.g. a header value it parsed), so it's not implicitly trusted just +because it came from a plugin rather than raw traffic. + +### What's grouped where + +- **Cheap IPC-plugin wins** (Phase 1 covers these fully): Autorize, + Param Miner, Backslash Powered Scanner, Retire.js. +- **Needs a second protocol addition** - a live round-trip to a + specific still-connected plugin, for an interactive action rather + than a passive tag (JWT Editor's "re-sign this with a different key, + right now" button; SAML Raider's equivalent XML re-signing): JWT + Editor, SAML Raider. Not yet built - Phase 1's tag+data display + already covers the *decode and view* half of what these do; only the + *live re-sign* half needs the new capability. +- **Needs real UI beyond a data panel**: InQL/GraphQL Raider (a schema + browser/query explorer, not just a decode view) - bigger lift, later. +- **Deserves its own separate project, not a plugin**: Burp Scanner and + Burp Bounty's custom active-check DSL (active vulnerability scanning + is a whole subsystem - check-diffing engines, hundreds of injection + variants - and already explicitly out of scope per this README's own + "a manual-testing tool, not a scanner"); Collaborator/OAST (needs + real internet-reachable DNS/HTTP infrastructure running somewhere, + not something an in-process plugin can be); a crawler (spidering is + its own substantial subsystem). Turbo Intruder's actual value is raw + throughput - mitmux's own Intruder already covers all four of Burp's + attack modes, so if extreme concurrency is ever wanted, that's a + core-engine change to how requests get dispatched, not something a + plugin protocol should be shaped around. + +Next: Phase 1's plugins themselves (Autorize- and Param-Miner- +equivalents first, since they validate the simple subscribe-act-tag +path before anything gets built on top of it), then the live-RPC +protocol addition for JWT Editor/SAML Raider. |