@highflame/policy 2.2.45 → 2.4.0

package/dist/guardrails-defaults.gen.js

@@ -3894,22 +3894,77 @@ when {
 const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// =============================================================================
 // Dual Attribution
 // =============================================================================
-// Blocks privileged agent actions that cannot be attributed to a human. "Which
-// agent did this?" is half an answer; the other half is "on whose behalf?" An
-// agent is not an accountable party — the person who pointed it at the work
-// is. Shield projects both sides of that pair, so the requirement can be a
-// policy rather than a reporting convention nobody enforces.
+// Routes privileged agent actions that no human answers for to explicit
+// human approval. "Which agent did this?" is half an answer; the other half
+// is "on whose behalf?" When an agent acts for a person, that person is the
+// accountable party. When it acts for nobody (an autonomous agent, a
+// workload, an api_key-rooted token), its sensitive tool calls run only when
+// someone explicitly authorizes them, never silently and never by default.
 //
 // The agent comes from the authenticated identity, never from the request
 // body: agent_id, agent_type, agent_trust_level, agent_framework. The human
-// comes from the identity claims on the credential, as the \`principal\` record
-// — its \`act_sub\` field names the party the agent is acting for.
-//
-// Deploy in MONITOR mode first. Section 2 blocks unverified agents, and a
-// service key authenticates as unverified until the agent is registered and
-// adopted in Studio. Monitor records what each rule would have blocked on
-// every event without blocking anything; register the agent, then switch to
-// enforce.
+// comes from the identity claims on the credential, as the \`principal\`
+// record. Its \`act_sub\` field names the human the agent acts for, and is
+// absent when there is none: legacy tokens carry the delegating parent (or
+// the api key's creator), while rfc8693 tokens carry it only when the
+// delegation chain is rooted in a user. Autonomous, workload and
+// api_key-rooted rfc8693 tokens have no act_sub.
+//
+// How an agent call with no acting human is authorized: it needs an
+// explicit approval OR an explicit grant.
+//   1. Approval. Section 1 permits the call but suspends it for step-up
+//      approval (@step_up_required, AARM R4, CAP-ENF-004): Shield issues an
+//      OpenID CIBA challenge and the call runs only after an approver with
+//      the named AuthN role approves it; the timeout denies it (fail-closed).
+//   2. Grants. Allow/deny rows in Studio's agent access table compile to
+//      permits (grants) and forbids (restrictions) that Shield evaluates per
+//      agent. A restriction always denies. Section 1 carries
+//      @step_up_unless_granted, so when an allow grant explicitly matches
+//      the call under an ENFORCING access posture, Shield waives the
+//      challenge and the call runs (recorded as step_up_waived_by_grant).
+//      Under the default shadow posture a grant is only observed, so it
+//      waives nothing and approval decides. With no matching grant the call
+//      is challenged under either posture, not denied for lack of a grant.
+//   The waiver needs every step-up policy matching the call to carry
+//   @step_up_unless_granted: another step-up policy without it still
+//   challenges. Shield releases older than the grant waiver ignore the
+//   annotation: there a no-human call needs the approval even when granted,
+//   and under an enforcing posture an ungranted one is denied outright.
+//
+// A call carrying an acting human (act_sub present) is untouched by
+// Section 1, unless the agent is autonomous and not first_party.
+//
+// Customize Section 1 before deploying:
+//   - @step_up_unless_granted: remove it to require the approval even for
+//     calls an allow grant covers (grant AND approval).
+//   - role: must exist in authn.roles ("security_oncall" is a placeholder;
+//     unknown roles reject the policy at deploy time). Another step-up
+//     policy matching the same call must name the same role, or Shield
+//     denies the call (one approval cannot satisfy two roles).
+//   - timeout_seconds: this template sets 3600 (1h); when omitted the
+//     default is 86400 (24h). Bounds [60, 604800].
+//
+// Deploy this policy in ENFORCE mode. Section 1's approval gate exists only
+// in enforce mode: in monitor or alert mode Shield issues no challenge and
+// passes Section 1's Allow through unchanged. Section 1 is a permit, so in
+// a policy set without the baseline permit (organization.permit-baseline)
+// it is what lifts the implicit deny for these calls. In enforce mode that
+// lift is gated on approval (or a grant); in monitor mode the same calls
+// would be allowed with no approval at all, a widening, not an observation.
+//
+// Only Section 2 is safe to observe first. It blocks unverified agents, and
+// a service key authenticates as unverified until the agent is registered
+// and adopted in Studio. Either register and adopt the agents before
+// deploying, or move Section 2 into its own policy, deploy that one in
+// MONITOR mode to see what it would block, and switch it to enforce once
+// the agents are adopted. Mode is per policy, so never put this whole
+// template in monitor to trial Section 2.
+//
+// Change note: Section 3 (autonomous agents must be first_party) used to be
+// a hard block. It is now folded into Section 1, so a non-first-party
+// autonomous agent's sensitive call is routed to approval (or a grant)
+// instead of being denied. To restore the hard block, add the forbid kept
+// in the Section 3 comment below; it overrides approvals and grants.
 //
 // Detection layers:
 //   - agent identity (authentication layer, always available)
@@ -3917,7 +3972,8 @@ const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// ===================
 //
 // Context keys consumed:
 //   - agent_id, agent_type, agent_trust_level: String
-//   - principal: record — act_sub names the accountable human
+//   - principal: record; act_sub names the acting human, absent when the
+//     agent acts for nobody
 //   - tool_is_sensitive: Bool
 //   - tool_category: String
 //
@@ -3929,33 +3985,69 @@ const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// ===================
 // =============================================================================
 
 // ---------------------------------------------------------------------------
-// Section 1: No unattributed privileged action
-// \`unless\` because the rule must fire when attribution is ABSENT, and an
-// absent field cannot be compared — only tested for.
+// Section 1: No-human privileged action requires approval
+// ENFORCE mode only: in monitor mode this permit allows the call with no
+// approval (see the header).
+// Matches when attribution is ABSENT (an absent field cannot be compared,
+// only tested for), and also for autonomous agents that are not first_party
+// even when a human is attached: nobody watches an autonomous agent in real
+// time, and a legacy api_key token names the key's creator as act_sub
+// whether or not that person is directing the call.
+//
+// Cedar is deny-overrides and Shield issues step-up only when the decision
+// is Allow, so this permit must not coexist with a forbid on the same calls:
+// the forbid would deny every one of them and no approval would be asked.
+// To hard-block instead of gating on approval, replace this rule with:
+//
+//   @id("agent-identity.require-principal-for-sensitive-tools")
+//   @name("Block sensitive agent tools without a principal")
+//   @description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+//   @severity("critical")
+//   @tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,owasp:asi01,posture:deny-default")
+//   @reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_id && context.agent_id != "" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has principal && context.principal has act_sub
+//   };
 // ---------------------------------------------------------------------------
 
-@id("agent-identity.require-principal-for-sensitive-tools")
-@name("Block sensitive agent tools without a principal")
-@description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+@id("agent-identity.step-up-sensitive-tools-without-principal")
+@name("Permit no-human sensitive agent tools with step-up approval")
+@description("Permits call_tool on a sensitive tool by an agent with no acting human (no act_sub), or an autonomous agent that is not first_party, but suspends it until an approver with the configured AuthN role approves, unless an enforcing allow grant explicitly covers the call.")
 @severity("critical")
-@tags("category:agent-identity,detection:rule,surface:call-tool,scope:per-agent,posture:deny-default,owasp:asi01")
-@reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached. Every privileged agent action must name the person it acts for.")
-forbid (
+@tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,posture:deny-default,owasp:asi01,step-up")
+@step_up_required("role=security_oncall,timeout_seconds=3600")
+@step_up_unless_granted
+permit (
     principal,
     action == Guardrails::Action::"call_tool",
     resource
 )
 when {
     context has agent_id && context.agent_id != "" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has principal && context.principal has act_sub
+    context has tool_is_sensitive && context.tool_is_sensitive == true &&
+    (
+        !(context has principal && context.principal has act_sub) ||
+        (
+            context has agent_type && context.agent_type == "autonomous" &&
+            !(context has agent_trust_level && context.agent_trust_level == "first_party")
+        )
+    )
 };
 
 // ---------------------------------------------------------------------------
 // Section 2: Trust level gates the blast radius
 // Start in monitor: a service key is unverified until the agent is adopted.
+// Unverified agents are blocked outright, approval or not: registration and
+// adoption come before any per-call authorization.
 // ---------------------------------------------------------------------------
 
 @id("agent-identity.block-unverified-agent-sensitive-tools")
@@ -3978,28 +4070,151 @@ when {
 };
 
 // ---------------------------------------------------------------------------
-// Section 3: Autonomous agents get a higher bar
-// Nobody watches an autonomous agent in real time, so a sensitive tool call
-// from one requires first-party trust rather than merely "not unverified".
+// Section 3 (folded into Section 1): autonomous agents need first-party trust
+// This template used to forbid sensitive tool calls from autonomous agents
+// that are not first-party. A forbid would deny the very calls Section 1
+// routes to approval, so the condition now lives in Section 1 and those
+// calls require approval instead of being blocked. To hard-block them anyway
+// (overriding approvals and grants), add:
+//
+//   @id("agent-identity.restrict-autonomous-agent-sensitive-tools")
+//   @name("Block non-first-party autonomous agent tool use")
+//   @description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
+//   @severity("high")
+//   @tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
+//   @reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_type && context.agent_type == "autonomous" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has agent_trust_level && context.agent_trust_level == "first_party"
+//   };
 // ---------------------------------------------------------------------------
+`;
+const GUARDRAILS_AGENT_IDENTITY_BLOCK_UNADOPTED_AGENT_SENSITIVE_TOOLS_CEDAR = `// =============================================================================
+// Unadopted Agents: No Sensitive Tool Calls
+// =============================================================================
+// Agents that an enterprise registers in its own IdP (Entra Agent ID, Okta AI
+// agents) are discovered by Highflame before anyone adopts them. A discovered
+// or pending agent has an identity but no owner-reviewed policy, so it should
+// not reach sensitive tools until it is adopted (status "active").
+//
+// \`context.actor.status\` carries the agent lifecycle status. When no actor
+// record is present the rule falls back to the legacy \`context.principal.status\`
+// profile. Absence means "unknown", not "active": the has-guards below make a
+// request with no status fall through to the other rules instead of being
+// matched here. Any status other than "active" is matched, so suspended and
+// deactivated agents are blocked too. The comparison is case-sensitive, like
+// ZeroID's lowercase status values.
+//
+// Today this template is forward-looking. ZeroID mints tokens only for active
+// identities and stamps "active" at mint, and every caller of Shield forwards
+// that value, so no live path reports another status yet. It takes effect when
+// a non-active status reaches Shield, as ADR 0042 plans for agents registered
+// in a customer IdP. The status is a mint-time snapshot: an identity suspended
+// after its token was minted reads "active" until the token expires.
+//
+// \`tool_is_sensitive\` is set by Shield's tool_validator from a fixed list of
+// tool names (shell, execute_command, write_file, http_post, send_email,
+// delete_file, run_sql, plus Shield's configured list); other tools are not
+// sensitive and are not matched.
+//
+// This copy covers Guardrails traffic. Gateway traffic (Firehog) is evaluated
+// in the AIGateway namespace; use the AIGateway copy for it.
+//
+// Deploy in MONITOR mode first to see which discovered agents already call
+// sensitive tools, adopt them, then switch to enforce.
+//
+// Context keys consumed:
+//   - actor, principal: records - status is the agent lifecycle status
+//   - tool_is_sensitive: Bool
+//
+// Compliance:
+//   - OWASP ASI04
+//
+// Category:  agent-identity
+// Namespace: Guardrails
+// =============================================================================
 
-@id("agent-identity.restrict-autonomous-agent-sensitive-tools")
-@name("Block non-first-party autonomous agent tool use")
-@description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
+@id("agent-identity.block-unadopted-agent-sensitive-tools")
+@name("Block unadopted agents from sensitive tools")
+@description("Blocks call_tool on a sensitive tool when actor.status (or, without an actor record, principal.status) is present and is not active.")
 @severity("high")
-@tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
-@reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools. No human is in the loop to catch a mistake.")
+@tags("category:agent-identity,detection:rule,surface:call-tool,scope:per-agent,posture:deny-default,owasp:asi04")
+@reject_message("Tool execution blocked: this agent has not been adopted, so it may not call sensitive tools. Adopt the agent to activate it.")
 forbid (
     principal,
     action == Guardrails::Action::"call_tool",
     resource
 )
 when {
-    context has agent_type && context.agent_type == "autonomous" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has agent_trust_level && context.agent_trust_level == "first_party"
+    (
+        (context has actor && context.actor has status && context.actor.status != "active") ||
+        (!(context has actor) && context has principal && context.principal has status &&
+         context.principal.status != "active")
+    ) &&
+    context has tool_is_sensitive && context.tool_is_sensitive
+};
+`;
+const GUARDRAILS_AGENT_IDENTITY_PERMIT_SINGLE_USE_SENSITIVE_TOOLS_CEDAR = `// =============================================================================
+// Single-Use for Sensitive Tools
+// =============================================================================
+// Permits sensitive tool calls, but only once per grant. @single_use makes
+// Shield record the first allow in an atomic consume store and deny any replay
+// of the same grant ("grant_consumed"). Bare @single_use means per tool: one
+// allow covers any call to the same action and tool. Use
+// @single_use("request") instead to bind the allow to one exact set of
+// arguments.
+//
+// @single_use is only valid on a permit. Deny, DEFER and step-up outcomes
+// never consume. If the consume store is unavailable the request is denied
+// ("single_use_store_unavailable") unless the operator opted into fail-open.
+//
+// Requests that carry no bearer token, such as gateway and internal-service
+// traffic, have no token id to record the use against. Shield denies every
+// sensitive call_tool from them ("single_use_unbound"), whatever the
+// fail-open setting. Until the gateway forwards the caller's token to Shield
+// (ADR 0041 D16, ADR 0042 D10), that means every sensitive gateway call.
+//
+// Try it with request-level monitor mode (guard requests sent with
+// mode=monitor): single_use.would_deny on each response shows what enforcing
+// would deny. Per-policy monitor mode does NOT exercise @single_use, because
+// Shield reads it only from enforcing policies; a monitor-mode copy of this
+// template reports nothing, and switching it to enforce takes effect at once.
+//
+// Adopted alone, this permit also allows every sensitive call_tool (once per
+// grant). Pair it with the policies that decide which sensitive calls are
+// allowed at all.
+//
+// Context keys consumed:
+//   - tool_is_sensitive: Bool
+//
+// Compliance:
+//   - OWASP ASI02
+//
+// Category:  agent-identity
+// Namespace: Guardrails
+// =============================================================================
+
+@id("agent-identity.permit-single-use-sensitive-tools")
+@name("Permit sensitive tools once per grant")
+@description("Permits call_tool on a sensitive tool once per grant.")
+@severity("medium")
+@tags("category:agent-identity,surface:call-tool,scope:per-tool,owasp:asi02,single-use")
+@single_use
+permit (
+    principal,
+    action == Guardrails::Action::"call_tool",
+    resource
+)
+when {
+    context has tool_is_sensitive && context.tool_is_sensitive
 };
 `;
 // =============================================================================
@@ -4398,11 +4613,29 @@ export const GUARDRAILS_TEMPLATES = [
     {
         id: 'agent-identity.dual-attribution',
         name: 'Dual Attribution',
-        description: 'Block privileged agent actions that cannot be attributed to a human. Deploy in monitor mode first; a service key is unverified until the agent is adopted.',
+        description: 'Require human approval or an explicit allow grant for sensitive agent tool calls that no human answers for (no acting human, e.g. autonomous or workload agents); calls with an acting human pass. Customize the approver role. Deploy in enforce mode: the approval gate does not exist in monitor mode. Adopt agents first (a service key is unverified until then), or trial the unverified-agent block as its own monitor-mode policy.',
         category: 'agent-identity',
         cedarText: GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR,
         severity: 'critical',
-        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi01'],
+        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi01', 'step-up'],
+    },
+    {
+        id: 'agent-identity.block-unadopted-agent-sensitive-tools',
+        name: 'Unadopted Agents: No Sensitive Tool Calls',
+        description: 'Block sensitive tool calls from agents whose lifecycle status is not active (discovered or pending). Deploy in monitor mode first to see which discovered agents already call sensitive tools.',
+        category: 'agent-identity',
+        cedarText: GUARDRAILS_AGENT_IDENTITY_BLOCK_UNADOPTED_AGENT_SENSITIVE_TOOLS_CEDAR,
+        severity: 'high',
+        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi04'],
+    },
+    {
+        id: 'agent-identity.permit-single-use-sensitive-tools',
+        name: 'Single-Use for Sensitive Tools',
+        description: 'Permit sensitive tool calls once per grant: the first allow is recorded and a replay of the same grant is denied. Bare @single_use means per tool; use @single_use(\"request\") to bind to one set of arguments. Requests without a bearer token (gateway and internal-service traffic, until the gateway forwards the caller token) are denied (single_use_unbound). Try it with request-level mode=monitor: per-policy monitor mode does not exercise @single_use. Adopted alone, it also permits every sensitive call.',
+        category: 'agent-identity',
+        cedarText: GUARDRAILS_AGENT_IDENTITY_PERMIT_SINGLE_USE_SENSITIVE_TOOLS_CEDAR,
+        severity: 'medium',
+        tags: ['category:agent-identity', 'surface:call-tool', 'scope:per-tool', 'owasp:asi02', 'single-use'],
     },
 ];
 // =============================================================================
@@ -5048,7 +5281,7 @@ export const GUARDRAILS_TEMPLATES_JSON = `{
     {
       "id": "agent-identity.dual-attribution",
       "name": "Dual Attribution",
-      "description": "Block privileged agent actions that cannot be attributed to a human. Deploy in monitor mode first; a service key is unverified until the agent is adopted.",
+      "description": "Require human approval or an explicit allow grant for sensitive agent tool calls that no human answers for (no acting human, e.g. autonomous or workload agents); calls with an acting human pass. Customize the approver role. Deploy in enforce mode: the approval gate does not exist in monitor mode. Adopt agents first (a service key is unverified until then), or trial the unverified-agent block as its own monitor-mode policy.",
       "category": "agent-identity",
       "file": "dual_attribution.cedar",
       "severity": "critical",
@@ -5058,7 +5291,39 @@ export const GUARDRAILS_TEMPLATES_JSON = `{
         "surface:call-tool",
         "scope:per-agent",
         "posture:deny-default",
-        "owasp:asi01"
+        "owasp:asi01",
+        "step-up"
+      ]
+    },
+    {
+      "id": "agent-identity.block-unadopted-agent-sensitive-tools",
+      "name": "Unadopted Agents: No Sensitive Tool Calls",
+      "description": "Block sensitive tool calls from agents whose lifecycle status is not active (discovered or pending). Deploy in monitor mode first to see which discovered agents already call sensitive tools.",
+      "category": "agent-identity",
+      "file": "unadopted_agents.cedar",
+      "severity": "high",
+      "tags": [
+        "category:agent-identity",
+        "detection:rule",
+        "surface:call-tool",
+        "scope:per-agent",
+        "posture:deny-default",
+        "owasp:asi04"
+      ]
+    },
+    {
+      "id": "agent-identity.permit-single-use-sensitive-tools",
+      "name": "Single-Use for Sensitive Tools",
+      "description": "Permit sensitive tool calls once per grant: the first allow is recorded and a replay of the same grant is denied. Bare @single_use means per tool; use @single_use(\\"request\\") to bind to one set of arguments. Requests without a bearer token (gateway and internal-service traffic, until the gateway forwards the caller token) are denied (single_use_unbound). Try it with request-level mode=monitor: per-policy monitor mode does not exercise @single_use. Adopted alone, it also permits every sensitive call.",
+      "category": "agent-identity",
+      "file": "single_use_sensitive_tools.cedar",
+      "severity": "medium",
+      "tags": [
+        "category:agent-identity",
+        "surface:call-tool",
+        "scope:per-tool",
+        "owasp:asi02",
+        "single-use"
       ]
     }
   ]

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './category-layers.gen.js';
 export * from './decision-effects.gen.js';
 export * from './aarm-annotations.gen.js';
 export * from './aarm-annotation.js';
+export * from './step-up-role-conflict.js';
 export * from './privilege-catalog.gen.js';
 export * from './engine.js';
 export * from './builder.js';

package/dist/index.js

@@ -17,6 +17,9 @@ export * from './aarm-annotations.gen.js';
 // AARM annotation parser/validator (typed parse + fail-closed validation,
 // parity with Go's aarm_annotation.go).
 export * from './aarm-annotation.js';
+// Policy-set lint: warns when step-up policies naming different approver
+// roles can match the same call (Shield denies with step_up_internal_error).
+export * from './step-up-role-conflict.js';
 // Role -> capability privilege catalog (privilege_scope minted into
 // the trusted-service JWT; checked by role-conditioned Cedar policies).
 export * from './privilege-catalog.gen.js';