Skip to main content

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​

ComponentWhere it runsTrust
MCP clientYour host, launches the wrapperUntrusted input. It chooses the tool name and arguments.
MCP PEP wrapperYour host, between the client and the serverEnforces the decision. The server never sees a call that is not allowed.
MCP serverYour host, launched by the wrapperRuns as the wrapper's user. Its environment is limited by child_env_allowlist.
Control plane (PDP)OpenProdkt APIMakes every decision and records it.

What the wrapper enforces​

  • A tools/call is forwarded to the server only after the PDP returns allow.
  • deny and approval_required return 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_id to 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.

ConditionResultDefault
PDP unreachable or timed outCall denied with pdp_unavailableFail closed
Tool has no registered assetCall 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 assignedCall allowed with no_policies_assignedFail open (denied in strict mode)
Policies assigned, none matchCall allowed with no_matching_policyFail open (denied in strict mode)
Kill switch active for the organization or assetCall denied with kill_switch_activeFail closed (Kill Switch)
Kill switch state cannot be readCall denied with HTTP 503 enforcement_unavailableFail closed
MCP tool definition differs from its pinIn strict mode the call is denied with definition_changed; otherwise allowed and recordedFail closed only in strict (Definition Pinning)
Definition pin cannot be readCall handled as if there were no pinNever newly blocks traffic
Enforcement mode or override cannot be readCall handled as permissiveNever newly blocks traffic
Break-glass grant cannot be read in strict modeThe strict deny standsFail closed
Policy evaluation errorCall not allowedFail closed
Approval rejected, revoked, expired, or consumedCall denied with the matching reasonFail 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_consumed and does not run the tool again.
  • Outcome reports are first-wins for each operation. The first ALLOW recorded 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 observe records what a stricter mode would deny without changing any decision, and an administrator can opt in to strict to 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 through strict temporarily, 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 metadata does 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_inventory and risk_tier are 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 for high and prohibited_check assets; it changes nothing else. Because a lower tier can loosen enforcement, only a signed-in super_admin can lower an asset's tier. Changes are recorded as asset.risk.classified records 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:run credential 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.