# Egress Governance Architecture

Outbound traffic interception, transparent Envoy proxying, and Collet fallback modes for agent egress governance.

Source: https://mandrel-web-363efb.gitlab.io/docs/guides/egress-governance/

---


In an agentic mesh, outbound tool calls (MCP resources/tools) and downstream agent delegations are structurally equivalent from a governance perspective. Both represent an agent exercising authority outside its immediate boundary.

Mandrel governs egress traffic through a decoupled policy-and-proxy model, adapting to Kubernetes and non-Kubernetes environments alike.

---

## The Decoupled Proxy Architecture

Mandrel separates policy definition from network-level traffic interception:

* **The Mandrel Collet**: Evaluates business logic, identity (Compound Identity / SPIFFE), cost budgets (Chips), and governance matrices.
* **Envoy Proxy / Mesh Data Plane**: Handles transparent `iptables`-based L3/L4 network interception, mTLS transport encryption, and connection pooling.

```mermaid
graph LR
    subgraph Pod / Container Group
        AGENT[Specialist Agent] -->|Outbound Call| ENV[Envoy Interceptor]
        ENV -->|Policy Check| COL[Collet Sidecar]
        COL -->|Permitted| GW[Egress Gateway / External System]
    end
```

---

## Deployment Modes

### 1. Kubernetes with Gantry Operator (Gold Standard)

In Kubernetes environments managed by the Gantry Operator:
* **Interception**: Transparent `iptables` rules redirect all outbound TCP traffic to the local proxy listener.
* **Identity Resolution**: Outbound SPIFFE IDs declared in `spec.network.egress-spiffe-targets` are resolved against the active `MandrelPlatformPolicy` trust domain.
* **Enforcement**: The Collet evaluates egress targets before connection establishment, ensuring unauthorized endpoints are terminated at Layer 3/L4.

### 2. Non-Kubernetes / Edge Deployments (Degraded Fallback)

In environments where automated `iptables` manipulation or Envoy sidecars are unavailable (Docker Compose, bare metal, Cloud Run):
* **Forward Proxy Mode**: The Collet acts as a explicit HTTP/gRPC forward proxy.
* **Startup Target Assertion**: Operators specify `--target-spiffe-id` on startup. The Collet verifies this target against `spec.network.egress-spiffe-targets` before opening its listening port.
* **Configuration Safeguard**: If the target does not match the spec's declared egress list, the Collet fails to start, preventing misconfigured deployments from serving traffic.

---

## Egress Governance Matrix

| Feature | Kubernetes (Envoy + Gantry) | Serverless (Cloud Run / Fargate) | Edge / Bare Metal (Fallback) |
| :--- | :--- | :--- | :--- |
| **Interception Method** | Transparent `iptables` | Ingress/Egress Gateway Proxy | Forward Proxy / Static Port |
| **Identity Proof** | SPIFFE SVID (mTLS) | Workload Identity / Token | Operator-asserted (`--target-spiffe-id`) |
| **Target Verification** | Dynamic mTLS handshake | VPC Perimeter + Gateway | Startup configuration check |
| **Fail-Closed Enforcement** | Immediate TCP Reset | HTTP 403 Forbidden | Startup Refusal / Local Drop |

---

## Spec Configuration Example

```yaml
apiVersion: mandrelproject.ai/v1
kind: MandrelSpec
metadata:
  name: finance-specialist
spec:
  network:
    egress-spiffe-targets:
      - "/ns/finance/sa/ledger"                 # Path-only (same trust domain)
      - "spiffe://partner.example/ns/x/sa/y"   # Absolute (federated trust domain)
      - "tag:spiffe-auth"                       # Platform selector tag
```