Control CoreDocs

Deployment modes

Control Core ships one universal Bouncer binary. Deployment mode is a topology choice — where you place the PEP on the traffic path — not a separate product SKU.

Recommended first posture: Deploy every new Bouncer in shadow mode first. Observe would-deny telemetry and compliance gaps, then switch to enforce with a single environment variable when ready.

Empty first boot: On a fresh Control Plane with no Bouncers yet, the Control Plane enables shadow posture feature flags automatically (bouncer_flags.shadow_enforcement_mode, integrity_pilot_mode, compliance_dashboard). The Getting Started wizard Choose mode step confirms Shadow (default) or Full Intercept.

Mode comparison

ModePlacementBest forDay-1 posture
ShadowInline but non-blockingRecommended starting posture — compliance discovery, risk-free observationBOUNCER_ENFORCEMENT_MODE=shadow
SidecarCo-located container in the same pod as the workloadKubernetes microservices, low-latency co-locationShadow first, then enforce
Reverse proxyStandalone hop in front of upstream (DNS/VIP/LB target)Legacy on-prem, VM stacks, monoliths, shared edgeShadow first, then enforce

Troubleshooting: If audit shows zero decisions, traffic is bypassing the Bouncer. Confirm clients hit Bouncer :8080, not the app port directly. See Bouncer placement.

Shadow mode

Shadow mode evaluates every request through the policy engine but always forwards traffic upstream unchanged. Decisions appear as SHADOW_WOULD_ALLOW / SHADOW_WOULD_DENY in audit — ideal for compliance packs and gap reports before enforce.

BOUNCER_ENFORCEMENT_MODE=shadow
BOUNCER_TYPE=reverse-proxy   # or sidecar — shadow works with both

How to use

  1. Deploy Bouncer with shadow env vars (~10 min).
  2. Route representative traffic through the Bouncer for 24–72 hours.
  3. Open Compliance & Gaps → select compliance packs.
  4. Review gap report before upgrade to enforce.

How to review / audit

  • Control Plane → Audit Logs — filter event_type containing SHADOW_
  • Grafana dashboard cc-01-shadow-discovery — shadow event rate over time
  • Export compliance report for evidence packs

Troubleshooting: Shadow events missing? Confirm BOUNCER_ENFORCEMENT_MODE=shadow in running container: docker exec bouncer env | grep ENFORCEMENT. Restart after env change.

Sidecar mode

A sidecar Bouncer runs alongside your application container. Traffic from the app hits 127.0.0.1:8080 (or a shared network namespace) before leaving the pod.

BOUNCER_TYPE=sidecar
TARGET_HOST=127.0.0.1:3000    # your app listen port inside the pod
ENVIRONMENT=sandbox

How to use

  1. Add the Bouncer container to your pod spec (Helm subchart or manual sidecar).
  2. Point app egress (or ingress) at localhost:8080.
  3. Register resource name in Control Plane — Bouncer auto-registers within ~30s.

How to review / audit

  • Settings → PEPs — heartbeat and Policy Bridge sync status per sidecar
  • Grafana cc-05-bouncer-fleet — fleet heartbeats and sync lag

Troubleshooting: Sidecar cannot reach Control Plane? Check network policy allows egress to PAP_API_URL. docker exec <sidecar> curl -s $PAP_API_URL/api/v1/health.

Reverse proxy mode

The Bouncer terminates client connections and proxies to TARGET_HOST. Clients swap DNS or load-balancer target to the Bouncer VIP — zero application code change.

BOUNCER_TYPE=reverse-proxy
TARGET_HOST=my-api.internal:8080
ORIGINAL_HOST_URL=https://api.yourcompany.com

How to use

  1. Deploy Bouncer with reverse-proxy type (~15 min).
  2. Update DNS or LB backend to Bouncer :8080.
  3. Verify upstream health: curl -s http://localhost:8080/health | jq .status

How to review / audit

  • Send test traffic — confirm decisions in Audit Logs
  • Compare shadow vs enforce counts before cutover

Troubleshooting: 502 from Bouncer? Upstream unreachable — verify TARGET_HOST resolves inside Bouncer network namespace.

eBPF mode (roadmap — not shipped)

Kernel-level attachment via eBPF is on the product roadmap for high-throughput L4 observation. It is not available in current releases. Do not configure eBPF flags in production — use shadow, sidecar, or reverse proxy instead.

When eBPF ships, it will complement (not replace) Bouncer Bouncer intercept/Bouncer intercept for L7 control decisions. Track release notes for availability.

Auto-registration

Every mode registers the Bouncer with the Control Plane on startup:

  1. Bouncer POSTs to /peps/register with BOUNCER_ID, environment, and resource metadata.
  2. Control Plane creates or rebinds the Protected Resource row (~30s typical).
  3. Policy Bridge pushes the sandbox bundle to the new PEP.

Verify:

curl -s -H "Authorization: Bearer <token>" "$PAP_API_URL/health/bouncers" | jq '.bouncers[] | {id, status, last_heartbeat}'

Next steps: Quick deploy · Bouncer placement · Shadow discovery