Pass-Through Containment

Pass-Through containment decides what WePROXA does with a request that no Map Local rule answered. By default it forwards the request upstream, which is what a proxy normally does. The deny modes turn WePROXA into a sealed environment instead, so an exploration or fixture-building run cannot silently reach a real service because a mock is missing.

This is the difference between a run that passes because your fixtures cover the flow and a run that passes because production quietly answered the calls they missed.

Not the same as TLS passthrough hosts

TLS passthrough hosts in Settings → Proxy Config keep specific HTTPS hosts tunneled instead of decrypted — see SSL Interception. Pass-Through containment is unrelated: it governs whether an unmatched request is forwarded at all.

Modes

Mode	Behavior
allow	Forward unmatched requests upstream. The default and the historical behavior.
denyUnmatched	Refuse any request no Map Local rule answered, without contacting the origin. Requests a rule does answer are served normally.
denyAll	Refuse every request, whether or not a rule would have matched.

denyUnmatched is the mode for building a fixture set: mocked traffic keeps working while everything you have not mocked yet fails loudly instead of reaching a real service. Use denyAll only when you want a total block.

What a denied request looks like

A denied request receives a synthetic 403 Forbidden generated by WePROXA, with an X-WePROXA-Passthrough header naming the mode that refused it. The status is deliberately not 502: a 502 would imply WePROXA talked to the origin and it failed, which is exactly what containment prevented.

Denials are recorded in the request list under the Pass-Through tool, keeping them distinct from a Block List rule and from a genuine 403 returned by a real server.

Host allow-list

Both deny modes accept a list of hosts that stay reachable. An entry is either an exact hostname or a wildcard of the form *.example.com, which covers example.com itself and every subdomain. Comparison is case-insensitive and up to 64 entries are accepted.

Use it for the things a contained run genuinely needs — a local dev server, an internal test domain, an auth service you are not mocking:

{ "mode": "denyUnmatched", "allowHosts": ["localhost", "*.internal.test"] }

Setting the mode replaces the previous allow-list rather than adding to it.

HTTPS and CONNECT tunnels

Under either deny mode, WePROXA also refuses blind CONNECT tunnels — HTTPS connections to hosts it is not decrypting. Traffic WePROXA cannot decrypt cannot be matched against a Map Local rule, so letting the tunnel through would be an unmatched request escaping containment through a channel nobody can inspect.

If a contained run fails on a host you expected to be mocked, check whether that host is being decrypted at all. Add it under SSL Interception, or add it to the allow-list if it is meant to stay reachable and encrypted.

Containment is never restored at launch

Containment is deliberately not persisted. Every launch starts in allow, including when the Scenario restored at startup declares containment. A proxy that came back up refusing traffic with no visible reason is far worse than one that forgot a setting, so containment is only ever applied by an activation or an explicit call — never by a restore.

Never assume a run is still contained. Confirm it before you trust a green result.

Carrying containment in a Scenario

Containment is a property of the setup you are testing, not of the machine, so a Scenario can declare it. Activating that Scenario installs the containment along with its rules, and it travels inside an exported bundle, so a sealed environment does not have to be re-established by hand on every machine.

WePROXA records who put the live policy in force — default, manual, or scenario — which is what makes reverting safe:

• Switching to a Scenario that declares nothing reverts containment a previous Scenario installed.
• It leaves a manually set policy alone. Someone who sealed the proxy by hand did not ask a Scenario switch to unseal it.
• Re-activating the Scenario that is already live re-asserts its containment, which is how you get back to a sealed proxy after a manual override.

If a Scenario’s declaration is invalid when it is activated, the declaration is skipped and logged rather than failing the whole activation — the Scenario’s rules are the reason you activated it, and skipping always leaves containment at least as strict as it already was.

Setting the mode

Containment is currently driven through the MCP server rather than a UI panel:

• weproxa_passthrough_setMode — set the mode and its allow-list.
• weproxa_passthrough_getMode — read the mode, its allow-list, and its source. Call this before a run to confirm containment is actually active.
• weproxa_scenarios_setPassthrough — declare the containment a Scenario installs when activated. Omit the value to clear the declaration.

See MCP Integration for the tool reference and Agent Skills for a complete contained fixture-building workflow.

Map Local must be enabled

Under denyUnmatched, a disabled Map Local tool means no rule can match, so every request is denied. Check the tool state before blaming the rules.

Finding what is still unmocked

Containment tells you a request was not covered; weproxa_requests_listUnmatched tells you which endpoints those were. It returns captured requests that matched no Map Local rule, deduplicated by method and URL pattern, each with a glob you can pass straight to a new rule. Repeat until nothing is left unmatched — new endpoints keep appearing as fixtures unblock later screens.

Pair it with capture sessions when you need to compare runs rather than discard the previous one.