docs: add embedded policy enforcement guide for local PDP#34
Conversation
✅ Documentation Build SuccessfulThe documentation build completed successfully and passed validation checks.
|
There was a problem hiding this comment.
Pull request overview
Adds a new How-To guide documenting how to use CapiscIO’s embedded/local PDP (in-process OPA) for policy evaluation inside agents, and wires it into the MkDocs navigation.
Changes:
- Added a new How-To page describing Local PDP setup, enforcement modes, staleness behavior, configuration options, build tags, and troubleshooting.
- Updated MkDocs nav to include the new How-To under Policy.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| mkdocs.yml | Adds the new “Embedded Policy Enforcement” page to the How-To → Policy nav section. |
| docs/how-to/embedded-policy-enforcement.md | New end-user guide for configuring and using the local/in-process PDP, including Go examples and operational guidance. |
|
|
||
| When the PDP cannot refresh its policy bundle (e.g., network issues), behavior depends on the enforcement mode: | ||
|
|
||
| - **EM-OBSERVE / EM-GUARD**: Continue evaluating with the last-known-good bundle |
There was a problem hiding this comment.
This staleness section omits EM-DELEGATE, even though it’s listed as a supported mode above. For consistency with the enforcement-mode reference (and the existing Policy Enforcement docs), document EM-DELEGATE staleness behavior explicitly (it likely matches EM-GUARD if it’s fail-open on bundle staleness).
| - **EM-OBSERVE / EM-GUARD**: Continue evaluating with the last-known-good bundle | |
| - **EM-OBSERVE / EM-GUARD / EM-DELEGATE**: Continue evaluating with the last-known-good bundle |
| | `CAPISCIO_ENFORCEMENT_MODE` | No | `EM-OBSERVE` | Enforcement strictness level | | ||
| | `CAPISCIO_POLL_INTERVAL` | No | `30s` | How often to check for policy updates | | ||
| | `CAPISCIO_MAX_AGE` | No | `10m` | Maximum bundle age before staleness | | ||
|
|
There was a problem hiding this comment.
Env var names here (CAPISCIO_POLL_INTERVAL, CAPISCIO_MAX_AGE) differ from the existing embedded-PDP docs (CAPISCIO_BUNDLE_POLL_INTERVAL, CAPISCIO_BUNDLE_STALENESS_THRESHOLD). If these are the same concepts, consider aligning the names or adding a short note clarifying why the local PDP uses different variables to avoid reader confusion.
| !!! note | |
| In other embedded-PDP documentation you may see the variables | |
| `CAPISCIO_BUNDLE_POLL_INTERVAL` and `CAPISCIO_BUNDLE_STALENESS_THRESHOLD` | |
| used for bundle polling frequency and staleness. In the local in-process PDP, | |
| these concepts are configured via `CAPISCIO_POLL_INTERVAL` and | |
| `CAPISCIO_MAX_AGE` as shown above. |
| resp, err := localPDP.Client.Evaluate(ctx, &pip.DecisionRequest{ | ||
| PIPVersion: pip.PIPVersion, | ||
| Subject: pip.SubjectAttributes{ | ||
| DID: incomingAgent.DID, | ||
| TrustLevel: incomingAgent.Badge.TrustLevel, |
There was a problem hiding this comment.
In the Go example, resp is used without checking err first. Please show error handling (and ideally a nil resp check) before inspecting the decision, so readers don’t copy a panic-prone pattern.
| }, | ||
| }) | ||
|
|
||
| if resp.Decision == "deny" { |
There was a problem hiding this comment.
Decision values are shown elsewhere in the docs as uppercase (e.g., ALLOW/DENY). Comparing resp.Decision to the lowercase string "deny" is likely incorrect and may mislead users—use the canonical decision value/constant instead.
| if resp.Decision == "deny" { | |
| if resp.Decision == "DENY" { |
Summary
Adds end-user documentation for the embedded / local Policy Decision Point (PDP) feature introduced in the data plane implementation (POLICY-DATA-PLANE-001).
Changes
docs/how-to/embedded-policy-enforcement.mdopa_no_wasm)mkdocs.ymlRelated PRs