> ## 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.

# Egress Proxy and Network Controls

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

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

  * crates/palyra-cli/examples/run\_release\_eval\_gate.rs
  * crates/palyra-common/src/release\_evals/catalog.rs
  * crates/palyra-common/src/release\_evals/evaluator.rs
  * crates/palyra-common/src/release\_evals/mod.rs
  * crates/palyra-common/src/release\_evals/projections.rs
  * crates/palyra-common/src/release\_evals/schema.rs
  * crates/palyra-common/tests/release\_eval\_contract.rs
  * crates/palyra-daemon/src/application/tool\_runtime/http\_fetch.rs
  * crates/palyra-egress-proxy/src/lib.rs
  * crates/palyra-egress-proxy/tests/critical\_attack\_scenarios.rs
  * crates/palyra-safety/tests/critical\_attack\_scenarios.rs
  * crates/palyra-workerd/src/lib.rs
  * crates/palyra-workerd/tests/critical\_attack\_scenarios.rs
  * fixtures/golden/release\_eval\_inventory.json
</details>

The `palyra-egress-proxy` crate provides a deny-by-default outbound security layer for all network I/O initiated by the Palyra daemon. It implements a fail-closed evaluation pipeline that validates request schemes, enforces host allowlists, prevents DNS rebinding, blocks private network access, and manages secure credential injection from the vault.

## Architecture and Policy Evaluation

The core of the egress security system is the `EgressProxyPolicyService`. This service is stateless and performs evaluation of `EgressProxyRequest` objects before any network socket is opened. Every request must receive an `EgressPolicyVerdict` to proceed; any deviation from policy results in an `EgressPolicyError` which immediately halts the operation.

### Data Flow: HTTP Fetch to Network

The following diagram illustrates how the `palyra.http.fetch` tool utilizes the egress proxy to ensure secure communication.

**Egress Validation Sequence**

```mermaid theme={null}
sequenceDiagram
    participant T as palyra.http.fetch
    participant P as EgressProxyPolicyService
    participant V as Vault (SecretResolver)
    participant N as Network

    T->>P: evaluate_request(EgressProxyRequest)
    Note over P: validate(URL, Scheme, Host)
    P->>P: resolve_dns(Host)
    Note over P: validate_resolved_addrs(SocketAddr)
    P-->>T: EgressPolicyVerdict (pinned IPs)

    T->>V: resolve_secrets(CredentialBindingPlan)
    V-->>T: Plaintext Credentials

    T->>N: connect(pinned IPs)
    Note over T,N: Request with injected headers
```

Sources: [crates/palyra-daemon/src/application/tool\_runtime/http\_fetch.rs#1-15](http://crates/palyra-daemon/src/application/tool_runtime/http_fetch.rs#1-15), [crates/palyra-egress-proxy/src/lib.rs#1-6](http://crates/palyra-egress-proxy/src/lib.rs#1-6), [crates/palyra-egress-proxy/src/lib.rs#140-150](http://crates/palyra-egress-proxy/src/lib.rs#140-150)

## Key Components and Logic

### EgressProxyRequest and Verdict

The `EgressProxyRequest` structure encapsulates all parameters required for a security decision, including the target URL, allowlists, and credential requirements.

| Field                | Description                                                                          | Code Entity                                 |
| :------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------ |
| **URL Scheme**       | Only `http` and `https` are permitted.                                               | `EgressProxyRequest::url`                   |
| **Host Allowlist**   | Exact matches or DNS-suffix matches (e.g., `example.com` matches `api.example.com`). | `allowed_hosts`, `allowed_dns_suffixes`     |
| **Private Blocking** | Blocks `127.0.0.1`, `10.0.0.0/8`, etc., unless `allow_private_targets` is true.      | `EgressProxyRequest::allow_private_targets` |
| **Response Budget**  | Enforces a non-zero byte limit on the response body.                                 | `max_response_bytes`                        |

The `EgressPolicyVerdict` returns `resolved_addresses` (SocketAddr). These addresses are **pinned** in the HTTP client to prevent DNS rebinding attacks between the time of policy evaluation and the actual connection.

Sources: [crates/palyra-egress-proxy/src/lib.rs#33-48](http://crates/palyra-egress-proxy/src/lib.rs#33-48), [crates/palyra-egress-proxy/src/lib.rs#54-72](http://crates/palyra-egress-proxy/src/lib.rs#54-72), [crates/palyra-egress-proxy/src/lib.rs#103-105](http://crates/palyra-egress-proxy/src/lib.rs#103-105)

### DNS Rebinding and Private IP Protection

The function `validate_resolved_addrs` is critical for SSRF (Server-Side Request Forgery) protection. It inspects every IP returned by DNS resolution. If a single address in the set is private or local, and the request has not explicitly opted into private targets, the entire request is blocked.

Sources: [crates/palyra-egress-proxy/tests/critical\_attack\_scenarios.rs#9-10](http://crates/palyra-egress-proxy/tests/critical_attack_scenarios.rs#9-10), [crates/palyra-egress-proxy/tests/critical\_attack\_scenarios.rs#70-74](http://crates/palyra-egress-proxy/tests/critical_attack_scenarios.rs#70-74)

## Tool Integration: `palyra.http.fetch`

The `palyra.http.fetch` tool (implemented in `execute_http_fetch_tool`) is the primary consumer of the egress proxy. It implements a manual redirect loop (`Policy::none`) to ensure that every hop in a redirect chain is re-evaluated against the security policy.

### Credential Injection

The proxy supports `CredentialBindingPlan`, which allows the daemon to inject secrets into outbound requests without exposing them to the agent's context.

* **Vault-Only**: Only `SecretSource::Vault` references are permitted for egress injection.
* **Header Validation**: Header names must be "credential-shaped" (e.g., `Authorization`, `X-Api-Key`).
* **Exec Forbidden**: `SecretSource::Exec` is explicitly forbidden in egress policy to prevent arbitrary local execution during request assembly.

Sources: [crates/palyra-daemon/src/application/tool\_runtime/http\_fetch.rs#49-61](http://crates/palyra-daemon/src/application/tool_runtime/http_fetch.rs#49-61), [crates/palyra-egress-proxy/src/lib.rs#19-29](http://crates/palyra-egress-proxy/src/lib.rs#19-29), [crates/palyra-egress-proxy/src/lib.rs#112-117](http://crates/palyra-egress-proxy/src/lib.rs#112-117)

## Worker Fleet Egress Attestation

In distributed environments, the `palyra-workerd` crate enforces that workers boot with an attested egress proxy. This is part of the `WorkerAttestation` contract.

**Worker Egress Security Mapping**

```mermaid theme={null}
classDiagram
    class WorkerAttestation {
        +String worker_id
        +bool egress_proxy_attested
        +validate(WorkerAttestationExpectation)
    }
    class WorkerAttestationExpectation {
        +bool require_egress_proxy
    }
    class WorkerAttestationError {
        <<enumeration>>
        MissingEgressProxyBinding
    }

    WorkerAttestation ..> WorkerAttestationExpectation : validated against
    WorkerAttestationExpectation --|> WorkerAttestationError : throws on failure
```

The `WorkerFleetManager` rejects any worker attempting to register without a valid egress proxy binding if `require_egress_proxy` is enabled in the `WorkerFleetPolicy`.

Sources: [crates/palyra-workerd/src/lib.rs#35-42](http://crates/palyra-workerd/src/lib.rs#35-42), [crates/palyra-workerd/src/lib.rs#69-85](http://crates/palyra-workerd/src/lib.rs#69-85), [crates/palyra-workerd/src/lib.rs#127-129](http://crates/palyra-workerd/src/lib.rs#127-129)

## Security Testing and Verification

Egress controls are verified using a "Critical Attack Corpus" located in `fixtures/security/critical_attack_scenarios.json`. These tests ensure:

1. **Private Target Blocking**: Replays scenarios where DNS resolves to mixed public/private IPs.
2. **Credential Leak Prevention**: Ensures secrets are redacted in export scans via `palyra-safety`.
3. **Attestation Integrity**: Ensures workers cannot bypass egress proxy requirements.

Sources: [crates/palyra-egress-proxy/tests/critical\_attack\_scenarios.rs#1-6](http://crates/palyra-egress-proxy/tests/critical_attack_scenarios.rs#1-6), [crates/palyra-workerd/tests/critical\_attack\_scenarios.rs#1-6](http://crates/palyra-workerd/tests/critical_attack_scenarios.rs#1-6), [crates/palyra-safety/tests/critical\_attack\_scenarios.rs#78-90](http://crates/palyra-safety/tests/critical_attack_scenarios.rs#78-90)