Yorishiro Proxy

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.

Yorishiro Proxy runs as an MCP (Model Context Protocol) server, giving AI agents full control over proxy operations through a typed-per-protocol MCP tool surface. 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.

Features

• Traffic Interception & Recording -- MITM proxy with automatic CA certificate management
• Per-Protocol Resend -- Replay recorded flows with typed schemas (resend_http, resend_ws, resend_grpc, resend_raw) including header/body/URL overrides, JSON patches, and raw byte editing
• Per-Protocol Fuzz -- Typed fuzzers (fuzz_http, fuzz_ws, fuzz_grpc, fuzz_raw) with payload sets and position-driven mutations
• 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, gRPC-Web, WebSocket, SSE, Raw TCP, SOCKS5
• Multi-Listener -- Multiple proxy listeners on different ports simultaneously
• mTLS Client Certificates -- Per-host client certificate support for mutual TLS authentication
• TLS Verification Control -- Per-host TLS verification and custom CA configuration
• Flow Timing -- Per-phase timing recording (DNS, connect, TLS handshake, request, response) on each flow
• Flow Export/Import -- JSONL, HAR 1.2, and cURL export formats
• SOCKS5 Listener -- SOCKS5 proxy with optional username/password authentication for proxychains integration
• Upstream Proxy -- Chain through HTTP or SOCKS5 proxies
• Streamable HTTP MCP -- Multi-agent shared access with Bearer token authentication
• AI Safety -- SafetyFilter blocks destructive payloads (DROP TABLE, rm -rf, etc.) at the Input Filter before they reach the target; Output Filter masks PII (credit card numbers, email addresses, phone numbers, etc.) in responses before returning to AI agents while preserving raw data in the flow store; rate limiting (global/per-host RPS) and diagnostic budgets (request count/duration limits) with two-layer Policy+Agent architecture
• Plugin System -- Extend proxy behavior with Starlark scripts using the typed register_hook(protocol, event, phase) API; introspect loaded hooks via plugin_introspect
• Web UI -- Embedded React/Vite dashboard for visual inspection and interactive testing

Quick Start

1. Get the Binary

Install via npm / npx (the correct prebuilt binary for your platform is fetched automatically as an optional dependency — no postinstall, no network fetch at install time):

# Install globally
npm i -g @usk6666/yorishiro-proxy

# Or run without installing
npx @usk6666/yorishiro-proxy install

Alternatively, 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

The npm distribution, GitHub Releases, and the yorishiro-proxy upgrade self-update path all coexist — use whichever fits your workflow.

2. Configure MCP

The easiest way to set up MCP integration is with the install subcommand:

# Configure MCP for the current project (writes .mcp.json)
yorishiro-proxy install mcp

# Or configure at the user level (~/.claude/settings.json)
yorishiro-proxy install mcp --user-scope

This generates the correct .mcp.json entry with stdio MCP transport enabled and log output redirected to a file -- the recommended configuration for MCP clients like Claude Code.

The CA certificate is automatically generated on first run and persisted to ~/.yorishiro-proxy/ca/.

3. Start the Server Standalone

You can also start the server directly. By default, it launches an HTTP MCP server on a random loopback port and writes the connection info to ~/.yorishiro-proxy/server.json:

# Start with default settings
yorishiro-proxy server

# Start on a fixed port with browser auto-open
yorishiro-proxy server -mcp-http-addr 127.0.0.1:3000 -open-browser

On startup, the log prints the Web UI URL:

WebUI available url=http://127.0.0.1:3000/

The authentication token is written to ~/.yorishiro-proxy/server.json and included in the URL at debug log level (-log-level debug).

4. 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

MCP Tools

All proxy operations are exposed through typed MCP tools:

Web UI

The embedded Web UI is served on the HTTP MCP address (enabled by default).

The Web UI communicates with the backend via Streamable HTTP MCP -- the same protocol used by AI agents.

Supported Protocols

CLI

yorishiro-proxy provides the following subcommands:

The client subcommand connects to a running server and calls MCP tools with key=value parameters, providing a lightweight interface for scripting and ad-hoc pentest workflows:

yorishiro-proxy client query resource=status
yorishiro-proxy client proxy_start listen_addr=127.0.0.1:8080
yorishiro-proxy client query resource=flows limit=10

For the full list of server flags, client options, and environment variables, run yorishiro-proxy server -help or yorishiro-proxy client -help, or see the documentation.

Architecture

Layer 4 TCP Listener
  -> Protocol Detection (peek bytes / ALPN)
    -> Connection Stack (TCP -> TLS -> HTTP/1 | HTTP/2 -> WS | gRPC | gRPC-Web | SSE | Raw)
      -> Pipeline (HostScope -> HTTPScope -> Safety -> PluginPre -> Intercept -> Transform -> PluginPost -> Record [-> UpgradeStep])
        -> Flow Recording (L7 Message + L4 Envelope.Raw)
          -> MCP Tool (Intercept / Replay / Search / Plugin Introspect)

• Accepts connections at Layer 4 (TCP) and builds a per-connection Layer stack
• No external proxy libraries -- built on the Go standard library
• MCP-first: all operations are exposed exclusively as MCP tools
• Embedded Web UI built with React/Vite, served via Streamable HTTP

For the design rationale and data model, see RFC-001 Envelope + Layered Connection Model.

Documentation

Full documentation is available at usk6666.github.io/yorishiro-proxy-docs.

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.