Skip to content

fix: add EM-DELEGATE to enforcement mode docs #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beonde merged 3 commits into from
Mar 21, 2026
Merged

fix: add EM-DELEGATE to enforcement mode docs #32

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f8ade08
fix: add EM-DELEGATE to enforcement mode docs
beonde Mar 21, 2026
7829743
fix: address review — reword EM-DELEGATE, add to staleness table
beonde Mar 21, 2026
0c2d1f4
fix: add EM-DELEGATE to Embedded PDP Step 3 enforcement progression
beonde Mar 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion docs/how-to/security/policy-enforcement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,9 @@ export CAPISCIO_ENFORCEMENT_MODE=EM-OBSERVE
# Deny unauthorized — PDP DENY blocks requests (fail-closed on PDP failure)
export CAPISCIO_ENFORCEMENT_MODE=EM-GUARD

# Best-effort obligations — DENY blocks; ALLOW obligations attempted but failures don't block
export CAPISCIO_ENFORCEMENT_MODE=EM-DELEGATE

# Full enforcement — unknown obligation types also cause denial
export CAPISCIO_ENFORCEMENT_MODE=EM-STRICT
```
Expand All @@ -90,6 +93,7 @@ When the embedded PDP's policy bundle hasn't been rebuilt within the staleness t
|------|-----------|
| `EM-OBSERVE` | Request proceeds; `staleness.bundle_stale` annotation in telemetry |
| `EM-GUARD` | Request proceeds; `staleness.bundle_stale` annotation in telemetry |
| `EM-DELEGATE` | Request proceeds; `staleness.bundle_stale` annotation in telemetry |
| `EM-STRICT` | Request denied with `BUNDLE_STALE` error code |

Configure staleness via:
Expand Down Expand Up @@ -160,6 +164,14 @@ export CAPISCIO_ENFORCEMENT_MODE=EM-GUARD

Now PDP DENY decisions block requests with `403 Forbidden`. If the PDP is unavailable, requests are denied with `503 Service Unavailable` (fail-closed).

For stricter obligation handling, use `EM-DELEGATE`:

```bash
export CAPISCIO_ENFORCEMENT_MODE=EM-DELEGATE
```

In EM-DELEGATE, DENY decisions always block requests. For ALLOW decisions, all attached obligations are executed on a best-effort basis: failures are logged but do not change the ALLOW decision or block the request.

Comment on lines +167 to +174
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Embedded PDP “Step 3: Tighten Enforcement” code block earlier in this document still lists only EM-OBSERVE, EM-GUARD, and EM-STRICT (no EM-DELEGATE). Since this PR adds EM-DELEGATE to the mode progression, please update that earlier Embedded PDP snippet as well to avoid conflicting guidance within the same doc.

Suggested change
For stricter obligation handling, use `EM-DELEGATE`:
```bash
export CAPISCIO_ENFORCEMENT_MODE=EM-DELEGATE
```
In EM-DELEGATE, DENY decisions always block requests. For ALLOW decisions, all attached obligations are executed on a best-effort basis: failures are logged but do not change the ALLOW decision or block the request.

Copilot uses AI. Check for mistakes.
Copy link
Member Author

@beonde beonde Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 0c2d1f4. Added EM-DELEGATE to the Embedded PDP Step 3 code block, positioned between EM-GUARD and EM-STRICT in the enforcement mode progression.

For full obligation enforcement, use `EM-STRICT`:

```bash
Expand Down Expand Up @@ -202,7 +214,7 @@ All PDP-related environment variables:
| `CAPISCIO_EMBEDDED_PDP` | `false` | Enable embedded OPA evaluator (in-process PDP) |
| `CAPISCIO_PDP_ENDPOINT` | _(empty)_ | External PDP URL. Empty + no embedded PDP = badge-only mode |
| `CAPISCIO_PDP_TIMEOUT_MS` | `500` | External PDP query timeout in milliseconds |
| `CAPISCIO_ENFORCEMENT_MODE` | `EM-OBSERVE` | One of: `EM-OBSERVE`, `EM-GUARD`, `EM-STRICT` |
| `CAPISCIO_ENFORCEMENT_MODE` | `EM-OBSERVE` | One of: `EM-OBSERVE`, `EM-GUARD`, `EM-DELEGATE`, `EM-STRICT` |
| `CAPISCIO_WORKSPACE` | _(empty)_ | Workspace/tenant UUID (required for embedded PDP) |
| `CAPISCIO_BUNDLE_POLL_INTERVAL` | `30s` | Embedded PDP bundle rebuild interval |
Comment on lines +217 to 219
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The config reference now lists EM-DELEGATE, but the earlier “Embedded PDP → Step 3: Tighten Enforcement” snippet and the “Bundle Staleness” mode table still only mention EM-OBSERVE, EM-GUARD, and EM-STRICT. To avoid conflicting guidance within the same doc, update those earlier sections to include EM-DELEGATE (and document its staleness behavior if applicable).

Copilot uses AI. Check for mistakes.
Copy link
Member Author

@beonde beonde Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 7829743. Added EM-DELEGATE row to the Bundle Staleness behavior table. The Step 3 section already has the EM-DELEGATE code block and explanation from the initial commit.

| `CAPISCIO_BUNDLE_STALENESS_THRESHOLD` | `5m` | Embedded PDP bundle age before staleness warnings |
Expand Down
Loading