Skip to main content
The Palyra Policy Engine, implemented in the palyra-policy crate, provides a centralized authorization layer using the Cedar Policy Language. It evaluates whether a principal (user or agent) is permitted to perform specific actions on resources, such as executing tools, managing memory, or accessing the vault.

​
Architecture & Data Flow

The engine acts as a gatekeeper within the palyrad daemon. When a tool call or sensitive action is requested, the system constructs a PolicyRequest and PolicyRequestContext, which are then evaluated against a set of Cedar policies.

​
Natural Language to Code Entity Space

The following diagram illustrates how high-level intent (e.g., “The agent wants to run a shell command”) is translated into structured Cedar entities and evaluated by the engine. Policy Evaluation Flow Sources: crates/palyra-daemon/src/tool_protocol.rs#29-44, crates/palyra-policy/src/lib.rs#11-38, crates/palyra-policy/src/lib.rs#211-215

​
Key Data Structures

​
PolicyRequest

The basic authorization triplet required for any Cedar evaluation.
  • principal: The identity requesting the action (e.g., a user ID or “agent”).
  • action: The operation being performed (e.g., tool.execute, memory.search).
  • resource: The target of the action.

​
PolicyRequestContext

Provides environmental attributes to the Cedar engine for fine-grained logic.
  • device_id: The hardware ID of the requesting node.
  • channel: The communication medium (e.g., “discord”, “console”).
  • tool_name: The specific name of the tool if action is tool.execute.
  • capabilities: A list of required permissions for the tool (e.g., process_exec, network).

​
PolicyEvaluationConfig

A configuration object used to populate the context and enforce baseline constraints before Cedar evaluation.
  • allowlisted_tools: List of tools permitted for execution.
  • sensitive_tool_names: Tools that require explicit allow_sensitive_tools flags.
  • tool_execute_principal_allowlist: Restricted list of principals allowed to run tools.
Sources: crates/palyra-policy/src/lib.rs#11-26, crates/palyra-policy/src/lib.rs#29-38

​
Implementation Detail: Cedar Policies

Palyra uses a built-in DEFAULT_POLICY_SRC that defines the baseline security posture. This source is compiled into a PolicySet and evaluated by the Cedar Authorizer. Policy Engine Entity Mapping Sources: crates/palyra-policy/src/lib.rs#99-181, crates/palyra-policy/src/lib.rs#217-250

​
Built-in Policy Logic

The engine enforces several critical security invariants:
  1. Sensitive Action Block: Actions in sensitive_actions (like memory.purge) are forbidden unless context.allow_sensitive_tools is true crates/palyra-policy/src/lib.rs#100-105.
  2. Read-Only Pass: Common status and health checks are permitted by default crates/palyra-policy/src/lib.rs#107-118.
  3. Tool Allowlisting: tool.execute is only permitted if the tool is in the allowlist AND the principal/channel are also allowlisted crates/palyra-policy/src/lib.rs#120-127.

​
Tool Execution Policy Integration

The tool_protocol.rs file integrates the policy engine with the tool execution lifecycle. Before any tool is dispatched to the sandbox_runner or wasm_plugin_runner, a decision is requested.
FeatureDescriptionCode Reference
Capability MappingTools are assigned capabilities like ProcessExec or Network.crates/palyra-daemon/src/tool_protocol.rs#47-52
Decision LogicCombines Cedar results with budget checks (max calls per run).crates/palyra-daemon/src/tool_protocol.rs#29-34
Sensitive FlagsTools with ProcessExec are automatically marked sensitive.crates/palyra-daemon/src/tool_protocol.rs#148-149

​
Policy Evaluation Results

The engine returns a PolicyDecision, which is either Allow or DenyByDefault.
  • Deny Reasons: If denied, the engine provides a specific reason string, such as TOOL_EXECUTE_CHANNEL_DENY_REASON (“channel is not allowlisted”) or SENSITIVE_DENY_REASON (“explicit user approval required”).
Sources: crates/palyra-policy/src/lib.rs#61-64, crates/palyra-policy/src/lib.rs#183-192

​
Sandbox & Egress Interaction

While the Cedar engine handles “Should this tool run?”, the SandboxProcessRunnerPolicy (defined in sandbox_runner.rs) handles “What is this tool allowed to do at runtime?”.
  • Egress Enforcement: Controlled by EgressEnforcementMode (None, Preflight, Strict).
  • Tier-C Isolation: Uses palyra-sandbox to invoke platform-specific backends like LinuxBubblewrap or MacosSandboxExec.
Sources: crates/palyra-daemon/src/sandbox_runner.rs#47-62, crates/palyra-daemon/src/sandbox_runner.rs#81-93, crates/palyra-sandbox/src/lib.rs#8-13