Architecture & Data Flow
Authorization is enforced at thepalyra-daemon gateway layer. When an LLM proposes a tool call, the decide_tool_call logic intercepts the request to evaluate it against the active security policy.
Authorization Flow Diagram
The following diagram illustrates how a natural language tool request is translated into a Cedar-based authorization decision and potentially an interactive approval flow. Tool Authorization & Approval Lifecycle Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101, crates/palyra-daemon/src/tool_protocol.rs#29-34, crates/palyra-policy/src/lib.rs#211-215The Cedar Policy Engine (palyra-policy)
The palyra-policy crate wraps the Cedar authorizer. It maps Palyra-specific entities (Principals, Actions, Resources) into the Cedar data model.
Key Logic & Default Policies
The engine uses a hardcoded baseline policy set that defines the core security invariants:- Sensitive Action Blocking: Any action marked as sensitive (e.g.,
process_exec,filesystem_write) is forbidden unlessallow_sensitive_toolsis explicitly true in the evaluation config. crates/palyra-policy/src/lib.rs#99-105 - Read-Only Permissiveness: Actions like
tool.readordaemon.statusare permitted by default. crates/palyra-policy/src/lib.rs#107-118 - Allowlist Enforcement: Tool and skill execution requires the tool/skill ID to be present in the
allowlisted_toolsorallowlisted_skillsvectors. crates/palyra-policy/src/lib.rs#120-134
Data Structures
| Struct | Purpose |
|---|---|
PolicyRequest | Defines the principal, action, and resource (e.g., “admin”, “tool.execute”, “palyra.process_runner”). crates/palyra-policy/src/lib.rs#11-15 |
PolicyRequestContext | Provides attributes like device_id, channel, and capabilities to Cedar. crates/palyra-policy/src/lib.rs#18-26 |
PolicyEvaluationConfig | Runtime configuration containing allowlists and sensitivity flags. crates/palyra-policy/src/lib.rs#29-38 |
Tool Authorization & Sensitivity
Tools are classified based on the capabilities they require. If a tool requests a capability defined inSENSITIVE_CAPABILITY_POLICY_NAMES, it triggers a more stringent authorization path.
Sensitive Capabilities
The following capabilities are considered sensitive:process_exec: Execution of arbitrary system binaries.network: Egress traffic to external hosts.secrets_read: Accessing values from the Palyra Vault.filesystem_write: Modifying files within the workspace.
The decide_tool_call Gatekeeper
Before execution, the system performs a multi-stage check:
- Budget Check: Ensures the
remaining_tool_budgetfor the current Run is not exhausted. crates/palyra-daemon/src/application/run_stream/tool_flow.rs#163-174 - Policy Evaluation: Calls
evaluate_tool_proposal_securityto determine if the policy allows the action. crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134 - Approval Resolution: If the policy requires approval, it checks for a cached decision or prompts the operator. crates/palyra-daemon/src/application/approvals/mod.rs#67-76
Approval Flows
When a tool requires explicit authorization, aPendingToolApproval is created. This record includes a policy_snapshot of the system state at the time of the request to prevent “Time-of-check to time-of-use” (TOCTOU) vulnerabilities.
Decision Scopes
Operators can grant approvals with different scopes:- Once: Valid only for the specific
proposal_id. - Session: Valid for the duration of the current session for that specific tool/skill combination. crates/palyra-daemon/src/application/approvals/mod.rs#156-183
Implementation Detail: Approval Subject ID
Approvals are keyed by asubject_id which combines the tool name and, if applicable, the skill context:
tool:{tool_name}|skill:{skill_id}. This ensures that approving a tool for a “trusted” skill does not grant global permission for that tool. crates/palyra-daemon/src/application/approvals/mod.rs#137-146
Sources: crates/palyra-daemon/src/application/approvals/mod.rs#100-135
Code Entity Mapping
This diagram maps the conceptual “Security Gates” to the actual implementation structures and functions within the codebase. Implementation Map: Authorization Entities Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-174, crates/palyra-daemon/src/sandbox_runner.rs#147-151, crates/palyra-policy/src/lib.rs#211-215Deny-by-Default Posture
The system enforces security through multiple layers of “Deny” logic:- Cedar Baseline: The
DEFAULT_POLICY_SRCcontains no defaultpermitfor execution; it only permits metadata/status reads. crates/palyra-policy/src/lib.rs#99-118 - Empty Allowlists: New agents are initialized with empty
default_tool_allowlistanddefault_skill_allowlist. apps/web/src/console/sections/AgentsSection.tsx#75-87 - Sandbox Restrictions: Even if authorized, the
SandboxProcessRunnerPolicyenforces resource limits (CPU, memory) and path restrictions. crates/palyra-daemon/src/sandbox_runner.rs#81-93