Transport Mode Comparison#

Pipelock supports multiple proxy modes, each with different scanning capabilities. Choosing the right mode determines what security checks apply to your agent's traffic.

Mode Summary#

Detailed Breakdown#

Fetch Proxy (/fetch?url=...)#

The highest-protection mode. Designed for AI agents that need web content.

Scanning:

• 11-layer URL scan (scheme, CRLF injection, path traversal, blocklist, DLP, path entropy, subdomain entropy, SSRF, rate limit, URL length, data budget)
• Raw HTML scan for injection in hidden elements (script, style, comments, hidden divs)
• Readability text extraction (strips HTML, returns clean text)
• Response injection detection on extracted content
• Redirect chain: each hop scanned through all 11 layers

What the agent receives: Extracted text content, not raw HTML. Hidden injection is detected even though the agent never sees it.

Use when: Your agent fetches web pages and you want both URL scanning and content inspection.

curl "http://localhost:8888/fetch?url=https://example.com"

CONNECT Tunnel (via HTTPS_PROXY)#

Standard HTTP CONNECT proxy. Without TLS interception, pipelock cannot see the encrypted traffic after the tunnel is established.

Scanning (without TLS interception):

• 11-layer URL scan on the target hostname (before tunnel)
• No content inspection during the tunnel (encrypted bytes)
• No response scanning

Scanning (with tls_interception.enabled: true):

• 11-layer URL scan on the target hostname (before tunnel)
• Full request body DLP (JSON, form, multipart extraction)
• Request header DLP scanning
• Authority enforcement (Host must match CONNECT target)
• Response injection detection (buffered scan-then-send)
• Compressed response blocking (fail-closed)

What the agent receives: Without interception: raw HTTPS response from the origin server. With interception: response re-encrypted by pipelock after scanning.

Use when: Your agent or SDK uses HTTPS_PROXY natively. Enable TLS interception for full DLP and injection scanning. Without interception, only hostname-level protection applies.

# Without TLS interception (hostname scanning only)
HTTPS_PROXY=http://localhost:8888 curl https://example.com

# With TLS interception (full body/header DLP + response scanning)
# Requires: tls_interception.enabled: true in config
# Requires: pipelock CA trusted by the agent (pipelock tls install-ca)
HTTPS_PROXY=http://localhost:8888 curl --cacert ~/.pipelock/ca.pem https://example.com

Absolute-URI Forward Proxy (via HTTP_PROXY)#

Handles plaintext HTTP requests where the client sends the full URL as the request target.

Scanning:

• 11-layer URL scan on the full URL
• Response injection scanning (buffer-then-scan-then-send, fail-closed on compressed responses)
• Response body buffered (up to MaxResponseMB), scanned for injection, then forwarded
• Data budget tracking on response size

What the agent receives: Raw HTTP response from the origin server.

Use when: Your application makes plaintext HTTP requests through HTTP_PROXY. Note that most modern APIs use HTTPS, making this mode less common.

HTTP_PROXY=http://localhost:8888 curl http://example.com

WebSocket Proxy (/ws?url=...)#

Bidirectional WebSocket proxy with frame-level scanning.

Scanning:

• 11-layer URL scan on the target URL
• DLP scanning on WebSocket upgrade request headers
• Bidirectional frame scanning (both client-to-server and server-to-client)
• Fragment reassembly for multi-frame messages
• Compression rejection (RSV1 bit check prevents deflate-based DLP bypass)
• Data budget tracking per domain

What the agent receives: WebSocket frames, scanned in both directions.

Use when: Your agent uses WebSocket connections for real-time communication and you need DLP scanning on the message content.

# Agent connects to pipelock, which proxies to the target
ws://localhost:8888/ws?url=wss://api.example.com/stream

MCP stdio proxy (pipelock mcp proxy -- COMMAND)#

Wraps a local MCP server process with full bidirectional message scanning.

Scanning:

• Response scanning: injection detection in tool results
• Input scanning: DLP + injection in tool arguments (when mcp_input_scanning enabled)
• Tool scanning: poisoned description detection + rug-pull drift detection (when mcp_tool_scanning enabled)
• Tool policy: pre-execution allow/deny rules with shell obfuscation detection (when mcp_tool_policy enabled)
• Chain detection: suspicious tool call sequence patterns (when tool_chain_detection enabled)
• Session binding: tool inventory pinning per session (when mcp_session_binding enabled)

What the agent receives: MCP responses with injection warnings injected, or blocked entirely depending on config action.

Use when: Running local MCP servers (filesystem, database, custom tools) and you want to scan all tool interactions.

{
  "mcpServers": {
    "filesystem": {
      "command": "pipelock",
      "args": ["mcp", "proxy", "--config", "pipelock.yaml", "--", "npx", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

MCP HTTP Proxy (pipelock mcp proxy --upstream URL)#

Proxies a remote MCP server over HTTP with the same scanning as stdio mode.

Scanning: Same 6 layers as MCP stdio (response, input, tool, policy, chain, session binding).

Transport sub-modes:

• Stdio-to-HTTP bridge (pipelock mcp proxy --upstream URL): Translates stdio JSON-RPC to HTTP requests against a streamable HTTP MCP server
• HTTP reverse proxy (pipelock mcp proxy --listen ADDR --upstream URL or pipelock run --mcp-listen ADDR --mcp-upstream URL): Listens on an HTTP port and reverse-proxies to the upstream MCP server

Use when: Connecting to remote MCP servers over HTTP and you want the same scanning coverage as local stdio servers.

MCP WebSocket Proxy (pipelock mcp proxy --upstream ws://...)#

Proxies a remote MCP server over WebSocket with the same scanning as stdio mode.

Scanning: Same 6 layers as MCP stdio (response, input, tool, policy, chain, session binding).

How it works: When --upstream receives a ws:// or wss:// URL, pipelock connects to the upstream over WebSocket and translates between stdin/stdout JSON-RPC and WebSocket text frames. Each JSON-RPC message maps to one WebSocket text frame. Fragment reassembly is handled automatically.

Use when: Connecting to MCP servers that expose a WebSocket endpoint (common with OpenClaw gateways and other real-time MCP hosts).

{
  "mcpServers": {
    "remote": {
      "command": "pipelock",
      "args": ["mcp", "proxy", "--config", "pipelock.yaml", "--upstream", "ws://localhost:3000/mcp"]
    }
  }
}

Security Implications#

CONNECT Tunnels: With and Without TLS Interception#

Without TLS interception (tls_interception.enabled: false, the default), CONNECT tunnels are opaque encrypted bytes after the hostname scan. DLP cannot detect secrets in bodies or headers, and response injection scanning does not apply.

With TLS interception enabled, pipelock performs a TLS MITM: it terminates TLS with the client (forged certificate), scans the decrypted traffic, then forwards to the upstream server over a separate TLS connection. This closes the body-blindness gap.

Without interception:

• DLP cannot detect secrets in HTTPS request/response bodies
• Response injection scanning does not apply
• Only the 11-layer URL scan provides protection

With interception:

• Full request body DLP (JSON, form, multipart)
• Request header DLP (Authorization, Cookie, etc.)
• Response injection scanning (buffered, scan-then-send)
• Authority enforcement (Host must match CONNECT target)

If your agent handles secrets and you need content-level DLP on HTTPS traffic, either enable TLS interception or use the fetch proxy or MCP proxy modes.

Fetch Proxy vs CONNECT: Trade-offs#

See Also#

• Configuration Reference for all config fields controlling each proxy mode
• OpenClaw Integration for deploying pipelock with OpenClaw gateways
• Deployment Recipes for Docker Compose, Kubernetes, and host-level enforcement
• Bypass Resistance for details on how each scanning layer resists evasion
• Attacks Blocked for real-world attack examples across all transport modes