@highflame/policy 2.2.45 → 2.4.0

package/dist/ai_gateway-defaults.gen.js

@@ -1321,6 +1321,126 @@ when {
     )
 };
 `;
+const AI_GATEWAY_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 gateway traffic (Firehog), which Shield evaluates in the
+// AIGateway namespace. The Guardrails copy covers Guardrails traffic.
+//
+// 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: AIGateway
+// =============================================================================
+
+@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,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 == AIGateway::Action::"call_tool",
+    resource
+)
+when {
+    (
+        (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 AI_GATEWAY_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: AIGateway
+// =============================================================================
+
+@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 == AIGateway::Action::"call_tool",
+    resource
+)
+when {
+    context has tool_is_sensitive && context.tool_is_sensitive
+};
+`;
 // =============================================================================
 // CATEGORIES
 // =============================================================================
@@ -1330,6 +1450,7 @@ export const AI_GATEWAY_CATEGORIES = [
     { id: 'agent-security', name: 'Agent Security', description: 'Detect tool poisoning, rug pull attacks, indirect prompt injection, and MCP supply chain threats.', layer: 'guardrail' },
     { id: 'data-protection', name: 'Data Protection', description: 'Prevent secrets leakage in LLM chat completions and MCP operations.', layer: 'guardrail' },
     { id: 'privacy', name: 'Privacy', description: 'Block personally identifiable information (PII) in LLM prompts and MCP tool calls.', layer: 'guardrail' },
+    { id: 'agent-identity', name: 'Agent Identity', description: 'Agent lifecycle and provenance controls for gateway traffic: unadopted agents, single-use sensitive tools.', layer: 'guardrail' },
     { id: 'organization', name: 'Organization', description: 'Organization-wide baselines and default permit policies.', layer: 'access' },
 ];
 // =============================================================================
@@ -1451,6 +1572,24 @@ export const AI_GATEWAY_TEMPLATES = [
         severity: 'critical',
         tags: ['category:privacy', 'threat:pii', 'detection:pattern', 'compliance:pci-dss', 'compliance:hipaa'],
     },
+    {
+        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: AI_GATEWAY_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: AI_GATEWAY_AGENT_IDENTITY_PERMIT_SINGLE_USE_SENSITIVE_TOOLS_CEDAR,
+        severity: 'medium',
+        tags: ['category:agent-identity', 'surface:call-tool', 'scope:per-tool', 'owasp:asi02', 'single-use'],
+    },
 ];
 // =============================================================================
 // TEMPLATES METADATA
@@ -1491,6 +1630,12 @@ export const AI_GATEWAY_TEMPLATES_JSON = `{
       "description": "Block personally identifiable information (PII) in LLM prompts and MCP tool calls.",
       "layer": "guardrail"
     },
+    {
+      "id": "agent-identity",
+      "name": "Agent Identity",
+      "description": "Agent lifecycle and provenance controls for gateway traffic: unadopted agents, single-use sensitive tools.",
+      "layer": "guardrail"
+    },
     {
       "id": "organization",
       "name": "Organization",
@@ -1655,6 +1800,37 @@ export const AI_GATEWAY_TEMPLATES_JSON = `{
         "compliance:pci-dss",
         "compliance:hipaa"
       ]
+    },
+    {
+      "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/annotations.d.ts

@@ -112,13 +112,14 @@ export interface ParseAnnotationsResult {
     customAnnotations?: CustomAnnotations;
 }
 /**
- * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Parse Cedar annotations from a Record<string, string | null> (as returned by cedar-wasm;
+ * null marks a value-less annotation).
  * Separates predefined annotations from custom annotations.
  *
  * @param rawAnnotations - Raw annotation map from Cedar JSON
  * @returns Parsed annotations object
  */
-export declare function parseAnnotations(rawAnnotations: Record<string, string> | undefined): ParseAnnotationsResult;
+export declare function parseAnnotations(rawAnnotations: Record<string, string | null> | undefined): ParseAnnotationsResult;
 /**
  * Generate a UUID v4 for rule IDs.
  * Uses crypto.randomUUID if available, falls back to manual generation.

package/dist/annotations.js

@@ -108,7 +108,8 @@ export function generateAnnotationLines(annotations, customAnnotations) {
     return lines;
 }
 /**
- * Parse Cedar annotations from a Record<string, string> (as returned by cedar-wasm).
+ * Parse Cedar annotations from a Record<string, string | null> (as returned by cedar-wasm;
+ * null marks a value-less annotation).
  * Separates predefined annotations from custom annotations.
  *
  * @param rawAnnotations - Raw annotation map from Cedar JSON
@@ -124,7 +125,10 @@ export function parseAnnotations(rawAnnotations) {
         return { annotations };
     }
     for (const [key, value] of Object.entries(rawAnnotations)) {
-        const unescapedValue = unescapeAnnotationValue(value);
+        // A value-less annotation (`@single_use`) arrives from cedar-wasm as null.
+        // Normalize to the empty string, which is what cedar-go reports and what
+        // the AARM validators read as "bare".
+        const unescapedValue = unescapeAnnotationValue(value ?? '');
         switch (key) {
             case 'id':
                 annotations.id = unescapedValue;