Enforcement Modes
By default OpenProdkt fails open for three situations: the tool or asset is not registered, no policy is assigned to it, or policies are assigned but none match the call. These calls are allowed. See Reason Codes and the Security Model.
The enforcement mode is an organization setting. permissive is today's behavior, observe lets you preview a stricter posture without changing what any caller experiences, and strict turns the default-allow behavior into a deny. Overrides let one environment or asset type use a different mode, the kill switch stops all calls in a scope, and break-glass temporarily allows one asset that strict would deny.
How a call is decided
Two checks come before policy evaluation, and the mode applies only to calls that no policy decides.
An active kill switch denies first. Next, in strict mode, a call whose tool definition differs from its pin is denied; this check does nothing for a tool with no pin. Otherwise a matching policy decides exactly as it does in every mode, and only a call that no policy decides reaches the mode.
The mode treats those calls as follows. In strict, an active break-glass grant on a registered asset allows the call again with its original reason.
permissive allows the call. observe allows it and records an enforcement.would_deny event. strict denies it with a default_deny_* reason unless an active break-glass grant covers the asset.
Available modes
| Mode | Behavior | Status |
|---|---|---|
permissive | Today's behavior. Unregistered, unassigned and unmatched calls are allowed. Nothing extra is recorded. | Default for every organization |
observe | The same responses as permissive. In addition, each call that a stricter mode would deny is recorded as a would-deny event. | Available |
strict | Denies those calls. See Strict mode. | Available, opt-in |
permissive and observe never change a decision response, a status code, billing, approvals or what is sent to your upstream. A new organization starts in permissive, and no organization changes mode on its own.
Overrides
An override gives one environment, one asset type or one risk tier its own mode. For example, keep the organization in permissive and set strict for the production environment, set observe for every mcp_tool asset, or set strict for every asset whose risk tier is high.
| Field | Meaning |
|---|---|
dimension | environment, asset_type or risk_tier. |
value | The environment, asset type or risk tier to match. An asset's environment is the one set on its group. For environment and asset_type it is 1 to 128 characters, matched exactly and case-sensitively; asset types in use today are service_operation and mcp_tool. For risk_tier it is one of minimal, limited, high or prohibited_check. |
mode | permissive, observe or strict. |
The risk tier is the risk_tier that you set in an asset's ai_inventory. It selects the enforcement mode only: it never makes outcome reporting required and it does not change any policy decision. An asset with no risk tier matches no risk_tier override.
The mode that applies to a call is chosen as follows:
An unregistered asset always uses the organization mode, because its environment and type come from the caller and must not select a laxer mode. For a registered asset the matching override applies; if several overrides match (for example an environment override and a risk-tier override), the strictest mode wins (permissive, then observe, then strict). With no match the organization mode applies. An override may be laxer than the organization mode, for example permissive for one environment while the organization is strict.
- What an override changes. The effective mode drives both
strictdenies andobserverecording, so anobserveoverride records would-deny events for its assets even while the organization ispermissive, and apermissiveoverride records nothing even while the organization observes. Calls that a policy decides are never affected. A kill switch is checked before any mode. - Who and how. Only a signed-in
super_admincan set or remove an override, and astrictoverride needs the sameacknowledge_denies: trueas the organization setting. API keys never can. In the Console, open Settings and use Overrides in the enforcement card. Setting the mode an override already has changes nothing and records nothing. - Limit. At most 50 overrides per organization. A 51st returns
409override_limit_reached; changing an existing override still works, and removing one frees a slot. - Audit. Each change is written to the audit trail as
enforcement.override.changed(organization, actor, dimension, value, mode,setorremovedaction, and the previous mode when one existed) in the same transaction as the change, and the history is kept. - Failure. If the effective mode cannot be resolved while a call is handled, the call is handled as
permissive, like an unreadable organization mode.
GET /v1/enforcement/overrides returns enforcement-overrides.v1 (overrides ordered by dimension, then value, and the limit); PUT /v1/enforcement/overrides takes {dimension, value, mode, acknowledge_denies?} and returns the override; DELETE /v1/enforcement/overrides/{id} returns 204. Errors: 400 invalid_dimension, invalid_value (including a risk tier that is not one of the four), invalid_mode, acknowledgement_required; 404 for an unknown override or one that belongs to another organization.
Strict mode
In strict, the three default-allow situations are denied instead (HTTP 403, decision deny, the same response shape as a policy deny). The reason tells you which one it was:
| Situation | Reason in strict | Recorded as a decision | Counted toward your decision quota |
|---|---|---|---|
Policies are assigned but none match (no_matching_policy) | default_deny_no_match | Yes | Yes |
The asset is registered but has no published, active policy (no_policies_assigned) | default_deny_no_match | Yes | No |
No registered asset matches the call (asset_not_registered) | default_deny_unregistered | No | No |
- Policies still decide first. A call that matches a policy is allowed, denied or sent for approval exactly as before. Only the three situations above change.
- Break-glass. An active break-glass grant on a registered asset allows the two registered cases above (
no_matching_policyandno_policies_assigned) for that asset only, with their original allow reason. It never covers an unregistered asset, a policy deny, an approval requirement or a kill switch. - Overrides. Which mode a call gets can depend on an override for its environment or asset type.
- Discovery continues. A denied call for an unregistered asset is still queued for asset discovery, so you can register it.
- Audit. A denied call that has a decision record appears as
decision.evaluatedwith resultdeny. A denied call for an unregistered asset has no decision record, so anenforcement.deniedevent is written instead (organization, reason, mode, time, transport, operation ID when valid, and asha256:digest of the asset key, never the key). It is written by a background worker shortly afterwards and is best effort; the call is denied either way. It is not exported to write-once storage and triggers no notification or webhook. - Your integrations. The SDKs, the MCP adapter and the Envoy adapter treat these as ordinary denies and show the reason. The Envoy adapter includes
reasonin its deny body for these two codes and forkill_switch_active, and for no other new reason. Make sure your application handles a deny for calls it used to get through. - Failures. A policy-engine outage still denies and never calls your upstream, in every mode. If the mode setting itself cannot be read while a call is being handled, that call is handled as
permissive, so an unreadable setting never newly blocks traffic. The kill switch behaves the other way: if its state cannot be read, the call is denied. - Turning it on. Only a signed-in
super_admincan, and only with an explicit acknowledgement:PUT /v1/enforcementwith{"mode": "strict", "acknowledge_denies": true}. Without it the request is refused withacknowledgement_required. The Console asks you to confirm and states that calls will be blocked immediately. Useobserveand the shadow report first to see whatstrictwould block. Switching back topermissiveorobservetakes effect immediately.
What observe records
When the organization is in observe, a real decision that is allowed for one of these reasons records one enforcement.would_deny audit event:
| Reason class | Meaning |
|---|---|
no_matching_policy | Policies are assigned but none matched. |
no_policies_assigned | The asset is registered but has no published, active policy. |
asset_not_registered | No registered asset matches the call. |
Calls that matched a policy (allow, deny or approval required) record nothing, and neither does the Console playground.
Each event carries: the organization, the reason class, the mode (observe), the time, the transport (http, grpc or mcp) when known, the decision ID when a decision was recorded, the asset ID when the asset is registered, and the operation ID when you supplied a valid one. For an unregistered asset the event carries only a sha256: digest of the asset key, never the key. Arguments, request bodies, prompts, secrets and metadata are never recorded.
- Best effort. The mode is read and the event is queued while the call is handled, and a background worker writes the audit event a short time later. If either step fails, the call still completes unchanged and the would-deny event may be missing. Counts can therefore be too low.
- Not exported. These events are readable in the audit trail but are not part of the export to write-once storage, and they do not trigger notifications or webhooks.
- Not billed. Recording a would-deny event adds no usage.
Who can read and change it
| Action | Endpoint | API key | super_admin | billing_admin | user | auditor |
|---|---|---|---|---|---|---|
| Read the mode | GET /v1/enforcement | policies:read | Allow | Allow | Allow | Allow |
| Change the mode | PUT /v1/enforcement | Refused | Allow (user JWT) | Deny | Deny | Deny |
| Read the shadow report | GET /v1/enforcement/shadow-report | audit:read | Allow | Allow | Owned assets only | Allow |
| Read overrides | GET /v1/enforcement/overrides | policies:read | Allow | Allow | Allow | Allow |
| Set or remove an override | PUT and DELETE /v1/enforcement/overrides | Refused | Allow (user JWT) | Deny | Deny | Deny |
Only a signed-in super_admin can change the mode or an override. API keys never can. Each mode change is written to the audit trail as enforcement.mode.changed (organization, actor, new mode, previous mode) together with the change itself, and the change history is kept. Setting the mode the organization already has changes nothing and records nothing. Reading and changing the mode need a plan that includes policy features. The Console shows the setting under Settings, in the same card as Overrides, Kill switch and Break-glass. Kill switch and break-glass permissions are on their own pages: Kill Switch and Break-Glass.
PUT /v1/enforcement takes {"mode": "permissive"}, {"mode": "observe"} or {"mode": "strict", "acknowledge_denies": true} and returns enforcement.v1:
{
"version": "enforcement.v1",
"organization_id": "org_123",
"mode": "observe",
"updated_at": "2026-11-16T05:00:00Z",
"updated_by": "usr_456"
}
updated_at and updated_by are omitted until the mode has been set at least once. Any other value returns 400 invalid_mode; strict without acknowledge_denies: true returns 400 acknowledgement_required and changes nothing. The flag is ignored for the other modes.
Shadow report
GET /v1/enforcement/shadow-report summarizes the recorded would-deny events: what a stricter mode would have denied while the organization was in observe. In the Console, open Audit and choose Show shadow report.
- Window. Optional
fromandto(RFC 3339,frominclusive,toexclusive, on the event time). The default is the last 30 days. A window longer than 90 days, orfromnot beforeto, returns400invalid_window; malformed values returninvalid_fromorinvalid_to. A window with more than 250,000 events returns400report_window_too_large: narrow it. A store failure or a query over 5 seconds returns503shadow_report_unavailable. - Contents.
total, a count for each of the three reason classes (always listed, zero when none), counts by transport, the registered assets with the most events (up to 50, with the asset name when it still exists), and up to 50 digests of unregistered asset keys with counts. It holds counts only: no operation IDs, decision IDs, asset keys or payloads.current_modeis the setting when the report was generated, not the mode during the window. - Who sees what. Organization-wide roles and auditors see the whole organization. Other users see only registered assets they own, and never unregistered-asset events.
- Caveats (always returned).
- The report covers only periods in
observe. Nothing is recorded inpermissive. - Recording is best effort, so counts can be under-counted.
- It is computed when you ask, from operational records. It is not write-once or sealed evidence.
- A quiet window does not mean nothing would be denied: it excludes time spent in
permissive. - It says nothing about calls that matched a policy.
- Each asset list shows at most 50 entries, ordered by count.
- The report covers only periods in
Limits
- Three settable modes:
permissive,observeandstrict. The default ispermissivefor every organization, including new ones. - Overrides: at most 50 per organization across all three dimensions; an
environmentorasset_typevalue is 1 to 128 characters. - Shadow report: window at most 90 days (default 30), at most 250,000 events per request, 50 entries per asset list, 5 second query limit. These are enforced limits, not a throughput guarantee.
See also Definition Pinning, Kill Switch, Break-Glass, Audit, Reason Codes, Access & Permissions, and the Security Model.