Skip to content

proxy_start

Start a proxy listener with optional configuration. The proxy listens on the specified address and begins intercepting HTTP/HTTPS/SOCKS5 traffic. You can run multiple listeners simultaneously by assigning each a unique name.

Parameters

Parameter Type Required Default Description
name string No "default" Listener name for multi-listener support
listen_addr string No "127.0.0.1:8080" TCP address to listen on (loopback only)
upstream_proxy string No direct Upstream proxy URL (http://host:port or socks5://host:port)
capture_scope object No capture all Controls which requests are recorded
tls_passthrough string[] No [] Domain patterns that bypass TLS interception
intercept_rules array No [] Rules for intercepting requests/responses
auto_transform array No [] Rules for automatic request/response modification
tcp_forwards object No {} TCP forwarding map (port -> target string or ForwardConfig object)
protocols string[] No all enabled Enabled protocols for detection
socks5_auth string No "none" SOCKS5 authentication method (none or password)
socks5_username string No Username for SOCKS5 password auth
socks5_password string No Password for SOCKS5 password auth
tls_fingerprint string No "chrome" TLS ClientHello fingerprint profile
client_cert string No PEM client certificate path for mTLS
client_key string No PEM client private key path for mTLS
max_connections integer No 128 Maximum concurrent connections (1--100000)
peek_timeout_ms integer No 30000 Protocol detection timeout in ms (100--600000)
request_timeout_ms integer No 60000 HTTP request header read timeout in ms (100--600000)

capture_scope

Controls which requests are recorded to the flow store.

  • includes (array of scope rules) -- only matching requests are captured. If empty, all requests match.
  • excludes (array of scope rules) -- matching requests are excluded. Takes precedence over includes.

Each scope rule has:

Field Type Description
hostname string Hostname pattern (exact or *.example.com wildcard)
url_prefix string URL path prefix (e.g. "/api/")
method string HTTP method (e.g. "GET", "POST")

At least one field must be set per rule.

intercept_rules

Each intercept rule has:

Field Type Required Description
id string Yes Unique rule identifier
enabled boolean Yes Whether the rule is active
direction string Yes "request", "response", or "both"
conditions object Yes Matching criteria (AND logic)

Conditions:

Field Type Description
host_pattern string Regex for hostname matching (port excluded)
path_pattern string Regex for URL path matching
methods string[] HTTP method whitelist (case-insensitive)
header_match object Maps header names to regex patterns (AND logic)

Multiple rules use OR logic -- a request/response is intercepted if any enabled rule matches.

tcp_forwards

Maps local listen ports to upstream forwarding configurations. Each entry maps a port number (string key) to either a string or a ForwardConfig object.

String format (legacy) -- the value is an upstream host:port address. Traffic is relayed as raw bytes with no L7 parsing:

"3306": "db.example.com:3306"

ForwardConfig object format -- provides control over protocol detection and TLS termination:

Field Type Required Default Description
target string Yes -- Upstream address in host:port format
protocol string No "auto" Expected protocol for L7 parsing
tls boolean No false Enable TLS MITM termination on the forwarded port

Protocol values:

Value Description
"auto" Peek-based detection -- the proxy inspects initial bytes to determine the L7 protocol
"raw" No L7 parsing -- relay as opaque bytes (same behavior as the legacy string format)
"http" Parse traffic as HTTP/1.x
"http2" Parse traffic as HTTP/2
"grpc" Parse traffic as gRPC (over HTTP/2)
"websocket" Parse traffic as WebSocket

TLS MITM: when tls is true, the proxy terminates TLS on the forwarded port. It issues a certificate using the target hostname and then applies L7 parsing to the decrypted traffic. This is useful for inspecting TLS-wrapped services like gRPC-over-TLS or HTTPS backends.

Note

Setting tls: true with protocol: "raw" is valid but unusual -- TLS is terminated, yet the decrypted payload is relayed as raw bytes without L7 parsing.

Both formats can be mixed in the same tcp_forwards object.

protocols

Valid values: "HTTP/1.x", "HTTPS", "WebSocket", "HTTP/2", "gRPC", "SOCKS5", "TCP".

tls_fingerprint

Value Description
"chrome" Mimic Chrome browser TLS fingerprint (default)
"firefox" Mimic Firefox browser TLS fingerprint
"safari" Mimic Safari browser TLS fingerprint
"edge" Mimic Edge browser TLS fingerprint
"random" Random browser fingerprint per connection
"none" Standard Go crypto/tls (no fingerprint mimicry)

Response

Field Type Description
name string Listener name
listen_addr string Actual address the proxy is listening on
status string Proxy state ("running")
tcp_forwards object Configured TCP forwarding map (if any)
protocols string[] Enabled protocols (if explicitly configured)

Examples

Start with defaults

// proxy_start
{}

Start on a custom port

// proxy_start
{
  "listen_addr": "127.0.0.1:9090"
}

Start with capture scope and TLS passthrough

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "capture_scope": {
    "includes": [
      {"hostname": "api.target.com"},
      {"hostname": "*.target.com", "url_prefix": "/api/"}
    ],
    "excludes": [
      {"hostname": "static.target.com"}
    ]
  },
  "tls_passthrough": ["*.googleapis.com", "accounts.google.com"]
}

Start with intercept rules

// proxy_start
{
  "intercept_rules": [
    {
      "id": "target-host",
      "enabled": true,
      "direction": "request",
      "conditions": {
        "host_pattern": "httpbin\\.org"
      }
    },
    {
      "id": "admin-api",
      "enabled": true,
      "direction": "request",
      "conditions": {
        "host_pattern": "api\\.target\\.com",
        "path_pattern": "/api/admin.*",
        "methods": ["POST", "PUT", "DELETE"],
        "header_match": {"Content-Type": "application/json"}
      }
    }
  ]
}

Start with TCP forwarding (string format)

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "tcp_forwards": {
    "3306": "db.example.com:3306",
    "6379": "redis.example.com:6379"
  }
}

Start with TCP forwarding (ForwardConfig with protocol detection)

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "tcp_forwards": {
    "50051": {
      "target": "api.example.com:50051",
      "protocol": "grpc"
    },
    "8443": {
      "target": "secure.example.com:443",
      "protocol": "http2",
      "tls": true
    },
    "3306": "db.example.com:3306"
  }
}

Start with specific protocols

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "protocols": ["HTTP/1.x", "HTTPS", "gRPC"]
}

Start with SOCKS5 password authentication

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "socks5_auth": "password",
  "socks5_username": "proxyuser",
  "socks5_password": "proxypass"
}

Start multiple listeners

// proxy_start
{
  "name": "http-listener",
  "listen_addr": "127.0.0.1:8080"
}

// proxy_start
{
  "name": "socks-listener",
  "listen_addr": "127.0.0.1:1080",
  "protocols": ["SOCKS5"]
}

Start with TLS fingerprint

// proxy_start
{
  "listen_addr": "127.0.0.1:8080",
  "tls_fingerprint": "firefox"
}