Security Architecture Overview
The security posture ofpalyrad is governed by several interlocking subsystems that validate requests before they reach the execution runtime.
System Interplay Diagram
This diagram illustrates the flow of a tool execution request through the security subsystems. Sources: crates/palyra-daemon/src/tool_protocol.rs#37-44, crates/palyra-policy/src/lib.rs#1-10, crates/palyra-daemon/src/sandbox_runner.rs#1-80, crates/palyra-vault/src/lib.rs#1-20Tool Execution & Sandbox Tiers
Palyra provides a multi-tiered approach to tool execution, allowing operators to balance performance and security.- Tier-A (WASM): Uses
wasmtimefor high-performance, memory-safe execution with fine-grained capability grants crates/palyra-daemon/src/tool_protocol.rs#115-127. - Tier-B (rlimits): Provides basic Unix resource constraints for native processes crates/palyra-daemon/src/sandbox_runner.rs#65-78.
- Tier-C (OS-level): Leverages platform-specific sandboxing like Linux
bubblewrap(bwrap) or macOSsandbox-execto enforce filesystem and network isolation crates/palyra-sandbox/src/lib.rs#8-13.
Policy Engine (Cedar)
Thepalyra-policy crate uses the Cedar policy language to evaluate if an action (e.g., tool.execute, vault.get) should be permitted based on the principal, resource, and context crates/palyra-policy/src/lib.rs#99-181.
- PolicyRequest: Encapsulates the
principal,action, andresourcecrates/palyra-policy/src/lib.rs#11-15. - Sensitive Actions: Certain actions like
cron.deleteor tools withnetworkcapabilities are flagged as sensitive and require explicit approval crates/palyra-policy/src/lib.rs#40-58.
Vault & Secret Management
Thepalyra-vault crate manages sensitive credentials. It supports multiple backends, including the macOS Keychain, Linux Secret Service, and Windows DPAPI crates/palyra-vault/src/backend.rs#39-49.
- Envelope Encryption: Secrets are stored as encrypted blobs crates/palyra-vault/src/backend.rs#88-93.
- Scoped Access: Access is restricted via
VaultScope, ensuring agents can only retrieve secrets they are explicitly authorized to use crates/palyra-vault/src/lib.rs#16-16.
Identity, mTLS & Device Pairing
Security between the CLI, Web Console, and Daemon is anchored in mutual TLS (mTLS). Thepalyra-identity subsystem manages the Certificate Authority (CA) and device-specific certificates.
- Pairing Flow: New devices must undergo a pairing handshake involving a PIN or QR code proof crates/palyra-cli/tests/pairing_flow.rs#17-28.
- Persistence: Once paired, the device identity is persisted securely to prevent unauthorized impersonation crates/palyra-cli/tests/pairing_flow.rs#112-140.
Human-in-the-Loop Approvals
When the Policy Engine determines an action is “sensitive,” Palyra pauses execution and generates anApprovalRecord.
- Decision Scopes: Users can approve an action “Once”, for the “Session”, or for a specific time window crates/palyra-daemon/src/tool_protocol.rs#32-34.
- ToolProposed Events: The daemon emits events to the Web Console or CLI TUI, allowing the operator to inspect the proposed command and its arguments before execution crates/palyra-daemon/src/tool_protocol.rs#253-264.
Security Component Mapping
The following table maps high-level security concepts to their implementation entities in the codebase.| Security Concept | Code Entity | Path |
|---|---|---|
| Sandbox Execution | run_constrained_process | crates/palyra-daemon/src/sandbox_runner.rs#147-151 |
| Policy Evaluation | evaluate_with_context | crates/palyra-policy/src/lib.rs#211-215 |
| Secret Storage | BlobBackend | crates/palyra-vault/src/backend.rs#88-93 |
| Tool Metadata | ToolMetadata | crates/palyra-daemon/src/tool_protocol.rs#67-70 |
| Egress Control | EgressEnforcementMode | crates/palyra-daemon/src/sandbox_runner.rs#47-51 |