Security Model
This page describes what OpenProdkt enforces, what it trusts, and what happens when a dependency fails. Read it before you rely on governance for a tool, an asset, or an approval.
Trust boundaries
| Component | Where it runs | Trust |
|---|---|---|
| MCP client | Your host, launches the wrapper | Untrusted input. It chooses the tool name and arguments. |
| MCP PEP wrapper | Your host, between the client and the server | Enforces the decision. The server never sees a call that is not allowed. |
| MCP server | Your host, launched by the wrapper | Runs as the wrapper's user. Its environment is limited by child_env_allowlist. |
| Control plane (PDP) | OpenProdkt API | Makes every decision and records it. |
What the wrapper enforces
- A
tools/callis forwarded to the server only after the PDP returnsallow. denyandapproval_requiredreturn a tool result to the client. The server does not run the tool.
What the decision can and cannot verify
- The tool name and arguments come from the MCP client. The PDP decides on the values the wrapper sends. A policy that checks an argument is only as strong as that value.
- The PDP does not check what the tool does after it runs. Governance decides whether a call may run. It does not verify the effect.
- Use
asset_idto fix a tool's identity. A renamed server or tool otherwise creates a new identity that existing policies do not match.
Credentials
- The principal token is a credential. Store it in a file that only the wrapper's user can read. The wrapper reads it from
principal_token_file. - API keys and user sessions have different permissions. Approving, rejecting, and revoking approvals require a signed-in user session, not an API key.
- Roles and approval scope are described in RBAC.
Behavior when a dependency fails or a tool is not governed
The defaults below are deliberate. Read them before you assume a tool is blocked.
| Condition | Result | Default |
|---|---|---|
| PDP unreachable or timed out | Call denied with pdp_unavailable | Fail closed |
| Tool has no registered asset | Call allowed with asset_not_registered. The call is not recorded as a decision. The tool is queued for discovery. | Fail open (denied in strict mode) |
| Asset has no policies assigned | Call allowed with no_policies_assigned | Fail open (denied in strict mode) |
| Policies assigned, none match | Call allowed with no_matching_policy | Fail open (denied in strict mode) |
| Kill switch active for the organization or asset | Call denied with kill_switch_active | Fail closed (Kill Switch) |
| Kill switch state cannot be read | Call denied with HTTP 503 enforcement_unavailable | Fail closed |
| MCP tool definition differs from its pin | In strict mode the call is denied with definition_changed; otherwise allowed and recorded | Fail closed only in strict (Definition Pinning) |
| Definition pin cannot be read | Call handled as if there were no pin | Never newly blocks traffic |
| Enforcement mode or override cannot be read | Call handled as permissive | Never newly blocks traffic |
Break-glass grant cannot be read in strict mode | The strict deny stands | Fail closed |
| Policy evaluation error | Call not allowed | Fail closed |
| Approval rejected, revoked, expired, or consumed | Call denied with the matching reason | Fail closed |
To govern a tool, register it, attach a policy, and check the decision in the dashboard before you rely on it. See Reason codes for each reason.
At-most-once execution
- Each approval grant is consumed once. A retry after the grant is consumed returns
approval_consumedand does not run the tool again. - Outcome reports are first-wins for each operation. The first
ALLOWrecorded for an operation stands. A later outcome report for that operation from another principal is refused. - If the wrapper starts a tool and cannot confirm the result, the status is
execution_unknown. Check the server's side effects before you retry. See MCP Adapter.
Webhook destinations
- In SaaS mode, webhook targets must use HTTPS.
- Private and internal destinations are denied by default.
- Cloud metadata addresses are always blocked.
- Redirects are not followed.
- Self-hosted administrators can allow specific private ranges through explicit configuration. This is not a per-tenant setting. See On-Premises Webhook Destinations.
Audit and security limitations
State these limits to your reviewers. They are not hidden behaviors.
- Fail open by default. Unregistered tools, assets without policies, and requests that match no policy are allowed. Governance only covers what you register and attach policies to. The enforcement mode
observerecords what a stricter mode would deny without changing any decision, and an administrator can opt in tostrictto deny these calls, for the whole organization or for one environment or asset type through overrides. A kill switch stops all calls in a scope, and a break-glass grant lets one asset throughstricttemporarily, with a second person's approval. No organization changes mode on its own. - Decisions are not execution. OpenProdkt records that a call was allowed, not that it ran. Execution is recorded only when a reporter reports an outcome, and some paths (for example the Envoy MCP path) cannot report one. See Audit.
- Caller-supplied context. Policies decide on the values the caller sends. Identity fields come from authentication, but
metadatadoes not. - Operational records are mutable. Audit events, decision history, and approvals live in the operational database. Only exported records are written to Object Lock storage, and only after the export delay. The product does not claim a fully write-once trail or any compliance certification. See Audit.
- Request content. Audit events hold identifiers and results; decision history keeps request metadata. Do not put secrets in metadata.
- Correlation is not proof. Trace, execution and upstream request identifiers are supplied by callers and adapters and are not verified against upstream systems. They are not tamper-proof and are not a certification or compliance claim. See Audit.
- AI inventory is a customer assertion.
ai_inventoryandrisk_tierare labels you provide. OpenProdkt does not verify them and does not make a legal classification. The risk tier can select a stricter enforcement mode when you create an override for it, and it makes a reviewer comment mandatory on approvals forhighandprohibited_checkassets; it changes nothing else. Because a lower tier can loosen enforcement, only a signed-insuper_admincan lower an asset's tier. Changes are recorded asasset.risk.classifiedrecords that are not exported to write-once storage. See Audit. - Definition pinning detects, it does not authenticate. The digest of an MCP tool's definition comes from the caller, so a caller with a
decision:runcredential can send the approved digest. Pinning notices a tool that was changed after you approved it, as seen by an honest enforcement point. See Definition Pinning. - Webhooks are at-least-once. Receivers can see duplicates and must verify signatures and deduplicate on
eventId. - Limits are enforcement, not SLAs. See Limits and Configuration.
Rate limits
Integration traffic and dashboard traffic have separate budgets per organization. See Developer Guide.