Policies, rules and decisions#

A policy (kind ToolPolicy, short name tp) is a named set of rules for which agents may call which tools, and how. The operator renders every valid ToolPolicy in the cluster into one document, policies.json in the ConfigMap maqpna-policies, which the gateway hot-reloads (every policyReloadSeconds, default 2 seconds) without dropping connections.

How a decision is made#

flowchart TD
    R["Request: namespace, agent, session, user, groups,<br/>scopes, server, tool, args, session taints, sinks"] --> P{"Any policy applies?<br/>(namespace + agents globs)"}
    P -- no --> D0["deny · no_applicable_policy"]
    P -- yes --> E["For each applicable policy:<br/>rules in order, first match wins"]
    E --> M{"A rule matched?"}
    M -- yes --> RA["rule action<br/>(Cedar text in the same policy also votes,<br/>strictest wins)"]
    M -- no --> DA["policy defaultAction<br/>(deny when unset) · default_action"]
    RA --> C["Combine all policies:<br/>deny &gt; require_approval &gt; allow<br/>(ties: larger minApprovers)"]
    DA --> C
    C --> X{"Engine-wide external evaluator?<br/>(OPA sidecar)"}
    X -- yes --> C2["Stricter result wins"]
    X -- no --> RL
    C2 --> RL{"Result not deny and a matched rule<br/>has maxCallsPerMinute?"}
    RL -- "over limit" --> D1["deny · rate_limited"]
    RL -- "within limit" --> F["Final decision"]

The rules, step by step (pkg/policy):

1. A policy applies to a call when its namespace matches the caller's namespace and one of its agents globs matches the agent.
2. Within one policy, rules are evaluated in order; the first matching rule wins. A rule matches only when every matcher it sets passes, in this order: servers, tools, argMatch, principals, scopes, sessionTaints, sinks, schedule, when.
3. When no rule matches, the policy's defaultAction applies (deny when unset), with reason default_action.
4. When several policies apply, the most restrictive decision wins: deny, then require_approval, then allow. Between two require_approval decisions, the one asking for more approvers wins.
5. When no policy applies, the call is denied with reason no_applicable_policy.
6. Rate limits (maxCallsPerMinute, a 60-second sliding window per session, policy and rule) are counted only when the combined result would let the call through. A call that is denied anyway never uses up the limit.

Rule matchers#

A condition that cannot be evaluated safely (for example a regex over a value longer than 64 KiB) fails closed: deny and require_approval rules match, allow rules do not.

Dry run#

A policy with enforcement: dryRun is evaluated normally, but only contributes its dryRunFallback (allow, or its defaultAction) to the enforced decision. The gateway writes an extra ledger record with ext.dryRun=true and the decision the policy would have made, so you can roll out a stricter policy and watch what it would do.

Cedar and Rego#

A ToolPolicy may carry spec.cedar text. Cedar policies in the same policy vote alongside its native rules, strictest wins. Cedar runs only in binaries built with -tags cedar; in a binary without it, a policy with Cedar text denies every call it applies to (cedar_unavailable). An optional OPA sidecar (Rego) can be registered engine-wide; it can only make a decision stricter. Errors and timeouts fail closed (cedar_error, rego_unavailable, external_policy_error). See policy evaluation.

Decisions in the ledger#

Every governed call produces exactly one decision in the audit ledger, including denials:

The rule field is written as <policy>/<rule>. For decisions not made by a policy, it names the source: revocation/<id>, budget/<scope>-<window>, pin/<server>/<tool>, dlp (with the profile in ext).

What you see#

Test a call against a policy file offline, in CI:

$ maqpna policy test --policy prod-guard.yaml --ns team-a --agent coder \
    --server kubernetes --tool delete_pod --expect require_approval

maqpna policy test prints the request and the decision as JSON, and exits 3 when the decision differs from --expect:

{
  "decision": {
    "action": "require_approval",
    "policy": "prod-guard",
    "rule": "k8s-delete",
    "reason": "destructive"
  },
  "request": {
    "namespace": "team-a",
    "agent": "coder",
    "server": "kubernetes",
    "tool": "delete_pod"
  }
}

Add --explain to print the trace: every policy, whether it applied, and for each rule whether it matched and why not. --gateway URL evaluates against the policies a running gateway has loaded (POST /v1/policies:evaluate), with no side effects. See maqpna policy test, maqpna replay and maqpna eval.

Related#

• A governed tool call
• Policy evaluation
• Approvals, four-eyes and user approval
• Error envelope and reason codes