Skip to main content
The Policy Engine and Tool Governance subsystem provides a layered security model for authorizing actions within the Palyra daemon. It leverages the Cedar policy language for fine-grained access control, manages the lifecycle of human-in-the-loop approvals, and enforces resource and budget constraints on tool executions.

​
Cedar-Based Policy Engine

The palyra-policy crate implements the core authorization logic using the Amazon Cedar policy engine crates/palyra-policy/src/lib.rs#1-6. It evaluates a PolicyRequest against a set of predefined and user-configured policies to return a PolicyDecision crates/palyra-policy/src/lib.rs#10-15.

​
Policy Evaluation Data Flow

When a component (like the message router or tool executor) needs to authorize an action, it constructs a PolicyRequest and a PolicyRequestContext.
EntityRoleSource
PolicyRequestDefines the principal, action, and resource (e.g., tool.execute).crates/palyra-policy/src/lib.rs#11-15
PolicyRequestContextProvides attributes like device_id, run_id, and capabilities.crates/palyra-policy/src/lib.rs#17-26
PolicyEvaluationConfigContains allowlists for tools/skills and sensitivity flags.crates/palyra-policy/src/lib.rs#28-38

​
Core Security Rules

The engine uses several built-in Cedar policies to establish a “deny-by-default” baseline:
  1. deny_sensitive_without_approval: Forbids any action marked as sensitive (e.g., cron.delete, memory.purge) unless allow_sensitive_tools is explicitly set in the context crates/palyra-policy/src/lib.rs#100-105.
  2. allow_allowlisted_tool_execute: Permits tool.execute only if the tool is in the allowlist and the principal/channel are authorized crates/palyra-policy/src/lib.rs#120-127.
  3. allow_read_only_actions: Provides a broad permit for non-mutating status and list actions crates/palyra-policy/src/lib.rs#107-118.
Sources: crates/palyra-policy/src/lib.rs#10-215, crates/palyra-daemon/src/tool_protocol.rs#3-6

​
Tool Governance and Security

Tool execution is governed by the ToolCallConfig, which defines the sandbox tiers and resource limits for both WASM plugins and native process execution crates/palyra-daemon/src/tool_protocol.rs#19-26.

​
Tool Capability Model

Tools are assigned ToolCapability flags which the policy engine uses to determine sensitivity:
  • ProcessExec: Native process spawning.
  • Network: Egress to external hosts.
  • SecretsRead: Access to the palyra-vault.
  • FilesystemWrite: Modifying files in the workspace.
Sources: crates/palyra-daemon/src/tool_protocol.rs#46-64, crates/palyra-daemon/src/tool_protocol.rs#148-150

​
Policy to Code Mapping: Tool Execution

The following diagram illustrates how a tool execution request moves from a high-level ToolProposal to the low-level Cedar evaluation and sandbox execution. Tool Security Pipeline Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-174, crates/palyra-daemon/src/sandbox_runner.rs#147-151

​
Approval System and Lifecycle

The approval system provides human-in-the-loop (HITL) verification for high-risk actions. An ApprovalRecord is created when the policy engine or usage governance detects a need for manual intervention crates/palyra-daemon/src/usage_governance.rs#8-13.

​
ApprovalRiskLevel

Approvals are categorized by risk to inform UI rendering:
  • Low: Standard budget overrides.
  • Medium: Read-only access to sensitive data.
  • High: Destructive actions or unverified skill execution.

​
Decision Scopes

Users can grant approvals with different scopes crates/palyra-daemon/src/usage_governance.rs#9-10:
  • Once: Valid only for the specific run_id.
  • Session: Valid for the duration of the current session.
  • Temporary: Valid for a specific ttl_ms.
  • Always: Persistent allowlist entry.
Sources: crates/palyra-cli/src/commands/approvals.rs#136-161, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#212-228

​
Usage Governance and Budgets

The usage_governance.rs module manages cost and token consumption limits. It implements “Smart Routing” to select models based on complexity and budget crates/palyra-daemon/src/usage_governance.rs#112-130.

​
Budget Policies

Budgets are tracked via UsageBudgetPolicyRecord, which monitors metrics like total_tokens or estimated_cost_usd over intervals (e.g., daily, monthly) crates/palyra-daemon/src/usage_governance.rs#92-109.
ActionModeDescription
SuggestPassiveProvides cost estimates without blocking.
DryRunLog-onlyEvaluates policies but does not enforce limits.
EnforcedActiveBlocks execution if hard_limit_value is exceeded.
Sources: crates/palyra-daemon/src/usage_governance.rs#28-41, crates/palyra-daemon/src/transport/http/handlers/console/usage.rs#108-123

​
Skill Quarantine Mechanism

Skills (WASM plugins) undergo a mandatory audit. If a skill is not explicitly allowlisted in the configuration or has failed an integrity check, it is placed in a Quarantine state.
  1. Audit Trail: Every skill execution proposal is recorded in the journal_events log with a skill_gate_decision crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134.
  2. Enforcement: The policy engine rule allow_allowlisted_skill_execute prevents execution unless the skill’s ULID is present in the allowlisted_skills vector of the PolicyEvaluationConfig crates/palyra-policy/src/lib.rs#129-134.
Sources: crates/palyra-policy/src/lib.rs#31-35, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#163-174

​
CLI Governance Interface

The palyra CLI provides administrative commands to manage policies and approvals. Sources: crates/palyra-cli/src/args/models.rs#41-52, crates/palyra-cli/src/args/approvals.rs#3-4