diff --git a/docs/how-to/security/policy-enforcement.md b/docs/how-to/security/policy-enforcement.md index e68f217..12c21af 100644 --- a/docs/how-to/security/policy-enforcement.md +++ b/docs/how-to/security/policy-enforcement.md @@ -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 ``` @@ -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: @@ -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. + For full obligation enforcement, use `EM-STRICT`: ```bash @@ -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 | | `CAPISCIO_BUNDLE_STALENESS_THRESHOLD` | `5m` | Embedded PDP bundle age before staleness warnings |