121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# 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.
|
||
|