# Network Topology Specification

This document defines the intended network topology for ThreeGate and the reasons it is required.

ThreeGate relies on **security by topology**, not on “trust the model.”

---

## Networks

ThreeGate uses three Docker networks:

1. `llmnet` (internal)
2. `fetchnet` (internal)
3. `egressnet` (non-internal)

### 1) llmnet (internal)
**Members**
- CORE
- FETCH
- TOOL-EXEC
- LLM gateway (RoleMesh or equivalent)

**Purpose**
- Provide access to local/proxied LLM endpoints
- Provide strictly internal inter-service connectivity

**Properties**
- Docker `internal: true` (no external routing)

### 2) fetchnet (internal)
**Members**
- FETCH
- proxy

**Purpose**
- Force FETCH to use proxy as its only internet path
- Avoid direct routing from FETCH to the host’s default route

**Properties**
- Docker `internal: true`

### 3) egressnet (non-internal)
**Members**
- proxy only (recommended)

**Purpose**
- Provide the proxy container a route to the public internet

**Properties**
- Docker `internal: false`

---

## Connectivity Requirements

### CORE
- Must only attach to `llmnet`
- Must not have internet route
- Must not be able to talk directly to proxy

### FETCH
- Must attach to `llmnet` and `fetchnet`
- Must not attach to `egressnet`
- Must use proxy via `http_proxy` / `https_proxy` env vars
- Must not have direct internet route

### TOOL-EXEC
- Must attach only to `llmnet`
- Must default to no network inside execution sandbox
- Must not attach to `fetchnet` or `egressnet`

### PROXY
- Must attach to `fetchnet` and `egressnet`
- Should be the only container on `egressnet` (recommended)

---

## Defense in Depth: Host Enforcement

Docker topology is necessary but not sufficient.

A host-level firewall policy MUST also enforce:
- Deny egress from ThreeGate internal subnets by default
- Allow only proxy egress to tcp/443 and DNS

This is implemented via:
- `DOCKER-USER` chain rules (authoritative)
- Optional UFW reinforcement (defense in depth)

---

## Why This Topology Matters

### Prevents “browsing CORE”
CORE is the component most exposed to adversarial prompt content. If CORE had internet access, an injection could escalate immediately.

### Prevents “executing FETCH”
FETCH touches hostile web content. If FETCH could execute, it could be coerced into running malicious code.

### Prevents “internet-enabled execution”
TOOL-EXEC is the highest-risk capability. If it had internet by default, it becomes a general-purpose exfiltration engine.

---

## Recommended Hardening (Future)

For production:
- Use explicit IPAM subnets for each network
- Pin proxy IP to a known address
- Apply DOCKER-USER rules at boot via systemd
- Keep proxy allowlists narrow and auditable

---

## Summary

The ThreeGate network design is a security primitive, not a convenience.
Any change that increases connectivity must be treated as a security change.