Shadow Bouncer deployment

Updated guide: For the full shadow compliance lifecycle (Deploy → Fingerprint → Select → Observe → Report → Enforce), start at Shadow compliance discovery. This page remains the Bouncer-level reference for BOUNCER_ENFORCEMENT_MODE=shadow.

Shadow mode is the recommended starting posture for every new deployment. It lets you deploy standard Control Core with zero enforcement risk. The Bouncer evaluates every request through your policy engine (same Rego bundles as production), but always forwards traffic upstream. Decisions that would have been denied are recorded as SHADOW_WOULD_DENY audit events for compliance mapping in the Sovereign Compliance Dashboard.

Time estimate: 45 minutes for first shadow Bouncer + dashboard verification.

What is Shadow Bouncer mode?

Shadow Bouncer mode is toggled by a single environment variable on the universal Bouncer image:

BOUNCER_ENFORCEMENT_MODE=shadow

Switching from shadow to enforce mode requires only a single environment variable change — no image swap, no migration, no downtime window.

Why financial institutions use shadow mode

Canadian FIs often need evidence before inline enforcement:

• OSFI B-13 — technology and cyber risk visibility without blocking production APIs
• FINTRAC — map transaction and KYC field exposure against PCMLTFA controls
• PIPEDA / Bill C-27 — classify personal information fields before masking policies go live

Shadow mode produces audit-grade telemetry and gap analysis without changing application behavior.

Architecture overview

Key invariant: semantic classification runs in the Control Plane API (schema-time SSIE), not in Bouncer Go code. The Bouncer remains resource-agnostic.

Deployment models

Model A — Dedicated shadow Bouncer (recommended)

Deploy a sandbox Bouncer with BOUNCER_ENFORCEMENT_MODE=shadow. Point test clients or synthetic traffic at the shadow listener. Production traffic is unchanged.

Model B — Traffic mirror (Phase 2)

Use Bouncer request mirroring to copy a percentage of live production traffic to a shadow Bouncer. Production path stays on the enforce Bouncer; mirror cluster receives a copy only.

See the traffic mirror cluster example shipped with your Helm chart (traffic-mirror-cluster.example.yaml) and the shadow values overlay (values-shadow.yaml).

Model C — Docker Compose (Kickstart)

Add to the Bouncer service environment in your compose override:

environment:
  BOUNCER_ENFORCEMENT_MODE: shadow

Restart the Bouncer container — no rebuild required if using the standard image.

How to deploy (Helm)

Prerequisites: Helm chart from customer package; sandbox Bouncer enabled.

1. Apply the shadow values overlay:

helm upgrade --install controlcore ./controlcore \
  -f values.yaml \
  -f values-shadow.yaml \
  --set global.shadowPilot.enabled=true

2. Confirm the Bouncer pod environment:

kubectl exec deploy/<bouncer-service-name> -- printenv BOUNCER_ENFORCEMENT_MODE
# Expected: shadow

3. In Control Plane Settings → Feature Flags, enable:

   • Integrity pilot mode
   • Sovereign compliance dashboard
   • Shadow enforcement mode (Bouncer)

4. Open Compliance & Gaps in the sidebar (/compliance).

Troubleshooting: If the compliance nav item is hidden, check effective feature flags at Settings → Feature Flags. See Troubleshooting.

How to deploy (Kickstart / Compose)

1. Set BOUNCER_ENFORCEMENT_MODE=shadow on the sandbox Bouncer service.
2. Restart: docker compose restart <bouncer-service-name> (service name from your compose file).
3. Send authenticated traffic against a route with an activated deny control.
4. Verify upstream returns success while Audit shows SHADOW_WOULD_DENY.

Expected outcomes

After 24–48 hours of representative traffic:

SSIE and regulation packs

The Semantic Schema Inference Engine (SSIE) runs as a scheduled worker in the Control Plane API. It classifies resource schema fields (OpenAPI, inventory metadata) and publishes semantic tags through the Policy Bridge for policy engine evaluation.

Regulation packs (YAML) map tags to frameworks:

• OSFI B-13
• FINTRAC PCMLTFA
• PIPEDA / Bill C-27
• PCI-DSS v4

Canadian control templates under canadian-financial-regulation/ consume these tags — they do not hardcode role names or remediation prose in Rego.

Trigger a manual SSIE cycle from the API:

curl -X POST "$PAP_API/v1/compliance/ssie/run" \
  -H "Authorization: Bearer $TOKEN"

Upgrade path to enforcement

When gap analysis is acceptable:

1. Run Policy Impact Simulator on critical deny paths.
2. Change BOUNCER_ENFORCEMENT_MODE to enforce on a non-production Bouncer first.
3. Validate deny/mask behavior with test clients.
4. Roll enforce mode to production Bouncers during a change window.
5. Optionally disable Integrity pilot mode to show full enforcement UI surfaces.

Same image. Same Control Plane database. No migration to a different product SKU.

FAQ

Does shadow mode skip the policy engine?

No. The policy engine runs the identical query path. Only the enforcement of the decision changes (always allow upstream).

Can shadow mode accidentally block traffic?

No. The Bouncer startup path treats shadow as bypass on all deny branches. For architecture evidence and supply-chain verification, see Supply chain verification.

Does my application need changes?

No. Your protected application remains policy-blind. Compliance surfaces live only in the Control Plane UI.

Is SSIE reading live request bodies?

No. SSIE classifies schema-time metadata (discovery/inventory), aligned with the existing ERP classification worker pattern.

How do I mirror production traffic?

Enable bouncerSandbox.trafficMirror in values-shadow.yaml, mount traffic-mirror-cluster.example.yaml, and start with a low mirror percentage (e.g. 10%).

Where is supply-chain verification documented?

See Supply chain verification — it covers cosign signing, SBOM attestations, vulnerability gates, and architecture evidence for procurement reviews.

Verification checklist

• BOUNCER_ENFORCEMENT_MODE=shadow on shadow Bouncer
• Feature flags enabled for compliance dashboard
• /compliance loads in Control Plane UI
• Test request produces SHADOW_WOULD_DENY in audit
• Upstream API still returns 200 for would-deny path
• SSIE cycle completes (POST /v1/compliance/ssie/run)
• Gap cache shows at least one entry after schema discovery
• Executive report generates JSON

Related guides

• Network Bouncer configuration
• Multiple Bouncers
• Production PBAC blueprint
• Troubleshooting