Skip to main content

Deploy the sidecar PEP

Goal: run the sidecar next to an agent you control and point its egress at it, so every outbound call is decided and narrowed before it's forwarded.

This is the enforcement point to reach for when you control the agent process. If you don't, see Deploy the gateway PEP or Deploy a boundary adapter PEP instead — see Enforcement point tradeoffs for how to choose.

1. Write the sidecar config​

sidecar.yaml
pdp_url: http://localhost:8000
listen_addr: 127.0.0.1:8081
upstream_map:
  /kb: http://localhost:9000

upstream_map is the only routing table the sidecar has — a path prefix that isn't listed is refused, not forwarded to a guess.

2. Run it​

agentic-auth-sidecar --config sidecar.yaml

3. Point the agent's egress at the sidecar instead of the real upstream​

curl -sS localhost:8081/kb/search -H "Authorization: Bearer $HOP_TOKEN"

Expected: the upstream (localhost:9000 in this example) receives a request with Authorization replaced by a freshly narrowed token — its aud is the mapped target and its hop is one greater than $HOP_TOKEN's. The presented token itself never reaches the upstream.

4. Confirm the unmapped-path case​

curl -sS localhost:8081/unmapped/thing

Expected: 403 UPSTREAM_NOT_MAPPED, and the upstream receives nothing.

5. Confirm it fails closed​

Stop the control plane, leave the sidecar and upstream running:

curl -sS -i localhost:8081/kb/search -H "Authorization: Bearer $HOP_TOKEN"

Expected: 503 with details.reason: PDP_UNAVAILABLE, and zero requests logged by the upstream — not a timeout that eventually forwards. Restart the control plane and confirm the denial was still recorded via Query a delegation chain or the audit decisions endpoint.

Why nothing can bypass this​

Forwarding is reachable from exactly one code path in sidecar/enforce.py — there is no second route to the upstream that skips the decide → exchange sequence. See PEP — Sidecar for the full request sequence, including the observe-mode behavior if you want to see what would be blocked without enforcing it yet.