Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
docs(rfc): define synthetic DNS correlation
Signed-off-by: John Myers <[email protected]>
  • Loading branch information
johntmyers committed Jul 28, 2026
commit 650afeba5200049feddbc99a85311e6072bd4f88
83 changes: 61 additions & 22 deletions rfc/0005-sandbox-proxy-egress-adapter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,11 +142,19 @@ flowchart TD
subgraph NativeTcp["Policy DNS + native TCP"]
NameLookup["Userland DNS lookup"]
PolicyDns["Policy DNS adapter"]
DnsAnswer["DNS answer + correlated active mapping"]
NativeConnect["Userland connect(ip:port)"]
TcpAdapter["Transparent TCP adapter"]
DnsEligible{"Eligible native TCP<br/>policy endpoint?"}
DnsDeny["Local DNS refusal<br/>no upstream lookup"]
TrustedDns["Trusted upstream lookup<br/>and destination filtering"]
DnsMapping["Synthetic IP + active mapping<br/>to validated real addresses"]
DnsAnswer["Return synthetic IP"]
NativeConnect["Userland connect(synthetic_ip:port)"]
TcpAdapter["Transparent TCP adapter<br/>recover mapping"]
NameLookup --> PolicyDns
PolicyDns --> DnsAnswer
PolicyDns --> DnsEligible
DnsEligible -- No --> DnsDeny
DnsEligible -- Yes --> TrustedDns
TrustedDns --> DnsMapping
DnsMapping --> DnsAnswer
DnsAnswer --> NativeConnect
NativeConnect --> TcpAdapter
end
Expand All @@ -167,7 +175,7 @@ flowchart TD
Intent["EgressIntent"]
Auth["Authorize and select endpoint"]
Decision["EgressDecision"]
Validate["Resolve and validate destination"]
Validate["Resolve or consume pinned destination<br/>and validate"]
Relay["Relay"]
Deny["Adapter-specific deny response"]
Intent --> Auth
Expand Down Expand Up @@ -329,16 +337,29 @@ unsupported h2c upgrades on inspected routes, and either stays in a shared HTTP
request loop or forces `Connection: close` for a guarded single request.

Transparent TCP is for native clients that do not know they are using a proxy.
It depends on policy DNS and nftables capture: DNS answers create correlated
active endpoint mappings, userland later calls `connect(ip:port)`, nftables
redirects matching traffic to a userland listener, and the TCP adapter recovers
the original destination before building an intent.
It depends on policy DNS and nftables capture. For a policy-eligible native TCP
name, policy DNS returns a supervisor-owned synthetic IP and creates an active
mapping from that IP to the normalized name, matched endpoint, allowed ports,
and validated real addresses. Userland later calls
`connect(synthetic_ip:port)`, nftables redirects the traffic to a userland
listener, and the TCP adapter recovers the synthetic destination and exact
mapping before building an intent.

Policy DNS replaces static `/etc/hosts` snapshots for native TCP names. It is
query-driven: check whether the name is policy-eligible, resolve through
trusted DNS, filter returned IPs, publish the active endpoint mapping, and
answer userland. The later `connect(ip:port)` still runs through normal
authorization and must correlate with the mapping created by that DNS answer.
query-driven. It first checks whether the normalized name matches an endpoint
whose transport and protocol contract enables native TCP through policy DNS. A
name without such an endpoint receives a local policy-denial DNS response,
normally `REFUSED`, and is never sent to upstream DNS. An eligible name is
resolved through trusted DNS, and every returned address is filtered through
destination and SSRF controls before the adapter atomically publishes the
mapping and capture state and returns the synthetic IP to userland.

The later connect still runs through normal authorization. The connector may
dial only the validated real addresses pinned in the unexpired mapping; it must
not perform an unrelated fresh resolution or treat a direct connection to one
of those real IPs as correlated. Process identity remains independent
authorization evidence evaluated at connect time, not the mechanism that joins
the DNS request to the TCP connection.

Local service adapters stay outside the normal external egress relay:
`inference.local` routes chat, completion, model discovery, embeddings, and
Expand All @@ -358,16 +379,19 @@ enforcement, not native TCP capture.
flowchart TD
Packet["Userland packet"] --> ProxyDest{"Proxy destination?"}
ProxyDest -- Yes --> AcceptProxy["nftables accept"]
ProxyDest -- No --> Capture{"Active policy-DNS capture match?"}
ProxyDest -- No --> Capture{"Active synthetic-IP<br/>capture match?"}
Capture -- Yes --> Redirect["nftables redirect/TPROXY to transparent adapter"]
Capture -- No --> Reject["nftables log + reject bypass"]
Reject --> Monitor["Bypass monitor emits OCSF"]
```

Transparent TCP extends this nftables model with explicit capture rules that
run before the reject path and are scoped to unexpired, policy-correlated DNS
mappings. It does not add a parallel iptables path. The compatibility milestone
leaves the current table unchanged; capture arrives in a later feature phase.
run before the reject path and are scoped to unexpired synthetic-IP mappings.
The sandbox resolver points to policy DNS, while direct external DNS traffic
continues to the reject path. DNS-over-HTTPS is ordinary HTTPS egress and
requires its own allowed endpoint. Transparent capture does not add a parallel
iptables path. The compatibility milestone leaves the current table unchanged;
capture arrives in a later feature phase.

### Deployment Modes

Expand Down Expand Up @@ -461,9 +485,10 @@ refactor branch.
- Token grants add a runtime dependency on SPIFFE Workload API and token
endpoints. Failures should remain fail-closed and sanitized.
- Transparent TCP capture adds network-namespace interception and mutable DNS
mapping state. It must coexist with nftables reject/log enforcement, prevent
unrelated bare-IP connections from inheriting DNS authorization, and fail
closed across policy or mapping generation changes.
mapping state. Synthetic address allocation must coexist with runtime
networks, avoid premature reuse, prevent unrelated bare-IP connections from
inheriting DNS authorization, and fail closed across policy or mapping
generation changes.
- Sidecar or standalone modes may intentionally lack process identity.
Binary/path-scoped policy needs an advertised identity capability and policy
validation; missing identity cannot silently broaden an allow.
Expand Down Expand Up @@ -510,6 +535,17 @@ destination, and relay boundaries plus policy DNS and nftables capture before
it can safely preserve endpoint identity. For that reason it is a later phase
of this RFC, not the first implementation change.

### Return real addresses from policy DNS

Returning validated real addresses avoids a synthetic address pool, but the
later TCP connection carries only an IP and port. Two policy names can share
the same real address and port, and a direct bare-IP connection is
indistinguishable from one caused by the earlier lookup. Process identity does
not solve shared resolvers, caches, cross-process handoff, or two names resolved
by the same process. The proposal therefore uses a synthetic address as the
correlation handle and keeps process identity as separate authorization
evidence.

## Prior art

The current `openshell-supervisor-network` split is the immediate prior step:
Expand Down Expand Up @@ -544,7 +580,10 @@ adapter wire middleware separately.
4. What TTL cap should policy DNS use, and should policy reload immediately
invalidate all active mappings or permit a bounded drain period that cannot
authorize new connections?
5. Which original-destination mechanism and nftables redirect mode should each
5. Which non-routable synthetic IPv4 and IPv6 ranges can each runtime reserve,
and what quarantine period prevents address reuse while stale DNS answers
may remain cached?
6. Which original-destination mechanism and nftables redirect mode should each
supported runtime use while keeping capture rules ahead of bypass rejection?
6. Which identity capabilities must standalone and sidecar runtimes advertise
7. Which identity capabilities must standalone and sidecar runtimes advertise
before the gateway accepts binary/path-scoped policy for them?
38 changes: 26 additions & 12 deletions rfc/0005-sandbox-proxy-egress-adapter/implementation-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,24 +178,34 @@ series.
## Phase 8 - Policy DNS And Transparent TCP

- Add policy DNS registration for native TCP endpoint names.
- Replace static host-file mapping with query-driven DNS answers resolved
through trusted DNS and filtered through destination controls.
- Store normalized name, endpoint ID, IP/port, policy generation, distinct DNS
mapping generation, mapping ID, and expiration in active mapping state.
- Reject names that do not match an eligible native TCP endpoint before making
an upstream DNS query.
- Replace static host-file mapping with query-driven synthetic DNS answers.
Resolve eligible names through trusted DNS and filter every real address
through destination controls.
- Allocate a supervisor-owned synthetic IP and store the normalized name,
endpoint ID, allowed ports, validated real addresses, policy generation,
distinct DNS mapping generation, mapping ID, and expiration in active mapping
state.
- Require every captured connect to correlate with the unexpired mapping
created by its policy-eligible DNS answer. Do not allow unrelated bare-IP
traffic to inherit a policy-DNS decision.
selected by its synthetic destination and requested port. Do not allow
unrelated bare-IP traffic to inherit a policy-DNS decision.
- Publish mapping and nftables capture updates atomically from the adapter's
perspective.
perspective before returning the synthetic DNS answer.
- Add nftables REDIRECT/TPROXY capture rules ahead of the bypass reject path;
do not add a parallel iptables path.
- Coordinate capture-rule ownership with
`openshell-supervisor-process::netns` and preserve reject/log fallback for
unmatched traffic.
- Recover the original destination, construct a transparent-TCP intent, and run
normal generation-consistent authorization and destination validation.
- Define TTL caps, policy-reload invalidation, stale-mapping behavior, and
rollback before enabling capture by default.
- Restrict the connector to the mapping's pinned validated real addresses; do
not independently re-resolve at connect time.
- Keep direct external DNS blocked and treat DNS-over-HTTPS as ordinary
policy-controlled HTTPS egress.
- Define synthetic address pools and reuse quarantine, TTL caps, policy-reload
invalidation, stale-mapping behavior, and rollback before enabling capture by
default.

## Phase 9 - Native Protocol Processors

Expand Down Expand Up @@ -247,10 +257,14 @@ series.
- Add protocol-processor harness tests before adding Redis, Postgres, MySQL, or
similar enforcement. Each concrete processor adds multi-message, handshake,
timeout, denial, redaction, and middleware coverage.
- Integration-test policy DNS filtering, TTL, distinct mapping generations,
policy-reload invalidation, atomic capture-rule updates, original-destination
recovery, captured-connect correlation, and rejection of unrelated bare-IP
- Integration-test policy DNS filtering, denial without an upstream query,
synthetic answer allocation, TTL and reuse quarantine, distinct mapping
generations, policy-reload invalidation, atomic capture-rule updates,
original-destination recovery, allowed-port correlation, connector
restriction to pinned real addresses, and rejection of unrelated bare-IP
connects.
- Prove two names that resolve to the same real IP and port receive distinct
correlations and cannot inherit each other's endpoint policy.
- Test standalone/sidecar capability negotiation and prove missing identity or
processor support fails during policy validation rather than broadening an
allow at runtime.
Expand Down
48 changes: 33 additions & 15 deletions rfc/0005-sandbox-proxy-egress-adapter/technical-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,6 +255,7 @@ struct ResolvedEndpointCorrelation {
policy_generation: PolicyGeneration,
mapping_generation: DnsMappingGeneration,
mapping_id: DnsMappingId,
synthetic_ip: IpAddr,
}

struct PinnedRequestPolicy {
Expand Down Expand Up @@ -330,19 +331,26 @@ Policy DNS is query-driven rather than a static `/etc/hosts` snapshot.

1. Policy load registers eligible native TCP endpoint names.
2. Userland performs a DNS lookup.
3. Policy DNS checks whether the name is eligible in the current policy
generation.
4. Policy DNS resolves through trusted upstream DNS and filters answers through
endpoint metadata and SSRF controls.
5. The adapter publishes the DNS answer plus an active mapping containing the
normalized name, endpoint identifier, IP/port, policy generation, distinct
DNS mapping generation, opaque mapping ID, and expiration.
6. Capture rules are updated atomically for the active mapping.
7. Userland later calls `connect(ip:port)`.
8. Transparent TCP recovers the original destination and requires an unexpired
mapping that correlates that connect with the policy-eligible DNS answer.
9. Normal egress authorization and relay selection run against a policy
generation consistent with the mapping contract.
3. Policy DNS checks whether the normalized name matches an endpoint whose
transport and protocol contract enables native TCP through policy DNS in the
current policy generation.
4. An ineligible name receives a local policy-denial DNS response without an
upstream query.
5. Policy DNS resolves an eligible name through trusted upstream DNS and
filters every answer through endpoint metadata and SSRF controls.
6. The adapter allocates a supervisor-owned synthetic IP and creates an active
mapping containing the synthetic IP, normalized name, endpoint identifier,
allowed ports, validated real addresses, policy generation, distinct DNS
mapping generation, opaque mapping ID, and expiration.
7. The adapter publishes the mapping and capture state atomically before
returning the synthetic IP to userland with a bounded TTL.
8. Userland later calls `connect(synthetic_ip:port)`.
9. Transparent TCP recovers the synthetic original destination and requires an
unexpired exact mapping whose allowed ports contain the requested port.
10. Normal egress authorization and relay selection run against a policy
generation consistent with the mapping contract.
11. The connector dials only a real address pinned in that mapping. It does not
re-resolve the name independently at connect time.

The resolved endpoint store is active state produced by policy-eligible lookups
and consumed by transparent TCP connects. Policy generation and DNS mapping
Expand All @@ -351,7 +359,15 @@ policy reload, while a policy reload can invalidate mappings whose endpoint
contract is no longer current. A captured connection with no mapping, a stale
mapping, or a mismatched endpoint/port fails closed. An unrelated bare-IP
connection cannot inherit a policy-DNS authorization merely because it targets
an IP currently present in the mapping store.
a real IP present in the mapping store. Synthetic IPs are correlation handles,
not upstream destinations, and must never be routed directly or reassigned
while a stale answer could still refer to the prior mapping.

The mapping is sandbox-scoped rather than process-scoped. Process identity is
looked up and evaluated independently when the captured TCP connection is
authorized. It is not used to join DNS and TCP because name resolution may be
cached, delegated to a resolver helper, or consumed by a different process, and
multiple names resolved by one process may share a real address and port.

## nftables Boundary

Expand All @@ -365,8 +381,10 @@ Transparent TCP capture builds on this same nftables substrate in a later
feature phase:

- capture rules run before the generic bypass reject rules;
- capture rules are scoped to active policy-DNS IP/port mappings;
- capture rules are scoped to active synthetic-IP and allowed-port mappings;
- mapping and capture-rule updates are atomic from the adapter's perspective;
- direct external DNS remains blocked; policy DNS is the sandbox resolver, and
DNS-over-HTTPS remains ordinary policy-controlled HTTPS egress;
- reject/log rules remain the fallback for unmatched TCP/UDP egress;
- VM or Podman driver nftables rules are infrastructure NAT/isolation and are
not the proxy policy enforcement point.
Expand Down
Loading