Policy: Caller Authorization & Capability Enforcement for Agents

[prateekdev552]

Proposing a Policy CRD that governs who may invoke an agent and what that agent is allowed to use at query-dispatch time. Part of the Agent Identity Management work (#1539); this draft covers the policy layer only, not the SPIFFE identity-minting layer it builds on.

Summary

Today any caller that can create a Query against an agent runs it with whatever models, tools, and downstream agents that agent declares. There is no way to say "only service account X may call this agent" or "this agent may use completions but not tools."

This change adds a namespaced Policy CRD and an enforcement gate in the Query controller. An agent opts in via spec.policyRef; when set, every query targeting that agent is checked against the bound policy before it is dispatched to the executor. Denials fail the query with a specific reason and emit a PolicyEnforcement event.

Policy is opt-in and fail-safe-by-allow on empty: agents without a policyRef are unaffected, and empty allow-lists mean "no restriction."

What a Policy looks like

apiVersion: ark.mckinsey.com/v1alpha1
kind: Policy
metadata:
  name: restricted
spec:
  callerAuthorization:           # WHO may invoke the agent (empty = anyone)
    allowedServiceAccounts: ["query-runner"]
    allowedSPIFFEIDs: ["spiffe://ark.local/ns/default/sa/query-runner"]
  capabilities:                  # WHAT the agent may use (empty list = unrestricted)
    allowCompletions: true       # *bool — false denies execution outright
    allowTools: true             # *bool — false denies if agent declares any non-built-in tool
    allowedModels: ["gpt-4o"]    # "*" wildcard permitted
    allowedTools: ["web-search"]

Bind it on an agent:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  policyRef:
    name: restricted
    # namespace: optional, defaults to the agent's namespace

Enforcement flow

The gate runs in QueryReconciler.executeQueryAsync, after the dispatch address is resolved but before sendQueryA2A:

1. Non-agent target (model/team/tool) → allow (policy is agent-scoped).
2. Agent without policyRef → allow (opt-in).
3. Validate agent identity — the agent must have a ready SPIFFE identity (IdentityReady=True condition + status.identity.spiffeID matching the expected spiffe://<trust-domain>/ns/<ns>/agent/<name>). This is the coupling to the SPIFFE layer.
4. Load the referenced Policy (missing → deny).
5. Caller authorization — match query.spec.serviceAccount against allowedServiceAccounts, or its derived caller SPIFFE ID (spiffe://<trust-domain>/ns/<ns>/sa/<sa>) against allowedSPIFFEIDs.
6. Capabilities — completions gate, tools gate, then allow-list checks for model, tools, and downstream agents.

Allow-lists treat empty as "no restriction" and support a * wildcard. Downstream-agent checks resolve an agent-type Tool (tool.spec.agent.name) to the real target agent name before matching allowedAgents.

Denial reasons

Reason	When
AgentNotFound	target agent can't be loaded
AgentIdentityNotReady	agent has no ready/matching SPIFFE identity
PolicyNotFound	policyRef points at a missing Policy
CallerNotAuthorized	caller SA / SPIFFE ID not in the allow-lists
CompletionsNotAllowed	allowCompletions: false
ToolsNotAllowed	allowTools: false and agent declares a non-built-in tool
ModelNotAllowed	agent's modelRef not in allowedModels
ToolNotAllowed	a declared tool not in allowedTools
AgentNotAllowed	a downstream agent not in allowedAgents

On any denial the query goes to phase=error with response policy denied: <Reason>: <Message>.

Components added / changed

Controller (Go)

• ark/api/v1alpha1/policy_types.go — Policy CRD (PolicySpec = CallerAuthorization + Capabilities), PolicyStatus.
• ark/api/v1alpha1/agent_types.go — Agent.spec.policyRef (PolicyRef) and Agent.status.identity (AgentIdentityStatus).
• ark/internal/controller/policy_enforcement.go — the enforceAgentPolicy gate and helpers.
• ark/internal/controller/policy_controller.go — minimal reconciler that stamps Ready on a Policy.
• ark/internal/controller/query_controller.go — wires the gate into dispatch; adds TrustDomain.
• ark/cmd/main.go — registers PolicyReconciler; adds --spire-trust-domain flag (default ark.local).
• CRD manifests + RBAC: config/crd/bases/...policies.yaml, chart CRD, policies/policies/status/policies/finalizers grants.
• Tests: policy_enforcement_test.go — TestEnforceAgentPolicy covers ~16 positive/negative cases (one per reason above).

API (Python / FastAPI)

• services/ark-api/.../api/v1/policies.py — GET /v1/policies, GET /v1/policies/{name}, POST /v1/policies.
• services/ark-api/.../models/policies.py — request/response models.
• agents.py / models/agents.py — policyRef plumbed through agent create/update/read.

Dashboard (Next.js)

• app/(dashboard)/policies/new/page.tsx — create-policy form.
• lib/services/policies.ts — policy service client.
• Agent form: policy selector in the model-config section.

[dcheida]

This is very well-though of, and highly important for enterprise adoption, the Policy CRD implementation proposal looks very solid, and completely valid.

Thinking it a bit further, and using Google as a strong reference, the proposal is also very aligned with the approach adopted by the Gemini Enterprise Platform. They landed on the same two elements (a SPIFFE-based per-agent identity, plus an enforcement gate on who may call what), and they've also made the choice of moving away from shared service accounts toward per-agent least-privilege principals.

Where Google has taken a step further is in the "execution-time identity" of the agent, not just the caller, and this could be extended in our proposal. In the current proposal the agent always runs with whatever identity and capabilities its bound Policy allows, regardless of whether it was invoked by an automated pipeline or directly by a human user. Gemini's model adds a new dimension on top of it: when an agent is triggered by an user (human), it can switch from acting under its own authority to acting "on behalf of that user", thus borrowing their credentials. I would suggest this very same as a further addition to the proposal

[Nab-0]

thanks Daniel, appreciate your feedback. I have taken a look at how Google does the "on behalf of the user" scenario, basically the agent prompts a login to the MCP, then they store the token. We have implemented this feature, but instead of the agent prompting the user to login (which I think is a really good way of doing it) the user needs to authenticate the MCP for it to be available in the first place.

We need to evolve this a bit more to 1. handle token refresh 2. have a login per user on the same namespace.

for the policy bit - do you think we should actually move towards a way where the policies are enforced by the cloud provider, and the agent just plugs into it? rather than being created on ARK?