srdusr
aboutsummaryrefslogtreecommitdiffstats
path: root/PLAN.md
diff options
context:
space:
mode:
authorsrdusr <[email protected]>2026-08-04 09:35:00 +0200
committersrdusr <[email protected]>2026-08-04 09:35:00 +0200
commitdde73a349a68f942a5bd89b27ac980d7973148e0 (patch)
treecec48acc8d65d2610f74752eab4db0705a2d38a1 /PLAN.md
parent4c4c8dd4983092ffa5c6602ed070f401bbbf74f1 (diff)
downloadmitmux-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.md93
1 files changed, 93 insertions, 0 deletions
diff --git a/PLAN.md b/PLAN.md
index bf30b0c..68b6e56 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -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.