yorishiro-proxy

AI-first MITM proxy tool
A network proxy for AI agents — intercept, record, and replay traffic through MCP.

---

yorishiro-proxy runs as an MCP (Model Context Protocol) server, giving AI agents full control over proxy operations through eleven MCP tools. Designed for use with Claude Code and other MCP-compatible agents, it enables automated security testing workflows without manual UI interaction. An embedded Web UI is also available for visual inspection and interactive use.

Beta

yorishiro-proxy is under active development. APIs, configuration formats, and protocol behavior may change between minor versions. Non-HTTP/HTTPS protocols (gRPC, WebSocket, Raw TCP, SOCKS5) are at an earlier stage of maturity and may have known limitations.

Key features

• Traffic interception & recording — MITM proxy with automatic CA certificate management
• Resender — Replay requests with header/body/URL overrides, JSON patches, and raw HTTP editing
• Fuzzer — Automated payload injection with sequential/parallel modes and async execution
• Macro — Multi-step request sequences with variable extraction and template substitution
• Intercept — Hold and inspect requests/responses in real time, then release, modify, or drop
• Auto-transform — Automatic request/response modification rules for matching traffic
• Target scope — Two-layer security boundary (Policy + Agent) to restrict reachable hosts
• Multi-protocol — HTTP/1.x, HTTPS (MITM), HTTP/2 (h2c/h2), gRPC, WebSocket, Raw TCP, SOCKS5
• AI safety — SafetyFilter blocks destructive payloads and masks PII; rate limiting and diagnostic budgets
• Plugin system — Extend proxy behavior with Starlark scripts
• Web UI — Embedded React/Vite dashboard for visual inspection and interactive testing

Quick start

1. Get the binary

Download a prebuilt binary from the GitHub Releases page, or build from source:

git clone https://github.com/usk6666/yorishiro-proxy.git
cd yorishiro-proxy
make build    # outputs bin/yorishiro-proxy

2. Configure MCP

Add to your MCP client configuration (e.g., .mcp.json for Claude Code):

{
  "mcpServers": {
    "yorishiro-proxy": {
      "command": "/path/to/bin/yorishiro-proxy",
      "args": ["server", "-stdio-mcp"]
    }
  }
}

The proxy starts as an MCP server with stdio transport for Claude Code integration. The CA certificate is automatically generated on first run and persisted to ~/.yorishiro-proxy/ca/. An HTTP MCP transport with the Web UI is also started by default on a random loopback port.

To use a fixed HTTP MCP address (e.g., for multi-agent sharing or direct Web UI access):

{
  "mcpServers": {
    "yorishiro-proxy": {
      "command": "/path/to/bin/yorishiro-proxy",
      "args": ["server", "-stdio-mcp", "-mcp-http-addr", "127.0.0.1:3000"]
    }
  }
}

3. First capture

Once the MCP server is running, the AI agent can start capturing traffic:

1. Start the proxy       → proxy_start with listen_addr "127.0.0.1:8080"
2. Set HTTP_PROXY        → point your target application at the proxy
3. Install the CA cert   → query ca_cert to get the certificate path
4. Browse / send traffic → captured flows appear in query flows
5. Inspect & replay      → use resend to replay with modifications

For detailed setup instructions, see the Getting started guide.

MCP tools

All proxy operations are exposed through eleven MCP tools:

Tool	Purpose
proxy_start	Start a proxy listener with capture scope, TLS passthrough, intercept rules, auto-transform, TCP forwarding, and protocol settings
proxy_stop	Graceful shutdown of one or all listeners
configure	Runtime configuration changes (upstream proxy, capture scope, TLS passthrough, intercept rules, auto-transform, connection limits)
query	Unified information retrieval: flows, flow details, messages, proxy status, config, CA certificate, intercept queue, macros, fuzz jobs/results
resend	Replay recorded requests with mutations and compare two flows structurally
fuzz	Execute fuzz testing campaigns with payload sets, positions, concurrency control, and stop conditions
macro	Define and execute multi-step macro workflows with variable extraction, guards, and hooks
intercept	Act on intercepted requests: release, modify and forward, or drop
manage	Manage flow data (delete/export/import) and CA certificate regeneration
security	Configure target scope rules, rate limits, diagnostic budgets, and SafetyFilter (Policy Layer + Agent Layer)
plugin	List, reload, enable, and disable Starlark plugins at runtime

See the MCP tools overview for details.

Supported protocols

Protocol	Detection	Status	Notes
HTTP/1.x	Automatic	Stable	Forward proxy mode
HTTPS	CONNECT	Stable	MITM with dynamic certificate issuance
HTTP/2	h2c / ALPN	Beta	Both cleartext and TLS, with per-stream flow display
gRPC	HTTP/2 content-type	Experimental	Service/method extraction, streaming support, structured metadata display
WebSocket	HTTP Upgrade	Experimental	Message-level recording with per-message display
Raw TCP	Fallback	Experimental	Captures any unrecognized protocol, with TCP forwarding mappings
SOCKS5	SOCKS5 handshake	Experimental	Routes arbitrary TCP traffic through the proxy (RFC 1928)

See the Protocols section for detailed documentation on each protocol.

Web UI

The embedded Web UI is served at the HTTP MCP address (enabled by default on a random loopback port). Use -mcp-http-addr to set a fixed address.

Page	Description
Flows	Flow list with filtering by protocol, method, status code, and URL pattern
Dashboard	Flow statistics overview with real-time traffic summary
Intercept	Real-time request/response interception with inline editing
Resender	Replay requests with overrides, JSON patches, raw HTTP editing, and dry-run preview
Fuzzer	Create and manage fuzz campaigns with payload sets and result analysis
Macros	Multi-step request workflows with variable extraction
Security	Target scope configuration (Policy + Agent Layer) with URL testing
Settings	Proxy control, TLS passthrough, auto-transform rules, CA management, and more

The Web UI communicates with the backend via Streamable HTTP MCP — the same protocol used by AI agents. See the Web UI overview for more information.

Quick links

Section	Description
Getting started	Installation, MCP configuration, CA certificate setup, and first capture
Concepts	Architecture, flows, MCP-first design, and security model
MCP tools	Complete reference for all eleven MCP tools
Features	Detailed guides for resender, fuzzer, macros, intercept, and more
Protocols	HTTP, HTTPS MITM, HTTP/2, gRPC, WebSocket, Raw TCP, SOCKS5
Web UI	Visual dashboard for inspection and interactive testing
Plugins	Extend proxy behavior with Starlark scripts
Configuration	CLI flags, config files, TLS, upstream proxy, and retention settings
Guides	Practical tutorials for vulnerability assessment, API testing, and multi-agent setups