Cedar-Based Policy Engine (palyra-policy)
The palyra-policy crate implements the core authorization logic using the Cedar policy language. It provides a structured way to evaluate whether a principal is allowed to perform an action on a resource within a specific context.
Key Components
PolicyRequest: Defines the fundamental authorization triple:principal,action, andresourcecrates/palyra-policy/src/lib.rs#11-15.PolicyRequestContext: Provides environmental metadata for the decision, includingdevice_id,session_id,run_id, andcapabilitiescrates/palyra-policy/src/lib.rs#18-26.PolicyEvaluationConfig: Contains the allowlists for tools, skills, and principals that the engine uses to hydrate the Cedar context crates/palyra-policy/src/lib.rs#29-38.
Default Policy Logic
The engine uses a “deny-by-default” baseline. The internal Cedar policy set defines several critical guards:- Sensitive Action Block: Forbids actions flagged as sensitive if
allow_sensitive_toolsis false crates/palyra-policy/src/lib.rs#100-105. - Tool Execution: Permits
tool.executeonly if the tool is allowlisted and the principal/channel are authorized crates/palyra-policy/src/lib.rs#120-127. - Read-Only Actions: Broadly permits non-mutating status and health checks crates/palyra-policy/src/lib.rs#107-118.
Tool Governance and Decision Flow
When an agent proposes a tool execution, the system enters a multi-stage governance flow to determine if the execution can proceed, requires approval, or must be blocked.Tool Execution Flow (Natural Language to Code Entities)
The following diagram bridges the high-level intent of executing a tool to the specific Rust functions and structs that handle the governance logic. “Tool Execution Governance Flow” Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#105-134, crates/palyra-daemon/src/application/approvals/mod.rs#100-135, crates/palyra-daemon/src/tool_protocol.rs#29-34Sensitive Action Classification
Palyra classifies certain tools and actions as “sensitive,” requiring explicit escalation.- Capability-based classification: Tools requesting
ProcessExec,Network,SecretsRead, orFilesystemWriteare treated as sensitive crates/palyra-daemon/src/tool_protocol.rs#46-52. - Action-based classification: Specific internal actions like
cron.deleteormemory.purgeare hardcoded as sensitive by default crates/palyra-policy/src/lib.rs#40-41. - Tool Metadata: Each tool defines its
capabilitiesand whether it isdefault_sensitivecrates/palyra-daemon/src/tool_protocol.rs#66-70.
Human-in-the-Loop Approval Loop
If thePolicyEngine determines that approval_required is true, the GatewayRuntimeState suspends tool execution and generates a PendingToolApproval.
- Approval Creation:
build_pending_tool_approvalcreates aPendingToolApprovalrecord with a unique ULID and apromptcontaining risk levels and options (e.g., “Allow once”, “Allow for session”) crates/palyra-daemon/src/application/approvals/mod.rs#100-135. - Persistence: The request is recorded in the
JournalStoreas anApprovalRequestedevent crates/palyra-daemon/src/application/run_stream/tool_flow.rs#239-246. - Resolution: Users resolve approvals via the Web Console or CLI. The
console_approval_decision_handlerprocesses the response and updates the state crates/palyra-daemon/src/transport/http/handlers/console/approvals.rs#57-82. - Resumption: Once approved,
apply_tool_approval_outcomeupdates theToolDecisionto allow execution crates/palyra-daemon/src/application/approvals/mod.rs#32-64.
Tool Attestation
To provide a verifiable audit trail, every tool execution generates aToolAttestation. This record cryptographically links the execution to the environment and the specific tool call.
ToolAttestation Structure
The attestation includes:
attestation_id: A unique ULID for the specific execution crates/palyra-daemon/src/tool_protocol.rs#74.execution_sha256: A hash of the tool input and the execution environment state crates/palyra-daemon/src/tool_protocol.rs#75.executor: The name of the sandbox or runtime used (e.g.,sandbox_tier_c_linux_bubblewrap) crates/palyra-daemon/src/tool_protocol.rs#78.sandbox_enforcement: The level of egress and resource enforcement applied (e.g.,strict,preflight) crates/palyra-daemon/src/tool_protocol.rs#79.