Config file

yorishiro-proxy can load proxy defaults from a JSON config file. The file format is identical to the proxy_start tool's input, so you can reuse the same JSON structure for both file-based configuration and runtime MCP tool calls.

Loading a config file

Pass the config file path using the -config flag or YP_CONFIG environment variable:

yorishiro-proxy -config proxy.json

YP_CONFIG=proxy.json yorishiro-proxy

File structure overview

The config file is a single JSON object with the following top-level sections:

{
  "listen_addr": "127.0.0.1:8080",
  "upstream_proxy": "",
  "tls_fingerprint": "chrome",
  "tls_passthrough": [],
  "capture_scope": {},
  "intercept_rules": {},
  "intercept_queue": {},
  "auto_transform": [],
  "tcp_forwards": {},
  "max_body_size": 266338304,
  "max_concurrent_streams": 500,
  "client_cert": "",
  "client_key": "",
  "host_tls": {},
  "socks5_auth": "none",
  "socks5_username": "",
  "socks5_password": "",
  "target_scope_policy": {},
  "safety_filter": {},
  "plugins": []
}

All fields are optional. Only include the sections you need.

Proxy core settings

listen_addr

The TCP address the proxy listens on.

Type	Default
string	"127.0.0.1:8080"

{
  "listen_addr": "127.0.0.1:9090"
}

upstream_proxy

Upstream proxy URL for proxy chaining. Supports HTTP and SOCKS5 proxy URLs.

Type	Default
string	"" (direct connection)

{
  "upstream_proxy": "http://proxy.corp.example:3128"
}

tls_fingerprint

TLS ClientHello fingerprint profile for upstream HTTPS connections. Uses uTLS to mimic a browser's TLS fingerprint, evading JA3/JA4-based bot detection.

Type	Default	Valid values
string	"" (Go default TLS)	chrome, firefox, safari, edge, random, none

{
  "tls_fingerprint": "chrome"
}

tls_passthrough

List of domain patterns that bypass TLS interception (MITM). Connections to matching hosts are forwarded without decryption.

Type	Default
string[]	[]

Supported patterns:

• Exact match: "example.com"
• Wildcard: "*.example.com" (matches any subdomain)

{
  "tls_passthrough": ["*.google.com", "*.googleapis.com"]
}

capture_scope

Controls which requests are recorded to the flow store. This is passed as a raw JSON object to the proxy engine.

{
  "capture_scope": {
    "include": ["*.target.com"],
    "exclude": ["*.static.target.com"]
  }
}

intercept_rules

Configures request/response intercept rules. This is passed as a raw JSON object to the intercept engine.

{
  "intercept_rules": {
    "request": true,
    "response": false
  }
}

intercept_queue

Hold-queue defaults for intercepted envelopes. Supports a global timeout / behavior pair and a per-protocol override map (USK-855).

Field	Type	Default	Description
timeout_ms	integer	300000	Global hold-timeout in ms (min 1000)
timeout_behavior	string	"auto_release"	Global behavior on timeout (auto_release or auto_drop)
protocol_overrides	object		Per-protocol overrides keyed by canonical envelope.Protocol (http, ws, grpc, grpc-web, sse, raw, tls-handshake). The literal "http2" is rejected -- HTTP/1 and HTTP/2 both envelope as "http"

Built-in per-protocol defaults raise WS / SSE / gRPC / gRPC-Web hold-timeouts to 60000 ms (60 s) so multi-second intercept review windows on long-lived streams do not race the upstream idle timeout; the WS Layer injects synthetic keepalive pings during a hold (USK-854) so the upstream remains alive for the entire window.

{
  "intercept_queue": {
    "timeout_ms": 300000,
    "timeout_behavior": "auto_release",
    "protocol_overrides": {
      "ws":  {"timeout_ms": 120000},
      "sse": {"timeout_ms": 60000, "timeout_behavior": "auto_drop"}
    }
  }
}

auto_transform

Configures auto-transform rules for automatic request/response modification. This is passed as a raw JSON array to the transform pipeline.

{
  "auto_transform": [
    {
      "match": {"header": "Authorization"},
      "set_header": {"Authorization": "Bearer new-token"}
    }
  ]
}

tcp_forwards

Maps local listen ports to upstream forwarding configurations. Each value can be a string (legacy format) or a ForwardConfig object with protocol detection and TLS options.

Type	Default
object	{}

String format (legacy) -- forwards raw bytes without L7 parsing:

{
  "tcp_forwards": {
    "5432": "db.internal:5432",
    "6379": "redis.internal:6379"
  }
}

ForwardConfig object format -- enables protocol detection and TLS MITM:

{
  "tcp_forwards": {
    "50051": {
      "target": "api.internal:50051",
      "protocol": "grpc"
    },
    "8443": {
      "target": "backend.internal:443",
      "protocol": "auto",
      "tls": true
    },
    "5432": "db.internal:5432"
  }
}

ForwardConfig fields:

Field	Type	Default	Description
target	string	(required)	Upstream host:port address
protocol	string	"auto"	L7 protocol: auto, raw, http, http2, grpc, websocket, sse (USK-913)
tls	bool	false	Enable client-side TLS MITM termination on the forwarded listen port
upstream_tls	bool	false	Wrap the upstream-dial connection in TLS (USK-911 / USK-916). Independent of tls
upstream_insecure_skip_verify	bool	inherit -insecure	Per-entry override for upstream TLS certificate verification when upstream_tls=true: true to skip verification on this entry, false to enforce, or omit to inherit the global flag (USK-918)

TLS × UpstreamTLS matrix

tls controls the listener-side handshake; upstream_tls controls the upstream-side handshake. They are independent and never inferred from target's scheme/port:

tls	upstream_tls	Client wire	Upstream wire	Typical use case
false	false	plaintext	plaintext	Raw L4/L7 forwarding (default)
true	false	TLS	plaintext	TLS termination only (downstream offload)
false	true	plaintext	TLS	Plaintext client -> TLS-only upstream
true	true	TLS	TLS	Full MITM: terminate then re-encrypt upstream

Both formats can be mixed in the same object. Legacy string values are equivalent to {"target": "host:port", "protocol": "raw"}.

Body and stream limits

max_body_size

Per-message body cap shared by HTTP/1.x, HTTP/2, gRPC, gRPC-Web, WebSocket, and SSE. Bodies up to body_spill_threshold (default 10 MiB) stay in memory; the surplus is spilled to a temp file. Exceeding the cap surfaces a per-protocol stream error rather than silently truncating.

Type	Default
integer (bytes)	266338304 (≈ 254 MiB)

max_concurrent_streams

HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS value advertised to clients. Raised from 100 to 500 in USK-862; range 1..65535. The same knob is exposed at runtime via proxy_start.max_concurrent_streams and configure.max_concurrent_streams.

Type	Default
integer	500

SOCKS5 authentication

Configure SOCKS5 proxy authentication.

Field	Type	Default	Description
socks5_auth	string	"none"	Authentication method: none or password
socks5_username	string	""	Username for password authentication
socks5_password	string	""	Password for password authentication

{
  "socks5_auth": "password",
  "socks5_username": "user",
  "socks5_password": "secret"
}

Client TLS (mTLS)

Global client certificate

Configure a global mTLS client certificate for upstream connections. Both client_cert and client_key must be provided together.

Field	Type	Description
client_cert	string	Path to PEM-encoded client certificate
client_key	string	Path to PEM-encoded client private key

{
  "client_cert": "/path/to/client.crt",
  "client_key": "/path/to/client.key"
}

Per-host TLS (host_tls)

Configure TLS settings for specific hosts. Supports per-host client certificates, custom CA bundles, and TLS verification control. Wildcard patterns (e.g., *.example.com) are supported.

Each entry supports:

Field	Type	Default	Description
client_cert	string	--	PEM-encoded client certificate path
client_key	string	--	PEM-encoded client private key path
tls_verify	bool\|null	null (use global)	TLS verification: true = enforce, false = skip, null = global setting
ca_bundle	string	--	PEM-encoded CA bundle file path

{
  "host_tls": {
    "api.internal.corp": {
      "client_cert": "/path/to/api-client.crt",
      "client_key": "/path/to/api-client.key"
    },
    "*.staging.example.com": {
      "tls_verify": false
    },
    "private-ca.example.com": {
      "ca_bundle": "/path/to/custom-ca.pem",
      "tls_verify": true
    }
  }
}

SafetyFilter (safety_filter)

The SafetyFilter engine blocks or masks destructive payloads. This is a Policy Layer setting -- once loaded from a config file, it cannot be modified at runtime via MCP tools.

Field	Type	Default	Description
enabled	bool	false	Enable the SafetyFilter engine
input	object	--	Input (request) filter rules
output	object	--	Output (response) filter rules

Input filter rules

Input rules inspect outgoing requests and can block destructive payloads.

Field	Type	Default	Description
action	string	"block"	Default action: block or log_only
rules	array	[]	List of filter rules

Output filter rules

Output rules inspect incoming responses and can mask sensitive data.

Field	Type	Default	Description
action	string	"mask"	Default action: mask or log_only
rules	array	[]	List of filter rules

Rule definition

Each rule is either a preset reference or a custom rule. The two are mutually exclusive.

Field	Type	Description
preset	string	Built-in preset name (e.g., destructive-sql). Mutually exclusive with pattern
id	string	Unique identifier. Required for custom rules
name	string	Human-readable label. Optional
pattern	string	Regular expression pattern. Mutually exclusive with preset
targets	string[]	Parts to inspect. Input: body, url, query, header, headers. Output: body, header:<name>, headers
replacement	string	Override replacement string for output preset rules

SafetyFilter example

{
  "safety_filter": {
    "enabled": true,
    "input": {
      "action": "block",
      "rules": [
        {"preset": "destructive-sql"},
        {"preset": "destructive-os-command"},
        {
          "id": "block-drop-api",
          "name": "Block dangerous API calls",
          "pattern": "DELETE\\s+/api/v[0-9]+/(users|accounts)",
          "targets": ["url"]
        }
      ]
    },
    "output": {
      "action": "mask",
      "rules": [
        {"preset": "credit-card"},
        {"preset": "email"},
        {
          "id": "mask-internal-ip",
          "name": "Mask internal IPs",
          "pattern": "10\\.\\d+\\.\\d+\\.\\d+",
          "targets": ["body"]
        }
      ]
    }
  }
}

Target scope policy (target_scope_policy)

Target scope policy rules control which network targets the proxy is allowed to access. These rules are part of the Policy Layer and are immutable at runtime.

Note

When a dedicated policy file is specified via -target-policy-file / YP_TARGET_POLICY_FILE, the target_scope_policy section in the config file is ignored.

Structure

Field	Type	Description
allows	array	Rules that permit network access. When non-empty, only matching targets are allowed
denies	array	Rules that block network access. Deny rules take precedence over allow rules
rate_limits	object	Rate limiting configuration
budget	object	Diagnostic session budget

Target rule fields

All non-empty fields must match for a rule to apply (AND logic).

Field	Type	Description
hostname	string	Target hostname (case-insensitive). Supports *.example.com wildcard
ports	int[]	Restrict to specific port numbers. Empty = all ports
path_prefix	string	Match the beginning of the URL path (case-sensitive). Empty = all paths
schemes	string[]	Restrict to specific URL schemes (e.g., http, https). Empty = all schemes

Rate limits (rate_limits)

Rate limiting for AI agent request throttling. These are Policy Layer limits that the Agent Layer cannot exceed.

Field	Type	Default	Description
max_requests_per_second	float	0 (unlimited)	Global rate limit (requests per second)
max_requests_per_host_per_second	float	0 (unlimited)	Per-host rate limit (requests per second)

Budget (budget)

Diagnostic session budgets to prevent runaway AI agents.

Field	Type	Default	Description
max_total_requests	int	0 (unlimited)	Maximum number of requests in the session
max_duration	string	"" (unlimited)	Maximum session duration (e.g., "30m", "1h")

Target scope policy example

{
  "target_scope_policy": {
    "allows": [
      {"hostname": "*.target.com"},
      {"hostname": "api.example.com", "ports": [443], "schemes": ["https"]}
    ],
    "denies": [
      {"hostname": "*.internal.corp"},
      {"hostname": "*.target.com", "path_prefix": "/admin"}
    ],
    "rate_limits": {
      "max_requests_per_second": 50,
      "max_requests_per_host_per_second": 10
    },
    "budget": {
      "max_total_requests": 10000,
      "max_duration": "1h"
    }
  }
}

You can also store target scope policy in a separate file and load it with -target-policy-file. The file format is the same as the target_scope_policy section:

{
  "allows": [
    {"hostname": "*.target.com"}
  ],
  "denies": [
    {"hostname": "*.internal.corp"}
  ],
  "rate_limits": {
    "max_requests_per_second": 50
  }
}

Plugins (plugins)

Configure Starlark-based plugins for the proxy pipeline. Each entry specifies a script path and configuration. Plugins are executed in order.

{
  "plugins": [
    {
      "path": "/path/to/plugin.star",
      "target": "http",
      "hooks": ["on_request", "on_response"],
      "on_error": "log"
    }
  ]
}

For details on writing plugins, see the plugin development guide.

Configuration examples

Minimal configuration

A minimal config file that sets just the listen address:

{
  "listen_addr": "127.0.0.1:8080"
}

Standard assessment configuration

A typical configuration for a vulnerability assessment engagement:

{
  "listen_addr": "127.0.0.1:8080",
  "tls_fingerprint": "chrome",
  "tls_passthrough": ["*.google.com", "*.googleapis.com"],
  "target_scope_policy": {
    "allows": [
      {"hostname": "*.target.com"}
    ],
    "denies": [
      {"hostname": "*.internal.corp"}
    ],
    "rate_limits": {
      "max_requests_per_second": 50,
      "max_requests_per_host_per_second": 10
    },
    "budget": {
      "max_total_requests": 10000,
      "max_duration": "2h"
    }
  },
  "safety_filter": {
    "enabled": true,
    "input": {
      "action": "block",
      "rules": [
        {"preset": "destructive-sql"},
        {"preset": "destructive-os-command"}
      ]
    },
    "output": {
      "action": "mask",
      "rules": [
        {"preset": "credit-card"},
        {"preset": "email"}
      ]
    }
  }
}

Full configuration

A comprehensive configuration demonstrating all available sections:

{
  "listen_addr": "127.0.0.1:8080",
  "upstream_proxy": "http://proxy.corp.example:3128",
  "tls_fingerprint": "chrome",
  "tls_passthrough": ["*.google.com"],
  "capture_scope": {
    "include": ["*.target.com"],
    "exclude": ["*.static.target.com"]
  },
  "intercept_rules": {
    "request": true,
    "response": false
  },
  "auto_transform": [
    {
      "match": {"header": "Authorization"},
      "set_header": {"Authorization": "Bearer updated-token"}
    }
  ],
  "tcp_forwards": {
    "5432": "db.internal:5432",
    "50051": {
      "target": "api.internal:50051",
      "protocol": "grpc"
    }
  },
  "client_cert": "/path/to/client.crt",
  "client_key": "/path/to/client.key",
  "host_tls": {
    "api.internal.corp": {
      "client_cert": "/path/to/api-client.crt",
      "client_key": "/path/to/api-client.key"
    },
    "*.staging.example.com": {
      "tls_verify": false
    }
  },
  "socks5_auth": "password",
  "socks5_username": "user",
  "socks5_password": "secret",
  "target_scope_policy": {
    "allows": [
      {"hostname": "*.target.com"}
    ],
    "denies": [
      {"hostname": "*.internal.corp"}
    ],
    "rate_limits": {
      "max_requests_per_second": 50,
      "max_requests_per_host_per_second": 10
    },
    "budget": {
      "max_total_requests": 10000,
      "max_duration": "1h"
    }
  },
  "safety_filter": {
    "enabled": true,
    "input": {
      "action": "block",
      "rules": [
        {"preset": "destructive-sql"},
        {"preset": "destructive-os-command"}
      ]
    },
    "output": {
      "action": "mask",
      "rules": [
        {"preset": "credit-card"},
        {"preset": "email"}
      ]
    }
  },
  "plugins": [
    {
      "path": "/path/to/plugin.star",
      "target": "http",
      "hooks": ["on_request", "on_response"],
      "on_error": "log"
    }
  ]
}

Related pages

• CLI flags -- Command-line flags reference
• TLS -- TLS interception and certificate configuration
• Upstream proxy -- Proxy chaining configuration
• Retention -- Flow retention and cleanup settings
• SafetyFilter -- SafetyFilter feature details
• Target scope -- Target scope feature details
• Rate limits & budgets -- Rate limiting feature details