Overview
The policy engine acts as a security gate within thepalyrad daemon. Every sensitive operation—ranging from tool execution to filesystem modifications—is modeled as a PolicyRequest crates/palyra-policy/src/lib.rs#11-15. These requests are evaluated against a set of Cedar policies that define the “deny-by-default” baseline of the system crates/palyra-policy/src/lib.rs#192-192.
Key Concepts
- Cedar Integration: Uses the
cedar-policycrate to authorize requests against a predefinedPolicySetcrates/palyra-policy/src/lib.rs#3-6. - Sensitive Actions: Certain actions (e.g.,
memory.purge,cron.delete) are flagged as sensitive by default and require explicit allowlisting or human-in-the-loop approval crates/palyra-policy/src/lib.rs#40-40. - Capability Enforcement: Tools are assigned capabilities (e.g.,
process_exec,network), which are passed as context to the policy engine to determine if the execution is safe crates/palyra-daemon/src/tool_protocol.rs#47-52.
Implementation & Data Flow
The policy evaluation process transforms high-level application state into a Cedar-compatible authorization request.1. PolicyRequest Construction
APolicyRequest consists of three primary strings:
- Principal: The identity of the requester (e.g.,
user:admin). - Action: The operation being attempted (e.g.,
tool.execute). - Resource: The target of the action (e.g.,
tool:process_runner).
2. Contextual Evaluation
Theevaluate_with_context function crates/palyra-policy/src/lib.rs#211-215 is the main entry point. It enriches the request with a PolicyRequestContext crates/palyra-policy/src/lib.rs#18-26, which includes:
is_sensitive_action: Boolean derived fromPolicyEvaluationConfigcrates/palyra-policy/src/lib.rs#29-38.is_allowlisted_tool: Checks if the requested tool name exists in the allowed list.capabilities: A list of strings representing the technical requirements of the tool (e.g., “network”).
Policy Evaluation Logic
The following diagram illustrates the flow from a tool call to a Cedar decision: Tool Authorization Flow Sources: crates/palyra-policy/src/lib.rs#99-181, crates/palyra-daemon/src/tool_protocol.rs#19-26, crates/palyra-daemon/src/tool_protocol.rs#83-88Decision Scopes & Built-in Policies
Palyra ships with aDEFAULT_POLICY_SRC crates/palyra-policy/src/lib.rs#99-181 that defines the security posture of the daemon.
Decision Scopes
| Policy ID | Purpose | Logic |
|---|---|---|
deny_sensitive_without_approval | Blocks high-risk tools | Forbids if context.is_sensitive_action is true and allow_sensitive_tools is false. |
allow_read_only_actions | General discovery | Permits actions like tool.list, daemon.status, and protocol.version. |
allow_allowlisted_tool_execute | Core tool gate | Permits tool.execute only if is_allowlisted_tool is true and principal/channel are allowed. |
allow_vault_actions | Secret management | Permits vault.put, vault.get, etc. |
Sensitive Action Detection
The engine determines if an action is sensitive by checking:- If the action name is in
DEFAULT_SENSITIVE_ACTIONScrates/palyra-policy/src/lib.rs#40-40. - If the tool possesses any
SENSITIVE_CAPABILITY_POLICY_NAMES(e.g.,process_exec,secrets_read) crates/palyra-daemon/src/tool_protocol.rs#148-149.
Tool Execution Guardrails
When a policy permitstool.execute, the request is handed off to the sandbox_runner. The policy engine’s decision is often a prerequisite for more granular sandbox checks.
Sandbox Interaction
TheToolCallConfig crates/palyra-daemon/src/tool_protocol.rs#20-26 bridges the Cedar policy with the physical execution limits. Even if Cedar allows an action, the SandboxProcessRunnerPolicy crates/palyra-daemon/src/sandbox_runner.rs#81-93 may still enforce:
- Egress Enforcement:
EgressEnforcementMode(None, Preflight, Strict) crates/palyra-daemon/src/sandbox_runner.rs#47-51. - Resource Quotas:
cpu_time_limit_msandmemory_limit_bytescrates/palyra-daemon/src/sandbox_runner.rs#90-91.
Access Control & API Tokens
Beyond tool execution, the engine governs administrative access via theAccessRegistry crates/palyra-daemon/src/access_control.rs#13-14.
Permissions and Roles
Roles define a set of static permissions:- Owner: Full access including
PERMISSION_TRUST_OPERATEandPERMISSION_ROLLOUT_MANAGEcrates/palyra-daemon/src/access_control.rs#114-122. - Admin: Management of memberships and tokens crates/palyra-daemon/src/access_control.rs#124-129.
- Operator: Basic use of sessions, memory, and routines crates/palyra-daemon/src/access_control.rs#131-131.
API Token Validation
Tokens are validated in the HTTP transport layer (e.g.,compat_chat_completions_handler) using authorize_compat_api_token crates/palyra-daemon/src/transport/http/handlers/compat.rs#134-142. This ensures that even OpenAI-compatible requests are subject to Palyra’s internal RBAC and rate limits crates/palyra-daemon/src/access_control.rs#16-16.
Sources: crates/palyra-daemon/src/access_control.rs#76-135, crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126