Cedar Policy Integration
Palyra uses thepalyra-policy crate to wrap the Cedar SDK. The engine evaluates PolicyRequest objects against a PolicySet to produce a PolicyDecision (Allow or Deny).
Core Data Structures
PolicyRequest: Defines the fundamental authorization triple:principal(who),action(what), andresource(on what) crates/palyra-policy/src/lib.rs#11-15.PolicyRequestContext: Provides supplemental attributes for Cedar evaluation, such asdevice_id,session_id, and toolcapabilitiescrates/palyra-policy/src/lib.rs#18-26.PolicyEvaluationConfig: Holds the allowlists and sensitivity flags used to populate the Cedar context during evaluation crates/palyra-policy/src/lib.rs#29-38.
Default Policy Logic
The system ships with a built-in Cedar policy source that enforces baseline security crates/palyra-policy/src/lib.rs#99-181:- Deny Sensitive: Forbids sensitive actions if
allow_sensitive_toolsis false crates/palyra-policy/src/lib.rs#100-105. - Allow Read-Only: Permits safe actions like
tool.listordaemon.statuscrates/palyra-policy/src/lib.rs#107-118. - Allowlisted Execution: Permits
tool.executeonly if the tool is in the allowlist and the principal/channel are authorized crates/palyra-policy/src/lib.rs#120-127.
Tool Authorization Workflow
When an agent or user requests a tool execution, thepalyra-daemon invokes the evaluate_with_context function.
Policy Evaluation Data Flow
The diagram below illustrates how internal tool metadata and request context are transformed into a Cedar authorization request. Tool Authorization Mapping Sources: crates/palyra-policy/src/lib.rs#211-215, crates/palyra-daemon/src/tool_protocol.rs#67-70Tool Sensitivity and Capabilities
Tools in Palyra are classified by theirToolMetadata. This metadata determines if a tool is “sensitive” and requires explicit operator approval.
Sensitivity Defaults
A tool is considered sensitive ifdefault_sensitive is true or if it requires any of the following ToolCapability values crates/palyra-daemon/src/tool_protocol.rs#148-149:
process_exec: Execution of arbitrary system binaries.network: Outbound network access.secrets_read: Access to the Palyra Vault.filesystem_write: Modification of the host filesystem.
Tool Attestation
Every tool execution generates aToolAttestation crates/palyra-daemon/src/tool_protocol.rs#73-80. This structure provides cryptographic and environmental proof of the execution:
execution_sha256: A hash of the tool input and binary/WASM module to ensure integrity [crates/palyra-daemon/src/tool_protocol.rs#75].executor: The name of the sandbox or runtime that handled the call (e.g.,sandbox_tier_c_linux_bubblewrap) [crates/palyra-daemon/src/tool_protocol.rs#78].sandbox_enforcement: The level of isolation applied (e.g.,strict,preflight) [crates/palyra-daemon/src/tool_protocol.rs#79].
Approval Lifecycle
If a policy evaluation results in a “Deny” due to sensitivity, or if the tool configuration requires manual intervention, the request enters the Approval Lifecycle.Lifecycle States
- Pending: The
palyradgateway holds the execution and creates an entry in theJournalStore. - Review: The operator uses the Web Console or CLI (
palyra approvals list) to inspect the request crates/palyra-cli/src/args/approvals.rs#5-24. - Decision: The operator issues a
Decidecommand crates/palyra-cli/src/args/approvals.rs#30-42.- Scope: Decisions can be
Once,Session(valid for the current session), orTimeboxed(valid for a specific TTL) crates/palyra-cli/src/args/approvals.rs#78-83.
- Scope: Decisions can be
- Resumption: If approved, the
RunStateMachinein the gateway continues the tool execution.
Execution & Approval Data Flow
The following diagram bridges the high-level approval concept to the specific CLI and Sandbox entities. Approval and Execution Flow Sources: crates/palyra-daemon/src/sandbox_runner.rs#147-151, crates/palyra-daemon/src/tool_protocol.rs#82-88, crates/palyra-cli/src/args/approvals.rs#30-42Sandbox Integration
The Policy Engine works in tandem with the Sandbox Runner. While Cedar determines if a tool can run, theSandboxProcessRunnerPolicy determines how it runs crates/palyra-daemon/src/sandbox_runner.rs#81-93.
- Tier B: Enforces resource limits (CPU/Memory) using Unix rlimits [crates/palyra-daemon/src/sandbox_runner.rs#66].
- Tier C: Enforces strict isolation using platform-specific backends like
LinuxBubblewraporMacosSandboxExec[crates/palyra-sandbox/src/lib.rs#8-13].
requested_hosts match the allowed_egress_hosts defined in the policy if EgressEnforcementMode is set to Strict crates/palyra-daemon/src/sandbox_runner.rs#186-194.
Sources: crates/palyra-daemon/src/sandbox_runner.rs#47-93, crates/palyra-sandbox/src/lib.rs#8-13