> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Architecture

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-common/src/redaction.rs
  * crates/palyra-common/src/workspace\_patch.rs
  * crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_patch.rs
  * crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs
  * crates/palyra-daemon/src/domain/workspace.rs
  * crates/palyra-policy/src/lib.rs
  * crates/palyra-safety/src/lib.rs
</details>

Palyra employs a layered security model designed to provide "defense in depth" for autonomous agents. Because agents can execute code, manipulate filesystems, and access the network, the architecture assumes a **fail-closed** posture. Security is enforced through a combination of logic-based policy evaluation, content inspection, cryptographic identity, and resource isolation.

### Layered Defense Overview

The security model is distributed across several specialized crates and subsystems that cooperate to validate every action an agent proposes.

| Layer             | Component             | Responsibility                                                      |
| :---------------- | :-------------------- | :------------------------------------------------------------------ |
| **Authorization** | `palyra-policy`       | Deny-by-default access control using the Cedar policy engine.       |
| **Safety**        | `palyra-safety`       | Real-time inspection for prompt injection and secret leaks.         |
| **Secrets**       | `palyra-vault`        | Secure storage and envelope encryption for sensitive credentials.   |
| **Identity**      | `palyra-identity`     | mTLS-based device pairing and service authentication.               |
| **Network**       | `palyra-egress-proxy` | Fine-grained outbound traffic control and DNS rebinding protection. |

### System Security Flow

The following diagram illustrates how a tool execution request moves through the security layers within the `palyra-daemon`.

**Diagram: Tool Execution Security Pipeline**

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        User["User Intent / Agent Goal"]
    end

    subgraph "Code Entity Space (palyra-daemon)"
        Proposal["Agent Proposal"]
        Policy["palyra-policy::PolicyEvaluation"]
        Safety["palyra-safety::inspect_text"]
        Vault["palyra-vault::SecretResolver"]
        Executor["Tool Executor"]
    end

    User --> Proposal
    Proposal -- "1. Authorize" --> Policy
    Policy -- "Permit" --> Safety
    Safety -- "2. Scan (Pre-Execution)" --> Executor
    Executor -- "3. Resolve Secrets" --> Vault
    Vault --> Executor
    Executor -- "4. Scan (Post-Execution)" --> Safety
    Safety -- "Redact/Allow" --> User
```

Sources: [crates/palyra-policy/src/lib.rs#138-144](http://crates/palyra-policy/src/lib.rs#138-144), [crates/palyra-safety/src/lib.rs#1-9](http://crates/palyra-safety/src/lib.rs#1-9), [crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs#31-33](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#31-33)

***

### [Cedar Policy Engine and Access Control](/security_architecture/cedar_policy_engine_and_access_control)

The authorization core is built on **Amazon Cedar**, a logic-based policy language. Every request (Principal, Action, Resource) is denied by default. The engine evaluates a `PolicyRequest` against an embedded baseline policy set.

* **Posture Management:** Tools can be set to `AlwaysAllow`, `AskEachTime` (requiring human approval), or `Disabled`.
* **Sensitive Actions:** Certain operations (e.g., `memory.purge`) are hardcoded as sensitive and require explicit approval flags in the `PolicyEvaluationConfig`.

For details, see [Cedar Policy Engine and Access Control](/security_architecture/cedar_policy_engine_and_access_control).
Sources: [crates/palyra-policy/src/lib.rs#17-26](http://crates/palyra-policy/src/lib.rs#17-26), [crates/palyra-policy/src/lib.rs#56-74](http://crates/palyra-policy/src/lib.rs#56-74), [crates/palyra-policy/src/lib.rs#98-103](http://crates/palyra-policy/src/lib.rs#98-103)

***

### [Safety Boundary and Content Inspection](/security_architecture/safety_boundary_and_content_inspection)

The `palyra-safety` crate provides a runtime boundary that inspects text at three phases: `PrePrompt`, `PreExecution`, and `Export`.

* **Injection Detection:** Uses `PROMPT_INJECTION_RULES` to detect attempts to override system instructions or exfiltrate data.
* **Secret Redaction:** Automatically identifies and masks credentials (e.g., API keys, Bearer tokens) using `redact_text_for_export` before they are returned to the LLM or shown in the UI.
* **Trust Labels:** Content is tagged with `TrustLabel` (e.g., `System`, `User`, `UnprivilegedTool`) to determine which safety rules apply.

For details, see [Safety Boundary and Content Inspection](/security_architecture/safety_boundary_and_content_inspection).
Sources: [crates/palyra-safety/src/lib.rs#16-34](http://crates/palyra-safety/src/lib.rs#16-34), [crates/palyra-safety/src/lib.rs#190-195](http://crates/palyra-safety/src/lib.rs#190-195), [crates/palyra-daemon/src/domain/workspace.rs#7-10](http://crates/palyra-daemon/src/domain/workspace.rs#7-10)

***

### [Vault, Secrets, and Identity](/security_architecture/vault_secrets_and_identity)

Palyra ensures that agents never handle raw credentials. The `palyra-vault` crate manages secrets using envelope encryption, often backed by OS-native stores (like Keychain or Secret Service).

* **Identity:** The `palyra-identity` crate manages a private Device CA. Communication between the CLI, Daemon, and Workers is secured via mTLS.
* **Secret Resolution:** Tools receive `vault_ref` identifiers. The `SecretResolver` only expands these into real values at the moment of execution, keeping them out of the agent's context and the `JournalStore`.

For details, see [Vault, Secrets, and Identity](/security_architecture/vault_secrets_and_identity).
Sources: [crates/palyra-common/src/redaction.rs#15-39](http://crates/palyra-common/src/redaction.rs#15-39), [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#12-15](http://crates/palyra-daemon/src/application/tool_runtime/os_file.rs#12-15)

***

### [Egress Proxy and Network Controls](/security_architecture/egress_proxy_and_network_controls)

Outbound network access is strictly controlled by the `palyra-egress-proxy`. This is critical for tools like `palyra.http.fetch` and the browser automation subsystem.

* **DNS Pinning:** Prevents DNS rebinding attacks by validating IP addresses before connection.
* **Private IP Blocking:** By default, agents are blocked from accessing local network resources (192.168.x.x, 10.x.x.x) unless explicitly allowlisted.
* **Credential Injection:** The proxy can inject credentials directly from the Vault into outgoing requests, ensuring the agent never sees the token.

For details, see [Egress Proxy and Network Controls](/security_architecture/egress_proxy_and_network_controls).
Sources: [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#40-42](http://crates/palyra-daemon/src/application/tool_runtime/os_file.rs#40-42), [crates/palyra-common/src/redaction.rs#146-154](http://crates/palyra-common/src/redaction.rs#146-154)

***

### Filesystem Security and Scoping

Filesystem tools (`palyra.fs.*`) implement strict path normalization and containment checks. The `workspace_scope` module ensures that agents are confined to specific project roots.

**Diagram: Path Resolution and Containment**

```mermaid theme={null}
graph LR
    subgraph "Model Input"
        RawPath["path: '../../etc/passwd'"]
    end

    subgraph "palyra-daemon Logic"
        Norm["workspace_file::canonicalize"]
        Check["workspace_scope::is_descendant"]
        Policy["OsFilePolicy"]
    end

    RawPath --> Norm
    Norm --> Check
    Policy --> Check
    Check -- "Reject (Traversal)" --> Error["Access Denied"]
```

Sources: [crates/palyra-daemon/src/application/tool\_runtime/workspace\_file.rs#3-9](http://crates/palyra-daemon/src/application/tool_runtime/workspace_file.rs#3-9), [crates/palyra-daemon/src/application/tool\_runtime/os\_file.rs#7-10](http://crates/palyra-daemon/src/application/tool_runtime/os_file.rs#7-10), [crates/palyra-daemon/src/application/tool\_runtime/workspace\_scope.rs#10-16](http://crates/palyra-daemon/src/application/tool_runtime/workspace_scope.rs#10-16)

## Child Pages

* [Cedar Policy Engine and Access Control](/security_architecture/cedar_policy_engine_and_access_control)
* [Safety Boundary and Content Inspection](/security_architecture/safety_boundary_and_content_inspection)
* [Vault, Secrets, and Identity](/security_architecture/vault_secrets_and_identity)
* [Egress Proxy and Network Controls](/security_architecture/egress_proxy_and_network_controls)