Neuwerk

TLS Interception

TLS-aware policy can either inspect handshake metadata or actively intercept HTTP inside TLS.

Use this guide when you need policy decisions based on TLS details.

Neuwerk supports two distinct TLS behaviors:

  • metadata mode inspects handshake metadata without terminating TLS
  • intercept mode terminates the client TLS session, opens a new upstream TLS session, and applies HTTP-aware policy inside the encrypted stream

Choose the lighter mode that solves your problem.

Start With Metadata Mode When Possible

Metadata mode is easier to operate because clients do not need to trust a new certificate authority.

Available matchers include:

  • SNI
  • certificate SAN and CN fields
  • certificate fingerprint
  • explicit trust anchors

Use this mode when the decision can be made from handshake and certificate metadata alone.

Use Intercept Mode Only For HTTP-Aware Policy

Intercept mode is for cases where you need to match on HTTP details such as:

  • request host
  • request method
  • request path
  • query parameters
  • headers
  • selected response headers

This mode is an active MITM boundary. It should be enabled only when the operational cost is worth the extra visibility.

Prerequisites For Intercept Mode

Interception becomes usable only when both of these are true:

  • the active policy contains at least one tls.mode: intercept rule
  • the Neuwerk has TLS intercept CA material available

The intercept CA is separate from the management HTTPS CA.

API endpoints exist to:

  • generate a new intercept CA
  • upload an existing one
  • download the current certificate for client trust distribution

What Clients Must Trust

When interception is enabled, the Neuwerk mints leaf certificates on demand from the intercept CA.

That means clients must trust the intercept CA. If they do not, TLS sessions will fail even if the policy itself is correct.

Enforcement Behavior

Metadata mode stays in the normal dataplane decision flow.

Intercept mode behaves differently:

  • traffic is selected for interception by the policy
  • the service runtime terminates the TLS session
  • HTTP request and response policy is evaluated inside the intercepted stream

In enforce mode, intercepted denials fail closed. In audit mode, the policy still evaluates but the Neuwerk does not actively block the request or response.

Current Limits

  • Intercept mode is for HTTP-over-TLS, not arbitrary non-HTTP protocols on port 443.
  • Metadata matchers and intercept matchers cannot be mixed in the same TLS block.
  • Some certificate-based metadata decisions need explicit tls13_uninspectable behavior for TLS 1.3.
  • The active intercept path currently supports IPv4 peers and IPv4 upstream destinations.

Safe Rollout Advice

  • Start with metadata mode if SNI or certificate fields are enough.
  • Distribute and validate the intercept CA before enabling intercept rules broadly.
  • Roll interception out to a narrow source group first.
  • Watch svc_fail_closed_total and intercept error metrics closely after enabling it.