HTTP/HTTPS Proxy

The HTTP/HTTPS proxy lets the Bridge sit in front of a user’s outbound web traffic so it can be recorded and controlled. Instead of brokering a single server, it brokers web requests: the user configures their browser, CLI, or application to send traffic through the Bridge, and the Bridge forwards each request to its destination while capturing a full record of what was sent and what came back.

This is an explicit proxy, meaning clients are deliberately pointed at it (as opposed to traffic being silently intercepted). It is the only protocol in this section that has no browser mode - there is nothing to render in a web page; instead clients are configured to route through it.

What gets captured

When recording is enabled, requests and responses use HAR format for URLs, headers, timing, and bodies, subject to redaction and max_body_record. WebSocket and SPDY upgrades record the handshake, byte counts, and duration. They do not capture stream contents or provide terminal replay.

Target bearer tokens

In v3.0.2 and later, an HTTP checkout can hold an API bearer token in target_password. Bridge authenticates the user through Proxy-Authorization, then replaces the destination’s Authorization header with Bearer <token>. The user does not need the target token. With an empty target_password, Bridge preserves the client’s destination Authorization header.

Bearer checkouts require an exact target_host and an explicit target_port. Bridge sends the token only to that HTTPS host and port, even if capture scope includes more hosts. It also replaces Host with that destination. Plain HTTP and other destinations are refused.

Target certificate verification is mandatory. Supply a private CA in target_ca_cert if needed. target_tls_skip_verify: true is rejected. The destination port must also be allowed by http_proxy.connect_ports.

HTTPS interception is required for bearer injection even when record_session is false. Clients must still trust the Bridge MITM CA. See Use kubectl through Bridge for a complete setup using a separate Bridge password and a server-held Kubernetes token.

What “MITM” means here

For ordinary HTTP, the Bridge can read the traffic directly. For HTTPS, the traffic is encrypted end to end, so the proxy could normally see only that some encrypted data passed by - not the actual requests and responses.

To record HTTPS, the proxy performs what is called MITM (man-in-the-middle): the Bridge decrypts each HTTPS request so it can record it, then re-encrypts it before sending it on to the real destination - and does the same with the response on the way back. In effect the Bridge terminates the user’s secure connection, reads the contents for the recording, and opens a fresh secure connection onward.

For this to work without the user’s client raising security warnings, the client must trust a certificate authority that the Bridge controls.

The MITM certificate authority (CA)

A certificate authority is a trusted issuer of the certificates that make HTTPS work. The Bridge runs its own CA so it can mint a certificate on the fly for each site a user visits. By default the Bridge generates this CA automatically the first time it needs one.

http_proxy:
  mitm:
    ca_cert_path: "/data/certs/ca.pem"
    ca_key_path: "/data/certs/ca-key.pem"
    auto_generate_ca: true
    ca_common_name: "Britive Bridge CA"
    ca_organization: "Britive"
    ca_validity: "87600h"   # 10 years
    leaf_validity: "24h"

• ca_validity is how long the CA itself is valid - by default 10 years (87600h).
• leaf_validity is how long each per-site certificate the CA mints is valid - by default 24h.

Capture is per checkout

The proxy does not capture everything indiscriminately. Capture scope is tied to active checkouts. A request is only proxied and recorded if its destination host matches an active checkout. If a user’s traffic goes to a host that does not match any active checkout, that request is blocked - the proxy will not forward it.

This keeps the recording focused on the access that was actually granted, and prevents the proxy from becoming an open gateway to the wider internet.

Turning it on

http_proxy:
  enabled: true
  listen: "8443"
  allow_http2: true
  max_body_record: 65536

• listen is the port the proxy accepts connections on.
• allow_http2 lets the proxy use HTTP/2 to capture-eligible destinations.
• max_body_record is the largest request or response body (in bytes) that will be written to the HAR record - the default is 65536, i.e. 64 KB. Bodies larger than this are truncated in the recording.

Redaction

Because the proxy records full requests and responses, it actively masks secrets before writing them to the recording. Three base lists control what gets redacted: sensitive header names, sensitive query-string parameters, and sensitive fields inside request/response bodies. Each comes with sensible defaults.

http_proxy:
  sanitize_headers:
    - authorization
    - proxy-authorization
    - cookie
    - set-cookie
    - x-api-key
    - x-auth-token
    - x-csrf-token
  sanitize_query_params:
    - token
    - access_token
    - refresh_token
    - key
    - secret
    - sig
    - signature
    - password
  sanitize_body_fields:
    - token
    - access_token
    - refresh_token
    - key
    - secret
    - password
    - client_secret
    - authorization

Full example

http_proxy:
  enabled: true
  listen: "8443"
  allow_http2: true
  max_body_record: 65536
  sanitize_headers:
    - authorization
    - cookie
  sanitize_query_params:
    - token
    - password
  sanitize_body_fields:
    - password
    - client_secret
  mitm:
    auto_generate_ca: true
    ca_common_name: "Britive Bridge CA"
    ca_organization: "Britive"
    ca_validity: "87600h"
    leaf_validity: "24h"

Option reference

Session lifetime and recordings

Revocation, expiry, checkout replacement, owner termination, or administrator disconnect closes the checkout’s tunnels and in-flight requests. Reusing an eligible checkout after a finished session starts a new session and recording. Graceful shutdown finalizes recordings; a crash leaves recoverable journal data on the shared recording volume.

WebSocket and SPDY upgrades use HTTP/1.1 for the upstream handshake, including when the target also offers HTTP/2. Watch and follow-log responses deliver chunks as they arrive. Compressed recorded responses remain readable, and each request reports when its body exceeds the recording limit.