Skip to content

Agent Mesh

sandbox: flip the boundary to named HTTP tunnels via tun2connect

Antonio Ojea207b8d18719b
diff --git a/.github/k8s/sam-box-canary-template.yaml b/.github/k8s/sam-box-canary-template.yaml
index d0ed183f..7fa5ed01 100644
--- a/.github/k8s/sam-box-canary-template.yaml
+++ b/.github/k8s/sam-box-canary-template.yaml
@@ -23,7 +23,7 @@ metadata:
namespace: sam-canary-${ENV_NAME}
data:
resolv.conf: |
- nameserver 169.254.1.1
+ nameserver 100.127.255.253
---
apiVersion: v1
kind: ServiceAccount
@@ -43,8 +43,8 @@ metadata:
# nano-init makes its own with --create-namespaces and gives itself the only
# route out; the agent then speaks ordinary HTTP to ordinary names, and the
# fact that it reaches anything at all is the assertion. A curl pointed at
-# --socks5-hostname would prove the boundary works for a client that chose to
-# use it, which is the one case nobody needs proving.
+# --proxy would prove the boundary works for a client that chose to use it,
+# which is the one case nobody needs proving.
apiVersion: apps/v1
kind: Deployment
metadata:
diff --git a/.gitignore b/.gitignore
index eb65f7a5..f48c4b0e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,6 +33,7 @@ go.work.sum
# .vscode/
#
bin/
+dist/
# Stray binaries from `go build ./cmd/<name>/` in the repo root
/sam-node
/sam-box
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 1671e44e..2cb05890 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -1,5 +1,8 @@
version: 2
project_name: sam
+# Deliberately not released: sam-bench (a measurement instrument for people
+# working on the mesh, built from the repo, not something operators install)
+# and chaos-agent (a Python dev tool).
builds:
- id: sam-node
main: ./cmd/sam-node
@@ -71,6 +74,20 @@ builds:
- arm64
ldflags:
- -s -w
+ - id: sam-console
+ main: ./cmd/sam-console
+ binary: sam-console
+ env:
+ - CGO_ENABLED=0
+ goos:
+ - linux
+ - windows
+ - darwin
+ goarch:
+ - amd64
+ - arm64
+ ldflags:
+ - -s -w
- id: nano-init
main: .
# nano-init is its own module: it carries a userspace TCP stack, and that
@@ -79,9 +96,10 @@ builds:
binary: nano-init
env:
- CGO_ENABLED=0
+ # linux only: nano-init is PID 1 inside a Linux sandbox — TUN ioctls,
+ # netlink, namespaces and vsock have no meaning anywhere else.
goos:
- linux
- - darwin
goarch:
- amd64
- arm64
@@ -101,6 +119,6 @@ archives:
- goos: windows
formats:
- zip
- # nano-init has no windows build (see build id "nano-init" above), so the
- # windows archive intentionally has one fewer binary than linux/darwin.
+ # nano-init only builds for linux (see build id "nano-init" above), so the
+ # windows and darwin archives intentionally have one fewer binary.
allow_different_binary_count: true
diff --git a/AGENTS.md b/AGENTS.md
index 0a9c3fe4..14492bd9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,7 +5,7 @@ You are an expert software engineering assistant helping to develop, maintain, a
## 1. Architecture & Component Independence
* **Decoupled Architecture:** The `sam-control-plane`, `sam-router` and `sam-node` components are strictly independent. They must not share internal state or tightly couple their logic.
* **API Communication:** All data communication between `sam-control-plane`, `sam-router` and `sam-node` must happen exclusively via the common API defined in `api/sam.proto`.
-* **Sandbox Dataplane:** `sam-box` (one per sandbox) is the single egress policy enforcement point. It holds no libp2p host, no enrollment and no mesh identity, and reaches the mesh exclusively as a client of the local `sam-node` sidecar socket. `nano-init` (PID 1 inside the guest, its own Go module) owns the guest side. The sandbox boundary is a Unix socket: SOCKS5 out, `CONNECT <port>` back in. The authoritative design is `site/content/docs/agent-architecture.md`; do not contradict it.
+* **Sandbox Dataplane:** `sam-box` (one per sandbox) is the single egress policy enforcement point. It holds no libp2p host, no enrollment and no mesh identity, and reaches the mesh exclusively as a client of the local `sam-node` sidecar socket. `nano-init` (PID 1 inside the guest, its own Go module) owns the guest side; its datapath is the `tun2connect` library. The sandbox boundary is a Unix socket speaking named HTTP tunnels: CONNECT (TCP) and connect-udp (UDP) out, `CONNECT <port>` back in. The authoritative design is `site/content/docs/agent-architecture.md`; do not contradict it.
* **Enforcement over Convention:** never gate sandbox traffic on the agent's cooperation — no proxy environment variables, no `LD_PRELOAD` shims, no DNS spoofing. The agent harness stays unmodified and mesh-unaware; confinement is a route and a socket, built by the userspace launcher (`nano-init`) and judged in `sam-box`. An agent that must cooperate with its own confinement is not confined.
* **Policy on Names:** egress policy, secret injection and routing decisions are made on the destination *name*, never on an IP. Deny by default.
* **Agent Identity:** the agent is the principal; the node is only the channel. Agent identity comes from the platform's workload credential, verified at admission — never asserted in-band from inside the sandbox. Platforms integrate solely through the connector interface (`Attach`/`Detach`/`Refresh`/`Status` and the agent bundle), not by reaching into SAM internals.
diff --git a/api/sam.pb.go b/api/sam.pb.go
index d20e1760..deed7a67 100644
--- a/api/sam.pb.go
+++ b/api/sam.pb.go
@@ -2221,9 +2221,9 @@ func (x *AgentAttachRequest) GetBundle() *AgentBundle {
type AgentAttachResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
- // Sandbox boundary endpoints to wire into the sandbox: SOCKS5 for guest to
- // host, and a reverse channel for host to guest that is empty when the
- // bundle declares no ingress.
+ // Sandbox boundary endpoints to wire into the sandbox: named HTTP tunnels
+ // (CONNECT, connect-udp) for guest to host, and a reverse channel for host
+ // to guest that is empty when the bundle declares no ingress.
EgressSocket string `protobuf:"bytes,1,opt,name=egress_socket,json=egressSocket,proto3" json:"egress_socket,omitempty"`
IngressSocket string `protobuf:"bytes,2,opt,name=ingress_socket,json=ingressSocket,proto3" json:"ingress_socket,omitempty"`
Error string `protobuf:"bytes,3,opt,name=error,proto3" json:"error,omitempty"`
diff --git a/api/sam.proto b/api/sam.proto
index 396f6ba6..458cd895 100644
--- a/api/sam.proto
+++ b/api/sam.proto
@@ -303,9 +303,9 @@ message AgentAttachRequest {
}
message AgentAttachResponse {
- // Sandbox boundary endpoints to wire into the sandbox: SOCKS5 for guest to
- // host, and a reverse channel for host to guest that is empty when the
- // bundle declares no ingress.
+ // Sandbox boundary endpoints to wire into the sandbox: named HTTP tunnels
+ // (CONNECT, connect-udp) for guest to host, and a reverse channel for host
+ // to guest that is empty when the bundle declares no ingress.
string egress_socket = 1;
string ingress_socket = 2;
string error = 3;
diff --git a/cmd/nano-init/README.md b/cmd/nano-init/README.md
index a4db038f..4c63d94b 100644
--- a/cmd/nano-init/README.md
+++ b/cmd/nano-init/README.md
@@ -5,22 +5,28 @@ boundary, and then gets out of the agent's way.
## What it does
-1. **Builds the only way out.** Creates `tun0` over netlink, gives it a
- link-local address, and makes it the default route. There is no other
- interface in the sandbox, so this is not the preferred path out; it is the
- only one.
-2. **Carries a TCP stack.** Terminates the sandbox's TCP in userspace via
- gVisor (through `tun2socks`) and opens a SOCKS5 flow to the boundary for
- each connection.
-3. **Keeps the name.** Answers DNS with a placeholder address per name and
- remembers the pairing, so what reaches the boundary is `mesh.sam.alt` rather
- than an address. The boundary chooses a provider from the name, which is the
- entire reason the name has to survive the trip.
+1. **Builds the only way out.** Creates `tun0` over netlink and gives it the
+ guest ends of the synthetic address pools (`100.64.0.0/10`, `100::/64`).
+ There is no other interface in the sandbox, so this is not the preferred
+ path out; it is the only one.
+2. **Carries a TCP stack.** Terminates the sandbox's TCP/IP in userspace via
+ the [tun2connect](https://github.com/aojea/agents.net) library (gVisor's
+ netstack) and opens one named HTTP tunnel to the boundary per flow:
+ authority-form `CONNECT` for TCP, `connect-udp` for UDP.
+3. **Keeps the name.** The virtual DNS answers with a synthetic address per
+ name and remembers the pairing, so what reaches the boundary is
+ `mesh.sam.alt` rather than an address. The boundary chooses a provider from
+ the name, which is the entire reason the name has to survive the trip. A
+ flow to an address the guest never resolved has no name, and is refused.
4. **PID 1 duties.** Reaps orphans, propagates `SIGINT`/`SIGTERM`/`SIGQUIT` to
the child's process group, and exits with the agent's own status.
It is a separate Go module. A userspace TCP stack is a large dependency and has
-no business in the graph every other SAM binary builds from.
+no business in the graph every other SAM binary builds from. The datapath —
+engine, tunnel client, virtual DNS — is the tun2connect library, consumed here
+rather than forked: what this module owns is exactly the SAM- and
+platform-specific part, the vsock boundary for microVMs, `--create-namespaces`
+for pods, `copy` for image builds, and PID 1.
## What it deliberately does not do
@@ -79,4 +85,4 @@ image that has nothing else in it.
- [Running agents on SAM](https://sam-mesh.dev/docs/user/running-agents/) — the
full picture, including the microVM arrangement
- [Agent architecture](https://sam-mesh.dev/docs/agent-architecture/) — why the
- boundary speaks SOCKS5
+ boundary speaks named HTTP tunnels
diff --git a/cmd/nano-init/boundary.go b/cmd/nano-init/boundary.go
deleted file mode 100644
index 67e9d369..00000000
--- a/cmd/nano-init/boundary.go
+++ /dev/null
@@ -1,197 +0,0 @@
-// Copyright 2026 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package main
-
-import (
- "context"
- "encoding/binary"
- "errors"
- "fmt"
- "io"
- "net"
- "strconv"
- "time"
-
- M "github.com/xjasonlyu/tun2socks/v2/metadata"
-)
-
-// Everything the sandbox sends leaves through here, as a SOCKS5 CONNECT naming
-// a destination. The boundary on the far side decides whether that destination
-// is allowed; this end decides nothing, which is deliberate. A sandbox that
-// could rule on its own traffic would be ruling on behalf of the agent it
-// contains.
-
-const (
- socks5Version = 0x05
- authNone = 0x00
- cmdConnect = 0x01
- atypIPv4 = 0x01
- atypDomain = 0x03
- atypIPv6 = 0x04
- replySucceeded = 0x00
-
- boundaryDialTimeout = 30 * time.Second
-)
-
-// boundaryProxy carries sandbox flows to sam-box, restoring the name the agent
-// asked for. It satisfies tun2socks's proxy.Proxy.
-type boundaryProxy struct {
- socket string
- resolver *resolver
-}
-
-// DialContext opens one flow to the boundary.
-func (b *boundaryProxy) DialContext(ctx context.Context, meta *M.Metadata) (net.Conn, error) {
- // The address gvisor saw is a placeholder standing for a name, unless the
- // agent dialled a literal address. Either way what arrives at the boundary
- // is what the agent actually asked for.
- host := meta.DstIP.String()
- if name, ok := b.resolver.nameFor(meta.DstIP); ok {
- host = name
- }
-
- conn, err := dialBoundary(ctx, b.socket)
- if err != nil {
- return nil, fmt.Errorf("dial boundary %s: %w", b.socket, err)
- }
-
- if deadline, ok := ctx.Deadline(); ok {
- _ = conn.SetDeadline(deadline)
- }
- if err := connect(conn, host, meta.DstPort); err != nil {
- _ = conn.Close()
- return nil, err
- }
- // The handshake deadline must not become the flow's deadline: an agent
- // holding a long-lived stream would otherwise be cut off mid-conversation.
- _ = conn.SetDeadline(time.Time{})
-
- return conn, nil
-}
-
-// DialUDP refuses. The boundary does not offer UDP ASSOCIATE, by design: a
-// datagram path would be a second way out with its own rules, and one way out
-// is the property the whole arrangement rests on.
-func (b *boundaryProxy) DialUDP(*M.Metadata) (net.PacketConn, error) {
- return nil, errors.New("nano-init: the boundary carries TCP only")
-}
-
-// connect performs the SOCKS5 handshake for one destination.
-func connect(conn net.Conn, host string, port uint16) error {
- if _, err := conn.Write([]byte{socks5Version, 1, authNone}); err != nil {
- return fmt.Errorf("socks greeting: %w", err)
- }
-
- greeting := make([]byte, 2)
- if _, err := io.ReadFull(conn, greeting); err != nil {
- return fmt.Errorf("socks greeting reply: %w", err)
- }
- if greeting[0] != socks5Version || greeting[1] != authNone {
- return fmt.Errorf("socks greeting refused: %v", greeting)
- }
-
- request, err := connectRequest(host, port)
- if err != nil {
- return err
- }
- if _, err := conn.Write(request); err != nil {
- return fmt.Errorf("socks connect: %w", err)
- }
-
- return readReply(conn)
-}
-
-// connectRequest encodes a CONNECT for a name or an address.
-func connectRequest(host string, port uint16) ([]byte, error) {
- request := []byte{socks5Version, cmdConnect, 0x00}
-
- switch ip := net.ParseIP(host); {
- case ip == nil:
- // A name. This is the case that matters: the boundary resolves it.
- if len(host) > 255 {
- return nil, fmt.Errorf("destination name too long: %d bytes", len(host))
- }
- request = append(request, atypDomain, byte(len(host)))
- request = append(request, host...)
- case ip.To4() != nil:
- request = append(request, atypIPv4)
- request = append(request, ip.To4()...)
- default:
- request = append(request, atypIPv6)
- request = append(request, ip.To16()...)
- }
-
- return binary.BigEndian.AppendUint16(request, port), nil
-}
-
-// readReply consumes the SOCKS5 reply, including the bound address the
-// boundary reports but nothing here needs.
-func readReply(conn net.Conn) error {
- head := make([]byte, 4)
- if _, err := io.ReadFull(conn, head); err != nil {
- return fmt.Errorf("socks reply: %w", err)
- }
- if head[0] != socks5Version {
- return fmt.Errorf("socks reply version %d", head[0])
- }
- if head[1] != replySucceeded {
- return fmt.Errorf("boundary refused: %s", replyMessage(head[1]))
- }
-
- var skip int
- switch head[3] {
- case atypIPv4:
- skip = net.IPv4len
- case atypIPv6:
- skip = net.IPv6len
- case atypDomain:
- length := make([]byte, 1)
- if _, err := io.ReadFull(conn, length); err != nil {
- return fmt.Errorf("socks reply address: %w", err)
- }
- skip = int(length[0])
- default:
- return fmt.Errorf("socks reply address type %d", head[3])
- }
-
- if _, err := io.ReadFull(conn, make([]byte, skip+2)); err != nil {
- return fmt.Errorf("socks reply address: %w", err)
- }
- return nil
-}
-
-// replyMessage turns a SOCKS5 failure into something an agent's logs can be
-// read against. "Not allowed" is a policy decision and has to be legible as
-// one, rather than looking like the mesh being broken.
-func replyMessage(code byte) string {
- switch code {
- case 0x02:
- return "not allowed by policy"
- case 0x03:
- return "network unreachable"
- case 0x04:
- return "host unreachable"
- case 0x05:
- return "connection refused"
- case 0x06:
- return "TTL expired"
- case 0x07:
- return "command not supported"
- case 0x08:
- return "address type not supported"
- default:
- return "general failure (" + strconv.Itoa(int(code)) + ")"
- }
-}
diff --git a/cmd/nano-init/go.mod b/cmd/nano-init/go.mod
index 97b42e52..89e6a196 100644
--- a/cmd/nano-init/go.mod
+++ b/cmd/nano-init/go.mod
@@ -1,37 +1,22 @@
module github.com/google/sam/cmd/nano-init
-go 1.26.3
+go 1.26.5
require (
+ github.com/aojea/agents.net/tun2connect v0.0.1
github.com/mdlayher/vsock v1.3.0
github.com/vishvananda/netlink v1.3.1
- github.com/xjasonlyu/tun2socks/v2 v2.7.0
- golang.org/x/net v0.58.0
golang.org/x/sys v0.47.0
)
require (
- github.com/ajg/form v1.7.1 // indirect
- github.com/docker/go-units v0.5.0 // indirect
- github.com/go-chi/chi/v5 v5.3.0 // indirect
- github.com/go-chi/cors v1.2.2 // indirect
- github.com/go-chi/render v1.0.3 // indirect
- github.com/go-gost/relay v0.6.1 // indirect
github.com/google/btree v1.1.3 // indirect
- github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
- github.com/google/uuid v1.6.0 // indirect
- github.com/gorilla/schema v1.4.1 // indirect
- github.com/gorilla/websocket v1.5.3 // indirect
github.com/mdlayher/socket v0.6.0 // indirect
github.com/vishvananda/netns v0.0.5 // indirect
- go.uber.org/atomic v1.11.0 // indirect
- go.uber.org/multierr v1.11.0 // indirect
- go.uber.org/zap v1.28.0 // indirect
- golang.org/x/crypto v0.55.0 // indirect
golang.org/x/exp v0.0.0-20260611194520-c48552f49976 // indirect
- golang.org/x/sync v0.21.0 // indirect
+ golang.org/x/net v0.58.0 // indirect
+ golang.org/x/sync v0.22.0 // indirect
+ golang.org/x/text v0.41.0 // indirect
golang.org/x/time v0.15.0 // indirect
- golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
- golang.zx2c4.com/wireguard v0.0.0-20260522210424-ecfc5a8d5446 // indirect
- gvisor.dev/gvisor v0.0.0-20260701204157-69c2d17aea96 // indirect
+ gvisor.dev/gvisor v0.0.0-20260827233944-c21d56e7d544 // indirect
)
diff --git a/cmd/nano-init/go.sum b/cmd/nano-init/go.sum
index 4014fa43..9835b6dd 100644
--- a/cmd/nano-init/go.sum
+++ b/cmd/nano-init/go.sum
@@ -1,75 +1,30 @@
-github.com/ajg/form v1.5.1/go.mod h1:uL1WgH+h2mgNtvBq0339dVnzXdBETtL2LeUXaIv25UY=
-github.com/ajg/form v1.7.1 h1:OsnBDzTkrWdrxvEnO68I72ZVGJGNaMwPhoAm0V+llgc=
-github.com/ajg/form v1.7.1/go.mod h1:HL757PzLyNkj5AIfptT6L+iGNeXTlnrr/oDePGc/y7Q=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
-github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
-github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
-github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
-github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
-github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
-github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
-github.com/go-chi/render v1.0.3 h1:AsXqd2a1/INaIfUSKq3G5uA8weYx20FOsM7uSoCyyt4=
-github.com/go-chi/render v1.0.3/go.mod h1:/gr3hVkmYR0YlEy3LxCuVRFzEu9Ruok+gFqbIofjao0=
-github.com/go-gost/relay v0.6.1 h1:7SqnHFbY8x/DzvjpK03a5zcVH9+TbJAcnW/RT6s1ecc=
-github.com/go-gost/relay v0.6.1/go.mod h1:Dku0f5sfjOClrZFiDmQUrYYJ4uof7rnkCUBfsl0PSAI=
+github.com/aojea/agents.net/tun2connect v0.0.1 h1:Q/uj1UrZhJIyaSrxmxYMFBz/b8mmACHlTT60PpPIh2I=
+github.com/aojea/agents.net/tun2connect v0.0.1/go.mod h1:zTkUfO7BHJTjeGYdCiGXKQ2N+fy9IZkUwDW36fi+hJY=
github.com/google/btree v1.1.3 h1:CVpQJjYgC4VbzxeGVHfvZrv1ctoYCAI8vbl07Fcxlyg=
github.com/google/btree v1.1.3/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
-github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
-github.com/gorilla/schema v1.4.1 h1:jUg5hUjCSDZpNGLuXQOgIWGdlgrIdYvgQ0wZtdK1M3E=
-github.com/gorilla/schema v1.4.1/go.mod h1:Dg5SSm5PV60mhF2NFaTV1xuYYj8tV8NOPRo4FggUMnM=
-github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
-github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
github.com/mdlayher/socket v0.6.0 h1:ScZPaAGyO1icQnbFrhPM8mnXyMu9qukC1K4ZoM2IQKU=
github.com/mdlayher/socket v0.6.0/go.mod h1:q7vozUAnxSqnjHc12Fik5yUKIzfZ8ITCfMkhOtE9z18=
github.com/mdlayher/vsock v1.3.0 h1:bqQfZ1OznI03y6YiXp2sze05RVdzLn/zsfjnjd4+ivI=
github.com/mdlayher/vsock v1.3.0/go.mod h1:WsuksavOvwCnV5UqGHUkvAvCy+Dqy81y4goKQTzxxNY=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
-github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/vishvananda/netlink v1.3.1 h1:3AEMt62VKqz90r0tmNhog0r/PpWKmrEShJU0wJW6bV0=
github.com/vishvananda/netlink v1.3.1/go.mod h1:ARtKouGSTGchR8aMwmkzC0qiNPrrWO5JS/XMVl45+b4=
github.com/vishvananda/netns v0.0.5 h1:DfiHV+j8bA32MFM7bfEunvT8IAqQ/NzSJHtcmW5zdEY=
github.com/vishvananda/netns v0.0.5/go.mod h1:SpkAiCQRtJ6TvvxPnOSyH3BMl6unz3xZlaprSwhNNJM=
-github.com/xjasonlyu/tun2socks/v2 v2.7.0 h1:fYEN0Q1sSanuoID8xvUTsMODbKLJJH/J5ywYoMRxIPw=
-github.com/xjasonlyu/tun2socks/v2 v2.7.0/go.mod h1:XHgJ3wbs63mZxGbJawt6jjNX65aPDl+Qhn2ePPEE4KI=
-go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
-go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
-go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
-go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
-go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
-go.uber.org/zap v1.28.0 h1:IZzaP1Fv73/T/pBMLk4VutPl36uNC+OSUh3JLG3FIjo=
-go.uber.org/zap v1.28.0/go.mod h1:rDLpOi171uODNm/mxFcuYWxDsqWSAVkFdX4XojSKg/Q=
-go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
-go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
-golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
golang.org/x/exp v0.0.0-20260611194520-c48552f49976 h1:X8Hz2ImujgbmetVuW+w2YkyZChE3cBpZi2P158rTG9M=
golang.org/x/exp v0.0.0-20260611194520-c48552f49976/go.mod h1:vnf4pv9iKZXY58sQE1L86zmNWJ4159e1RkcWiLCkeEY=
golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
-golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
-golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.2.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.10.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
-golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 h1:B82qJJgjvYKsXS9jeunTOisW56dUokqW/FOteYJJ/yg=
-golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2/go.mod h1:deeaetjYA+DHMHg+sMSMI58GrEteJUUzzw7en6TJQcI=
-golang.zx2c4.com/wireguard v0.0.0-20260522210424-ecfc5a8d5446 h1:cqHQ3AycTHvM2R7ikgyX57D+XvtcSnGylsLkOVhta/w=
-golang.zx2c4.com/wireguard v0.0.0-20260522210424-ecfc5a8d5446/go.mod h1:rpwXGsirqLqN2L0JDJQlwOboGHmptD5ZD6T2VmcqhTw=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
-gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-gvisor.dev/gvisor v0.0.0-20260701204157-69c2d17aea96 h1:LZXOf4NwvAwUy/eI8P+Y3DUdYLyaCEDNPEjsL2OP2ro=
-gvisor.dev/gvisor v0.0.0-20260701204157-69c2d17aea96/go.mod h1:8aLQqUBHDH8fY5y60lzmwDpMMbQCcT3EBfoSwhfaGCY=
+gvisor.dev/gvisor v0.0.0-20260827233944-c21d56e7d544 h1:AfKDPn5UNs9npLCLMfQzaKOAM++WQw0e9v0p0aT5OUc=
+gvisor.dev/gvisor v0.0.0-20260827233944-c21d56e7d544/go.mod h1:8aLQqUBHDH8fY5y60lzmwDpMMbQCcT3EBfoSwhfaGCY=
diff --git a/cmd/nano-init/main.go b/cmd/nano-init/main.go
index 6aa682a2..4ab7ac91 100644
--- a/cmd/nano-init/main.go
+++ b/cmd/nano-init/main.go
@@ -33,10 +33,13 @@
// convenience for clients that look a name up before connecting, not a control:
// an agent that resolves some other way is routed through the tun regardless.
//
-// The TCP stack is gVisor's, via tun2socks. Writing one would mean writing
-// retransmission, windowing and teardown, and getting those subtly wrong shows
-// up as tail latency under load, which is exactly where this has to be
-// trusted.
+// The datapath is the tun2connect library: gVisor's TCP stack terminating the
+// sandbox's flows in userspace, each one leaving for the boundary as a named
+// HTTP CONNECT (RFC 9110) or connect-udp (RFC 9298) tunnel, with a virtual DNS
+// preserving the name the agent asked for. Writing a TCP stack here would mean
+// writing retransmission, windowing and teardown, and getting those subtly
+// wrong shows up as tail latency under load, which is exactly where this has
+// to be trusted.
package main
import (
@@ -53,28 +56,34 @@ import (
"time"
"github.com/vishvananda/netlink"
- "github.com/xjasonlyu/tun2socks/v2/engine"
- "github.com/xjasonlyu/tun2socks/v2/tunnel"
+ "golang.org/x/sys/unix"
+
+ "github.com/aojea/agents.net/tun2connect/pkg/tun2connect"
)
const (
tunName = "tun0"
-
- // Addresses inside the sandbox are link-local because that is what these
- // addresses are for: RFC 3927 describes a single link with no router, and
- // a tun to the boundary is exactly that. A sandbox numbered out of
- // 10.0.0.0/8 will eventually be deployed somewhere that already uses it.
- tunIP = "169.254.1.1"
- tunAddr = tunIP + "/30"
-
- // The resolver answers on the tun's own address, which is the one address
- // this sandbox is certain to have. Nothing outside can reach it: a
- // link-local address is not routed anywhere.
- dnsAddr = tunIP + ":53"
-
- // Disjoint from tunAddr: an overlap would hand out the interface's own
- // address as a name's answer, which fails in a way nobody enjoys reading.
- virtualPool = "169.254.64.0/18"
+ tunMTU = 1500
+
+ // The guest addresses sit at the TOP of tun2connect's synthetic pools:
+ // the virtual DNS invents answers from the bottom up, so they can never
+ // collide with one. The /10 and /64 prefix lengths make the kernel
+ // install connected routes covering every synthetic address, so no
+ // explicit route entries are needed.
+ //
+ // v4 is CGNAT space (RFC 6598) rather than the link-local range this used
+ // to number from: link-local would be leak-proof at the first router, but
+ // SSRF guards in HTTP clients commonly block 169.254/16, which broke
+ // legitimate egress. v6 is the RFC 6666 discard-only prefix, so a packet
+ // that ever escapes through a stray interface is blackholed rather than
+ // delivered.
+ tunAddr4 = "100.127.255.254/10"
+ tunAddr6 = "100::ffff:ffff:ffff:fffe/64"
+
+ // The resolver's address is any pool address routed through the tun: the
+ // engine answers UDP port 53 locally wherever the query is sent, so it
+ // needs no route or listener of its own.
+ resolverIP = "100.127.255.253"
)
func main() {
@@ -193,11 +202,7 @@ func run(createNS bool, ingressSocket, boundarySocket, cmdName string, cmdArgs [
log.Fatalf("this sandbox has no way out: %v", err)
}
- names, err := newResolver(virtualPool)
- if err != nil {
- log.Fatalf("resolver: %v", err)
- }
- if err := setupNetwork(ctx, boundarySocket, names); err != nil {
+ if err := setupNetwork(ctx, boundarySocket); err != nil {
log.Fatalf("set up sandbox network: %v", err)
}
@@ -225,77 +230,114 @@ func run(createNS bool, ingressSocket, boundarySocket, cmdName string, cmdArgs [
// stack rather than running a separate binary, so a sandbox image can be the
// agent and nothing else. That is not tidiness: image size is what decides how
// many agents fit on a host.
-func setupNetwork(ctx context.Context, boundarySocket string, names *resolver) error {
+func setupNetwork(ctx context.Context, boundarySocket string) error {
// As PID 1 in a microVM nothing else has done this, and a sandbox without
// loopback breaks things that have no business caring about the network.
if lo, err := netlink.LinkByName("lo"); err == nil {
_ = netlink.LinkSetUp(lo)
}
- tun := &netlink.Tuntap{
- LinkAttrs: netlink.LinkAttrs{Name: tunName},
- Mode: netlink.TUNTAP_MODE_TUN,
- }
- if err := netlink.LinkAdd(tun); err != nil {
+ fd, err := openTUN(tunName)
+ if err != nil {
return fmt.Errorf("create %s: %w\n%s", tunName, err, describeTunFailure(err))
}
- if err := netlink.LinkSetUp(tun); err != nil {
- return fmt.Errorf("bring up %s: %w", tunName, err)
- }
- addr, err := netlink.ParseAddr(tunAddr)
+ link, err := netlink.LinkByName(tunName)
if err != nil {
- return fmt.Errorf("parse %s: %w", tunAddr, err)
+ return fmt.Errorf("find %s after creating it: %w", tunName, err)
+ }
+ for _, cidr := range []string{tunAddr4, tunAddr6} {
+ addr, err := netlink.ParseAddr(cidr)
+ if err != nil {
+ return fmt.Errorf("parse %s: %w", cidr, err)
+ }
+ if err := netlink.AddrAdd(link, addr); err != nil {
+ return fmt.Errorf("address %s with %s: %w", tunName, cidr, err)
+ }
}
- if err := netlink.AddrAdd(tun, addr); err != nil {
- return fmt.Errorf("address %s: %w", tunName, err)
+ if err := netlink.LinkSetUp(link); err != nil {
+ return fmt.Errorf("bring up %s: %w", tunName, err)
}
- // A device route with no gateway: nothing on the far side of this link has
+ // Default routes with no gateway: nothing on the far side of this link has
// an address worth naming, and everything goes the same way regardless.
- // The destination has to be spelled out rather than left nil, which
- // netlink reads as "no route specified at all".
- if err := netlink.RouteAdd(&netlink.Route{
- LinkIndex: tun.Attrs().Index,
- Scope: netlink.SCOPE_LINK,
- Dst: &net.IPNet{IP: net.IPv4zero, Mask: net.CIDRMask(0, 32)},
- }); err != nil {
- return fmt.Errorf("default route via %s: %w", tunName, err)
- }
-
- dns, err := net.ListenPacket("udp", dnsAddr)
- if err != nil {
- return fmt.Errorf("resolver on %s: %w", dnsAddr, err)
+ // The connected /10 and /64 routes already cover every synthetic address,
+ // but the default is what keeps the promise that routing does not ask: an
+ // agent that hardcodes its own resolver still has the query answered by
+ // the engine, and a stray dial to a literal address terminates at the
+ // boundary as a visible refusal rather than a kernel errno. The
+ // destination has to be spelled out rather than left nil, which netlink
+ // reads as "no route specified at all".
+ for _, dst := range []*net.IPNet{
+ {IP: net.IPv4zero, Mask: net.CIDRMask(0, 32)},
+ {IP: net.IPv6zero, Mask: net.CIDRMask(0, 128)},
+ } {
+ if err := netlink.RouteAdd(&netlink.Route{
+ LinkIndex: link.Attrs().Index,
+ Scope: netlink.SCOPE_LINK,
+ Dst: dst,
+ }); err != nil {
+ return fmt.Errorf("default route for %s via %s: %w", dst, tunName, err)
+ }
}
- go names.serveDNS(dns)
- go func() {
- <-ctx.Done()
- _ = dns.Close()
- }()
// A pod can mount the file over instead, in which case it is read-only and
// already says this.
if !resolvConfAlreadyOurs() {
- if err := os.WriteFile("/etc/resolv.conf", []byte("nameserver "+tunIP+"\n"), 0o644); err != nil {
+ if err := os.WriteFile("/etc/resolv.conf", []byte("nameserver "+resolverIP+"\n"), 0o644); err != nil {
// Not fatal: resolution is a convenience here, not the control.
log.Printf("could not write /etc/resolv.conf, name resolution may fail: %v", err)
}
}
- // direct:// is a placeholder the engine insists on. The real dialer is
- // installed below, before the agent exists to send anything, so nothing
- // can take the placeholder path.
- engine.Insert(&engine.Key{
- Device: "tun://" + tunName,
- Proxy: "direct://",
- LogLevel: "warn",
+ dev, err := tun2connect.NewTUNDevice(fd, tunMTU)
+ if err != nil {
+ return fmt.Errorf("link endpoint on %s: %w", tunName, err)
+ }
+ engine, err := tun2connect.New(tun2connect.Config{
+ Device: dev,
+ Dialer: &tun2connect.BoundaryClient{
+ DialBoundary: func(ctx context.Context) (net.Conn, error) {
+ return dialBoundary(ctx, boundarySocket)
+ },
+ },
+ DNS: tun2connect.NewVirtualDNS(),
+ EnableUDP: true,
})
- engine.Start()
-
- tunnel.T().SetProxy(&boundaryProxy{socket: boundarySocket, resolver: names})
+ if err != nil {
+ return fmt.Errorf("start the userspace TCP stack: %w", err)
+ }
+ go func() {
+ <-ctx.Done()
+ engine.Close()
+ }()
return nil
}
+// openTUN opens the clone device and names the interface. The fd is what the
+// engine reads and writes; the interface is what the kernel routes into.
+func openTUN(name string) (int, error) {
+ fd, err := unix.Open(tunDevice, unix.O_RDWR, 0)
+ if err != nil {
+ return -1, fmt.Errorf("open %s: %w", tunDevice, err)
+ }
+ ifr, err := unix.NewIfreq(name)
+ if err != nil {
+ _ = unix.Close(fd)
+ return -1, err
+ }
+ ifr.SetUint16(unix.IFF_TUN | unix.IFF_NO_PI)
+ if err := unix.IoctlIfreq(fd, unix.TUNSETIFF, ifr); err != nil {
+ _ = unix.Close(fd)
+ return -1, fmt.Errorf("TUNSETIFF %s: %w", name, err)
+ }
+ if err := unix.SetNonblock(fd, true); err != nil {
+ _ = unix.Close(fd)
+ return -1, err
+ }
+ return fd, nil
+}
+
// runAgent starts the agent and reports the exit status it should be judged by.
//
// The same supervision serves the namespace trampoline, whose child is this
diff --git a/cmd/nano-init/main_test.go b/cmd/nano-init/main_test.go
index 3c0572c1..9fcc87c0 100644
--- a/cmd/nano-init/main_test.go
+++ b/cmd/nano-init/main_test.go
@@ -15,213 +15,17 @@
package main
import (
- "net/netip"
"os"
"path/filepath"
"strings"
"testing"
-
- "golang.org/x/net/dns/dnsmessage"
)
-func TestTheSameNameAlwaysGetsTheSameAddress(t *testing.T) {
- // Clients cache. An agent that resolves once, holds the answer, and
- // connects later must arrive at the same place, or a long-lived agent
- // starts failing for reasons nothing in its own behaviour explains.
- r, err := newResolver("169.254.64.0/18")
- if err != nil {
- t.Fatalf("newResolver: %v", err)
- }
-
- first, err := r.assign("mesh.sam.alt")
- if err != nil {
- t.Fatalf("assign: %v", err)
- }
- again, err := r.assign("mesh.sam.alt")
- if err != nil {
- t.Fatalf("assign: %v", err)
- }
- other, err := r.assign("calc.mcp.sam.alt")
- if err != nil {
- t.Fatalf("assign: %v", err)
- }
-
- if first != again {
- t.Errorf("same name got %v then %v", first, again)
- }
- if first == other {
- t.Errorf("two names share the address %v", first)
- }
-}
-
-func TestTheAddressLeadsBackToTheName(t *testing.T) {
- // This is the whole point of the resolver: the boundary must be told a
- // name, because mesh.sam.alt has no address and the boundary is what
- // chooses a provider for it.
- r, err := newResolver("169.254.64.0/18")
- if err != nil {
- t.Fatalf("newResolver: %v", err)
- }
-
- addr, err := r.assign("mesh.sam.alt")
- if err != nil {
- t.Fatalf("assign: %v", err)
- }
-
- name, ok := r.nameFor(addr)
- if !ok || name != "mesh.sam.alt" {
- t.Errorf("nameFor(%v) = %q, %v; want mesh.sam.alt", addr, name, ok)
- }
-
- // An address nobody handed out is not an error: an agent may dial a
- // literal address, and whether that is allowed is policy's business.
- if _, ok := r.nameFor(netip.MustParseAddr("93.184.216.34")); ok {
- t.Error("an address that was never assigned resolved to a name")
- }
-}
-
-func TestTheAddressPoolIsBounded(t *testing.T) {
- // A /30 holds four addresses, and the network address is skipped. An
- // agent resolving endlessly must be refused rather than handed something
- // outside the pool that would then be routed somewhere real.
- r, err := newResolver("169.254.64.0/30")
- if err != nil {
- t.Fatalf("newResolver: %v", err)
- }
-
- var lastErr error
- for i := range 10 {
- if _, err := r.assign(strings.Repeat("a", i+1) + ".example"); err != nil {
- lastErr = err
- break
- }
- }
- if lastErr == nil {
- t.Error("the pool handed out more addresses than it contains")
- }
-}
-
-func TestAQueriesAreAnsweredWithAPlaceholder(t *testing.T) {
- r, err := newResolver("169.254.64.0/18")
- if err != nil {
- t.Fatalf("newResolver: %v", err)
- }
-
- query, err := buildQuery("mesh.sam.alt.", dnsmessage.TypeA)
- if err != nil {
- t.Fatalf("buildQuery: %v", err)
- }
-
- reply, err := r.answer(query)
- if err != nil {
- t.Fatalf("answer: %v", err)
- }
-
- var parser dnsmessage.Parser
- if _, err := parser.Start(reply); err != nil {
- t.Fatalf("parse reply: %v", err)
- }
- if err := parser.SkipAllQuestions(); err != nil {
- t.Fatalf("skip questions: %v", err)
- }
- answer, err := parser.AnswerHeader()
- if err != nil {
- t.Fatalf("answer header: %v", err)
- }
- if answer.Type != dnsmessage.TypeA {
- t.Fatalf("answer type = %v, want A", answer.Type)
- }
-
- resource, err := parser.AResource()
- if err != nil {
- t.Fatalf("A resource: %v", err)
- }
- got := netip.AddrFrom4(resource.A)
- if name, ok := r.nameFor(got); !ok || name != "mesh.sam.alt" {
- t.Errorf("answered %v, which maps to %q, %v", got, name, ok)
- }
-}
-
-func TestAAAAQueriesAreAnsweredEmpty(t *testing.T) {
- // A sandbox that got an AAAA answer would try IPv6 first and wait for it
- // to fail, which reads as a slow mesh rather than an absent address family.
- r, err := newResolver("169.254.64.0/18")
- if err != nil {
- t.Fatalf("newResolver: %v", err)
- }
-
- query, err := buildQuery("mesh.sam.alt.", dnsmessage.TypeAAAA)
- if err != nil {
- t.Fatalf("buildQuery: %v", err)
- }
- reply, err := r.answer(query)
- if err != nil {
- t.Fatalf("answer: %v", err)
- }
-
- var parser dnsmessage.Parser
- if _, err := parser.Start(reply); err != nil {
- t.Fatalf("parse reply: %v", err)
- }
- if err := parser.SkipAllQuestions(); err != nil {
- t.Fatalf("skip questions: %v", err)
- }
- if _, err := parser.AnswerHeader(); err == nil {
- t.Error("AAAA query produced an answer record")
- }
-}
-
-func TestConnectSendsTheNameNotTheAddress(t *testing.T) {
- // If this regresses, the boundary receives an address it cannot resolve a
- // provider for, and every mesh name stops working while every literal
- // address keeps working, which is a confusing way to lose the design.
- request, err := connectRequest("mesh.sam.alt", 80)
- if err != nil {
- t.Fatalf("connectRequest: %v", err)
- }
-
- if request[3] != atypDomain {
- t.Fatalf("address type = %d, want %d (domain)", request[3], atypDomain)
- }
- length := int(request[4])
- if got := string(request[5 : 5+length]); got != "mesh.sam.alt" {
- t.Errorf("name = %q, want mesh.sam.alt", got)
- }
- port := int(request[5+length])<<8 | int(request[6+length])
- if port != 80 {
- t.Errorf("port = %d, want 80", port)
- }
-}
-
-func TestConnectPassesLiteralAddressesThrough(t *testing.T) {
- // An agent that dials an address rather than a name is not doing anything
- // forbidden; the boundary still decides. Encoding it as a name would make
- // the boundary try to resolve "93.184.216.34" as a mesh service.
- request, err := connectRequest("93.184.216.34", 443)
- if err != nil {
- t.Fatalf("connectRequest: %v", err)
- }
- if request[3] != atypIPv4 {
- t.Errorf("address type = %d, want %d (IPv4)", request[3], atypIPv4)
- }
-}
-
-func TestConnectRefusesAnUnencodableName(t *testing.T) {
- if _, err := connectRequest(strings.Repeat("a", 256), 80); err == nil {
- t.Error("a name too long for the protocol was encoded anyway")
- }
-}
-
-func TestPolicyDenialIsLegibleAsPolicy(t *testing.T) {
- // An operator reading an agent's logs has to be able to tell "you may not"
- // from "the mesh is broken", because the two have nothing in common.
- if got := replyMessage(0x02); !strings.Contains(got, "not allowed") {
- t.Errorf("reply 0x02 reads as %q, which does not say it was policy", got)
- }
- if got := replyMessage(0x05); !strings.Contains(got, "refused") {
- t.Errorf("reply 0x05 reads as %q", got)
- }
-}
+// Name preservation — the property that mesh.sam.alt reaches the boundary as
+// a NAME, because the boundary chooses a provider from it — lives in the
+// tun2connect library now, and is pinned by that library's own tests. What
+// remains here is what nano-init still owns: the two ways of naming a
+// boundary, the agent's untouched environment, and the copy mode.
func TestTheAgentEnvironmentIsNotDoctored(t *testing.T) {
// The point of the rewrite: nano-init no longer reaches into the agent. If
@@ -294,18 +98,3 @@ func TestCopyFile(t *testing.T) {
t.Errorf("mode = %v, want the owner execute bit set", info.Mode().Perm())
}
}
-
-func buildQuery(name string, qtype dnsmessage.Type) ([]byte, error) {
- builder := dnsmessage.NewBuilder(nil, dnsmessage.Header{ID: 1234})
- if err := builder.StartQuestions(); err != nil {
- return nil, err
- }
- if err := builder.Question(dnsmessage.Question{
- Name: dnsmessage.MustNewName(name),
- Type: qtype,
- Class: dnsmessage.ClassINET,
- }); err != nil {
- return nil, err
- }
- return builder.Finish()
-}
diff --git a/cmd/nano-init/namespaces.go b/cmd/nano-init/namespaces.go
index eb3c191c..89528e35 100644
--- a/cmd/nano-init/namespaces.go
+++ b/cmd/nano-init/namespaces.go
@@ -258,9 +258,9 @@ func resolvConfSaysOurs(contents string) bool {
continue
}
// Any nameserver but ours, and the file is not one we can rely on.
- if !strings.EqualFold(fields[0], "nameserver") || len(fields) != 2 || fields[1] != tunIP {
+ if !strings.EqualFold(fields[0], "nameserver") || len(fields) != 2 || fields[1] != resolverIP {
return false
}
}
- return strings.Contains(contents, tunIP)
+ return strings.Contains(contents, resolverIP)
}
diff --git a/cmd/nano-init/namespaces_test.go b/cmd/nano-init/namespaces_test.go
index 46c699bd..cfb71dc1 100644
--- a/cmd/nano-init/namespaces_test.go
+++ b/cmd/nano-init/namespaces_test.go
@@ -147,12 +147,12 @@ func TestResolvConfAlreadyOurs(t *testing.T) {
}{
{
name: "the file a pod can mount for the sandbox",
- contents: "nameserver " + tunIP + "\n",
+ contents: "nameserver " + resolverIP + "\n",
want: true,
},
{
name: "comments and blank lines are not nameservers",
- contents: "# supplied by the platform\n\nnameserver " + tunIP + "\n",
+ contents: "# supplied by the platform\n\nnameserver " + resolverIP + "\n",
want: true,
},
{
@@ -165,7 +165,7 @@ func TestResolvConfAlreadyOurs(t *testing.T) {
// The dangerous one: ours plus somebody else's would send some
// lookups outside the boundary, so it does not count as done.
name: "ours alongside another server",
- contents: "nameserver " + tunIP + "\nnameserver 8.8.8.8\n",
+ contents: "nameserver " + resolverIP + "\nnameserver 8.8.8.8\n",
want: false,
},
{
diff --git a/cmd/nano-init/resolver.go b/cmd/nano-init/resolver.go
deleted file mode 100644
index 4f51c2e6..00000000
--- a/cmd/nano-init/resolver.go
+++ /dev/null
@@ -1,178 +0,0 @@
-// Copyright 2026 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package main
-
-import (
- "fmt"
- "net"
- "net/netip"
- "sync"
-
- "golang.org/x/net/dns/dnsmessage"
-)
-
-// The sandbox has to keep hold of the name.
-//
-// An agent asks for mesh.sam.alt, which has no address anywhere: the boundary
-// answers it by choosing a provider, and choosing is the whole point. But an
-// agent opens a socket to an address, and the packets that arrive at the tun
-// carry an address and nothing else. Somewhere between the two the name has to
-// survive.
-//
-// So this hands out an address that means nothing except "the name I was asked
-// for", and remembers which. When the flow comes back the other way, the
-// address is turned back into the name and it is the name that reaches the
-// boundary. The addresses are never real, never routed and never leave the
-// sandbox.
-//
-// This is not the DNS interception that used to live here. That answered with
-// real-looking addresses and then relied on the agent honouring proxy
-// variables to catch the connection; an agent that ignored them was outside
-// the boundary. Here the address is a token in a table, the route is the only
-// route, and an agent that ignores everything still arrives at the same place.
-
-// resolver allocates a placeholder address per name and remembers the pairing.
-type resolver struct {
- mu sync.RWMutex
- pool netip.Prefix
- next netip.Addr
- names map[netip.Addr]string
- addrs map[string]netip.Addr
-}
-
-func newResolver(pool string) (*resolver, error) {
- prefix, err := netip.ParsePrefix(pool)
- if err != nil {
- return nil, fmt.Errorf("virtual address pool %q: %w", pool, err)
- }
- return &resolver{
- pool: prefix,
- // The network address itself is skipped: handing it out would make a
- // name indistinguishable from "no name at all" in a packet capture.
- next: prefix.Addr().Next(),
- names: map[netip.Addr]string{},
- addrs: map[string]netip.Addr{},
- }, nil
-}
-
-// assign returns the placeholder for a name, allocating one if needed. The
-// same name always gets the same address, so an agent that resolves twice and
-// caches the first answer still reaches the same place.
-func (r *resolver) assign(name string) (netip.Addr, error) {
- r.mu.Lock()
- defer r.mu.Unlock()
-
- if addr, ok := r.addrs[name]; ok {
- return addr, nil
- }
- if !r.pool.Contains(r.next) {
- return netip.Addr{}, fmt.Errorf("virtual address pool %s exhausted", r.pool)
- }
-
- addr := r.next
- r.next = r.next.Next()
- r.names[addr] = name
- r.addrs[name] = addr
- return addr, nil
-}
-
-// nameFor returns the name a placeholder stands for. An address that was never
-// handed out is not an error: an agent may dial a literal address, and that is
-// policy's business rather than something to fail here.
-func (r *resolver) nameFor(addr netip.Addr) (string, bool) {
- r.mu.RLock()
- defer r.mu.RUnlock()
- name, ok := r.names[addr]
- return name, ok
-}
-
-// serveDNS answers A queries with placeholders until ctx ends.
-//
-// Nothing here is a security control. An agent that ignores this resolver and
-// hardcodes another one still has its packets routed through the tun, and
-// still reaches only what policy allows. This exists so that ordinary clients,
-// which resolve before they connect, get an address to connect to.
-func (r *resolver) serveDNS(conn net.PacketConn) {
- buf := make([]byte, 512)
- for {
- n, from, err := conn.ReadFrom(buf)
- if err != nil {
- return
- }
-
- reply, err := r.answer(buf[:n])
- if err != nil {
- continue
- }
- if _, err := conn.WriteTo(reply, from); err != nil {
- return
- }
- }
-}
-
-// answer builds a reply for one query.
-func (r *resolver) answer(query []byte) ([]byte, error) {
- var parser dnsmessage.Parser
- header, err := parser.Start(query)
- if err != nil {
- return nil, err
- }
- question, err := parser.Question()
- if err != nil {
- return nil, err
- }
-
- builder := dnsmessage.NewBuilder(nil, dnsmessage.Header{
- ID: header.ID,
- Response: true,
- Authoritative: true,
- RCode: dnsmessage.RCodeSuccess,
- })
- builder.EnableCompression()
- if err := builder.StartQuestions(); err != nil {
- return nil, err
- }
- if err := builder.Question(question); err != nil {
- return nil, err
- }
- if err := builder.StartAnswers(); err != nil {
- return nil, err
- }
-
- // Only A is answered. A sandbox that got a AAAA answer would try IPv6
- // first and wait for it to fail, which looks like a slow mesh.
- if question.Type == dnsmessage.TypeA {
- name := trimRoot(question.Name.String())
- addr, err := r.assign(name)
- if err != nil {
- return nil, err
- }
- if err := builder.AResource(
- dnsmessage.ResourceHeader{Name: question.Name, Class: question.Class, TTL: 1},
- dnsmessage.AResource{A: addr.As4()},
- ); err != nil {
- return nil, err
- }
- }
-
- return builder.Finish()
-}
-
-func trimRoot(name string) string {
- if len(name) > 0 && name[len(name)-1] == '.' {
- return name[:len(name)-1]
- }
- return name
-}
diff --git a/cmd/nano-init/vsock.go b/cmd/nano-init/vsock.go
index b2947ac8..39cdaa54 100644
--- a/cmd/nano-init/vsock.go
+++ b/cmd/nano-init/vsock.go
@@ -21,6 +21,7 @@ import (
"os"
"strconv"
"strings"
+ "time"
"github.com/mdlayher/vsock"
)
@@ -45,6 +46,10 @@ import (
const vsockScheme = "vsock://"
+// boundaryDialTimeout bounds opening one flow to the boundary; established
+// flows carry no deadline.
+const boundaryDialTimeout = 30 * time.Second
+
// dialBoundary opens a connection to the boundary named by spec, which is
// either "vsock://<cid>:<port>" or a Unix socket path.
func dialBoundary(ctx context.Context, spec string) (net.Conn, error) {
diff --git a/cmd/sam-bench/main.go b/cmd/sam-bench/main.go
index da63542a..1cf74f95 100644
--- a/cmd/sam-bench/main.go
+++ b/cmd/sam-bench/main.go
@@ -131,7 +131,7 @@ func main() {
}
flags := runCmd.Flags()
- flags.StringVar(&socket, "socket", "", "Sandbox boundary SOCKS5 socket to measure through; omit to measure the same workload without a boundary, which is the baseline")
+ flags.StringVar(&socket, "socket", "", "Sandbox boundary Unix socket (HTTP CONNECT) to measure through; omit to measure the same workload without a boundary, which is the baseline")
flags.StringVar(&unixTarget, "target-unix", "", "Dial the target over this Unix socket rather than resolving its host, so a baseline needs no relay in the path")
flags.StringVar(&target, "target", "", "URL to request, e.g. http://mesh.sam.alt/v1/models (required)")
flags.StringVar(&method, "method", "GET", "HTTP method")
diff --git a/cmd/sam-box/main.go b/cmd/sam-box/main.go
index 3d90c222..66ad0d7c 100644
--- a/cmd/sam-box/main.go
+++ b/cmd/sam-box/main.go
@@ -61,9 +61,9 @@ func main() {
runCmd := &cobra.Command{
Use: "run",
Short: "Serve the sandbox boundary for an agent",
- Long: "Serves SOCKS5 on a sandbox-facing Unix socket, so an unmodified agent reaches\n" +
- "mesh inference and tools by name, and reaches nothing else unless egress policy\n" +
- "allows it.",
+ Long: "Serves named HTTP tunnels (CONNECT for TCP, connect-udp for UDP) on a\n" +
+ "sandbox-facing Unix socket, so an unmodified agent reaches mesh inference and\n" +
+ "tools by name, and reaches nothing else unless egress policy allows it.",
SilenceUsage: true,
RunE: func(cmd *cobra.Command, args []string) error {
golog.SetAllLoggers(golog.LevelInfo)
@@ -102,7 +102,7 @@ func main() {
logger.Infof("Serving metrics on http://%s/metrics", metricsAddr)
}
- server := &sambox.SOCKS5Server{
+ server := &sambox.ConnectServer{
Dialer: &sambox.AgentDialer{
Router: &sambox.Router{Egress: egress},
SidecarSocket: sidecarSocket,
@@ -127,7 +127,7 @@ func main() {
},
}
- runCmd.Flags().StringVar(&sandboxSocket, "socket", "", "Path to the sandbox-facing Unix socket to serve SOCKS5 on (required)")
+ runCmd.Flags().StringVar(&sandboxSocket, "socket", "", "Path to the sandbox-facing Unix socket to serve the boundary (HTTP CONNECT) on (required)")
runCmd.Flags().StringVar(&sidecarSocket, "sidecar-socket", "", "Path to the local sam-node API Unix socket (required)")
runCmd.Flags().StringVar(&bundlePath, "bundle", "", "Path to the agent bundle declaring the agent's identity and its egress allowance")
runCmd.Flags().StringSliceVar(&egressAllow, "egress-allow", nil, "Destinations an unidentified sandbox may reach, e.g. api.github.com or *.pypi.org; use --bundle instead where an agent has an identity")
diff --git a/development/examples/agent-harness/requirements.txt b/development/examples/agent-harness/requirements.txt
index a0e09d86..0bdfb2da 100644
--- a/development/examples/agent-harness/requirements.txt
+++ b/development/examples/agent-harness/requirements.txt
@@ -2,7 +2,7 @@
# client, because there is no such thing: the mesh is reached with ordinary
# HTTP to an ordinary name.
#
-# There is no SOCKS support here on purpose. The sandbox routes the agent's
+# There is no proxy support here on purpose. The sandbox routes the agent's
# traffic to the boundary through tun0, so the agent neither configures a proxy
# nor knows there is one.
openai>=1.40,<3
diff --git a/install.sh b/install.sh
index 61ed31e9..8acf692d 100755
--- a/install.sh
+++ b/install.sh
@@ -25,7 +25,9 @@ esac
# Get latest release version
echo "Fetching latest release information..."
LATEST_RELEASE_URL="https://api.github.com/repos/${REPO}/releases/latest"
-VERSION=$(curl -s $LATEST_RELEASE_URL | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
+# `|| true`: with pipefail, a grep that matches nothing would kill the script
+# here instead of reaching the friendly error below.
+VERSION=$(curl -s $LATEST_RELEASE_URL | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/' || true)
if [ -z "$VERSION" ]; then
echo "Error: Could not find the latest release."
diff --git a/internal/bench/bench.go b/internal/bench/bench.go
index 4b07f015..83c34e09 100644
--- a/internal/bench/bench.go
+++ b/internal/bench/bench.go
@@ -22,11 +22,13 @@
// difference in the mesh.
//
// It reaches the mesh the way an agent does, through the sandbox boundary's
-// SOCKS5 socket, so what it measures is what an agent would experience rather
-// than what an operator with host access would.
+// Unix socket, opening each flow as a named HTTP CONNECT tunnel, so what it
+// measures is what an agent would experience rather than what an operator
+// with host access would.
package bench
import (
+ "bufio"
"bytes"
"context"
"errors"
@@ -35,19 +37,18 @@ import (
"math"
"net"
"net/http"
+ "net/url"
"sort"
"sync"
"time"
-
- "golang.org/x/net/proxy"
)
// Options describe one measurement run. The zero value is not useful: at
// minimum a Target and a positive Requests count are required.
type Options struct {
- // Socket is the sandbox boundary's SOCKS5 Unix socket. Empty measures the
- // same workload without the boundary, which is the baseline the mesh
- // numbers are only meaningful against.
+ // Socket is the sandbox boundary's Unix socket, which speaks HTTP CONNECT.
+ // Empty measures the same workload without the boundary, which is the
+ // baseline the mesh numbers are only meaningful against.
Socket string
// UnixTarget dials the target over this Unix socket instead of resolving
@@ -292,7 +293,8 @@ func once(ctx context.Context, client *http.Client, opts Options) Sample {
}
// newClient builds the transport the workload runs over. Through a boundary it
-// dials the SOCKS5 socket, which is the only path a sandboxed agent has.
+// opens each flow as a CONNECT tunnel on the boundary socket, which is the
+// only path a sandboxed agent has.
func newClient(opts Options) (*http.Client, error) {
transport := &http.Transport{
MaxIdleConnsPerHost: opts.Concurrency,
@@ -303,15 +305,10 @@ func newClient(opts Options) (*http.Client, error) {
case opts.Socket != "" && opts.UnixTarget != "":
return nil, errors.New("bench: a run goes through the boundary or straight to a socket, not both")
case opts.Socket != "":
- dialer, err := proxy.SOCKS5("unix", opts.Socket, nil, proxy.Direct)
- if err != nil {
- return nil, fmt.Errorf("bench: dial boundary %s: %w", opts.Socket, err)
- }
- contextDialer, ok := dialer.(proxy.ContextDialer)
- if !ok {
- return nil, errors.New("bench: SOCKS5 dialer does not support contexts")
+ socket := opts.Socket
+ transport.DialContext = func(ctx context.Context, _, addr string) (net.Conn, error) {
+ return dialThroughBoundary(ctx, socket, addr)
}
- transport.DialContext = contextDialer.DialContext
case opts.UnixTarget != "":
transport.DialContext = func(ctx context.Context, _, _ string) (net.Conn, error) {
return (&net.Dialer{}).DialContext(ctx, "unix", opts.UnixTarget)
@@ -323,6 +320,46 @@ func newClient(opts Options) (*http.Client, error) {
return &http.Client{Transport: transport}, nil
}
+// dialThroughBoundary opens one boundary flow: an authority-form CONNECT
+// naming the destination, answered 200 before any tunneled byte moves.
+func dialThroughBoundary(ctx context.Context, socket, addr string) (net.Conn, error) {
+ conn, err := (&net.Dialer{}).DialContext(ctx, "unix", socket)
+ if err != nil {
+ return nil, fmt.Errorf("bench: dial boundary %s: %w", socket, err)
+ }
+ if d, ok := ctx.Deadline(); ok {
+ _ = conn.SetDeadline(d)
+ }
+ req := &http.Request{Method: http.MethodConnect, URL: &url.URL{Host: addr}, Host: addr, Header: make(http.Header)}
+ if err := req.Write(conn); err != nil {
+ _ = conn.Close()
+ return nil, fmt.Errorf("bench: CONNECT %s: %w", addr, err)
+ }
+ br := bufio.NewReader(conn)
+ resp, err := http.ReadResponse(br, req)
+ if err != nil {
+ _ = conn.Close()
+ return nil, fmt.Errorf("bench: CONNECT %s: %w", addr, err)
+ }
+ if resp.StatusCode != http.StatusOK {
+ _ = conn.Close()
+ if reason := resp.Header.Get("Boundary-Reason"); reason != "" {
+ return nil, fmt.Errorf("bench: boundary refused %s: %s (%s)", addr, resp.Status, reason)
+ }
+ return nil, fmt.Errorf("bench: boundary refused %s: %s", addr, resp.Status)
+ }
+ _ = conn.SetDeadline(time.Time{})
+ return &bufferedConn{Conn: conn, br: br}, nil
+}
+
+// bufferedConn keeps bytes the response reader buffered past the header.
+type bufferedConn struct {
+ net.Conn
+ br *bufio.Reader
+}
+
+func (c *bufferedConn) Read(p []byte) (int, error) { return c.br.Read(p) }
+
func ttfbOf(samples []Sample) []time.Duration {
out := make([]time.Duration, 0, len(samples))
for _, s := range samples {
diff --git a/internal/sambox/capsule.go b/internal/sambox/capsule.go
new file mode 100644
index 00000000..9b0160bd
--- /dev/null
+++ b/internal/sambox/capsule.go
@@ -0,0 +1,136 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package sambox
+
+import (
+ "bufio"
+ "bytes"
+ "encoding/binary"
+ "errors"
+ "fmt"
+ "io"
+ "sync"
+)
+
+// HTTP capsules (RFC 9297) frame datagrams on a reliable stream, which is the
+// form connect-udp (RFC 9298) takes when the transport is not QUIC — here, a
+// Unix socket or vsock. This codec is deliberately standalone: the guest side
+// lives in the tun2connect library, but importing that library would pull a
+// userspace TCP stack into the module every SAM binary builds from, and the
+// boundary needs sixty lines of framing, not a netstack.
+
+// capsuleTypeDatagram carries one HTTP Datagram, whose payload for connect-udp
+// is a context ID (0) plus the UDP payload (RFC 9298 section 5).
+const capsuleTypeDatagram = 0x00
+
+// maxCapsulePayload bounds a peer's declared capsule length so a sandbox
+// cannot make the boundary allocate unbounded memory.
+const maxCapsulePayload = 1 << 16
+
+// varints are QUIC variable-length integers (RFC 9000 section 16).
+
+func appendVarint(b []byte, v uint64) []byte {
+ switch {
+ case v < 1<<6:
+ return append(b, byte(v))
+ case v < 1<<14:
+ return binary.BigEndian.AppendUint16(b, uint16(v)|0x4000)
+ case v < 1<<30:
+ return binary.BigEndian.AppendUint32(b, uint32(v)|0x8000_0000)
+ case v < 1<<62:
+ return binary.BigEndian.AppendUint64(b, v|0xc000_0000_0000_0000)
+ default:
+ panic("varint overflow")
+ }
+}
+
+func readVarint(r io.ByteReader) (uint64, error) {
+ b0, err := r.ReadByte()
+ if err != nil {
+ return 0, err
+ }
+ v := uint64(b0 & 0x3f)
+ for i := 1; i < 1<<(b0>>6); i++ {
+ b, err := r.ReadByte()
+ if err != nil {
+ if err == io.EOF {
+ err = io.ErrUnexpectedEOF
+ }
+ return 0, err
+ }
+ v = v<<8 | uint64(b)
+ }
+ return v, nil
+}
+
+// CapsuleStream frames HTTP Datagrams on a reliable stream. It is exported so
+// tests and non-tun2connect clients can speak the boundary's UDP form.
+type CapsuleStream struct {
+ wmu sync.Mutex
+ w io.Writer
+ r *bufio.Reader
+}
+
+func NewCapsuleStream(rw io.ReadWriter) *CapsuleStream {
+ return &CapsuleStream{w: rw, r: bufio.NewReader(rw)}
+}
+
+// WriteDatagram sends one UDP payload as a DATAGRAM capsule with context ID 0.
+// Safe for concurrent writers.
+func (s *CapsuleStream) WriteDatagram(p []byte) error {
+ buf := make([]byte, 0, len(p)+8)
+ buf = appendVarint(buf, capsuleTypeDatagram)
+ buf = appendVarint(buf, uint64(len(p))+1) // +1: the context ID below
+ buf = appendVarint(buf, 0)
+ buf = append(buf, p...)
+ s.wmu.Lock()
+ defer s.wmu.Unlock()
+ _, err := s.w.Write(buf)
+ return err
+}
+
+// ReadDatagram returns the next UDP payload, skipping capsule types and
+// datagram contexts it does not understand, as RFC 9297 requires.
+func (s *CapsuleStream) ReadDatagram() ([]byte, error) {
+ for {
+ ctype, err := readVarint(s.r)
+ if err != nil {
+ return nil, err
+ }
+ clen, err := readVarint(s.r)
+ if err != nil {
+ return nil, err
+ }
+ if clen > maxCapsulePayload {
+ return nil, fmt.Errorf("sambox: capsule of %d bytes exceeds limit", clen)
+ }
+ value := make([]byte, clen)
+ if _, err := io.ReadFull(s.r, value); err != nil {
+ return nil, err
+ }
+ if ctype != capsuleTypeDatagram {
+ continue
+ }
+ rd := bytes.NewReader(value)
+ ctxID, err := readVarint(rd)
+ if err != nil {
+ return nil, errors.New("sambox: malformed DATAGRAM capsule")
+ }
+ if ctxID != 0 {
+ continue
+ }
+ return value[len(value)-rd.Len():], nil
+ }
+}
diff --git a/internal/sambox/connect.go b/internal/sambox/connect.go
new file mode 100644
index 00000000..54c182c9
--- /dev/null
+++ b/internal/sambox/connect.go
@@ -0,0 +1,404 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package sambox
+
+import (
+ "bufio"
+ "context"
+ "encoding/base64"
+ "errors"
+ "fmt"
+ "io"
+ "log"
+ "net"
+ "net/http"
+ "net/netip"
+ "net/url"
+ "strconv"
+ "strings"
+ "sync"
+ "time"
+)
+
+// Named HTTP tunnels are the sandbox boundary protocol: authority-form CONNECT
+// (RFC 9110) for TCP, connect-udp (RFC 9298) with capsules (RFC 9297) for UDP.
+// A tunnel request carries the destination *name*, so egress policy is decided
+// on "api.github.com" rather than on an address that says nothing about who is
+// being talked to — the property the old SOCKS5 boundary was chosen for, kept.
+//
+// What CONNECT adds is symmetry and headroom. The reverse channel into a
+// sandbox already speaks `CONNECT <port>`, so with this the boundary is one
+// protocol in both directions; a refusal is a status code with a
+// Boundary-Reason header rather than a bare reply byte; headers are the
+// extension point identity and tracing arrive through; and connect-udp gives
+// UDP a *named*, policy-checked shape, where SOCKS5's UDP ASSOCIATE never fit
+// a one-socket boundary at all. The guest side is the tun2connect library,
+// and `curl --proxy` speaks the TCP half of it natively.
+
+// handshakeTimeout bounds reading the tunnel request only. Once a flow is
+// established it may stream for as long as it likes, so no deadline survives
+// into the relay.
+const handshakeTimeout = 10 * time.Second
+
+// Errors a Dialer returns to select a refusal status. Anything else becomes a
+// general failure, which is the right default: an unrecognised failure must
+// not be reported to a sandbox as a precise diagnostic.
+var (
+ // ErrNotAllowed is a policy denial: the destination is not permitted.
+ ErrNotAllowed = errors.New("connection not allowed by ruleset")
+
+ // ErrHostUnreachable means the destination could not be resolved or routed.
+ ErrHostUnreachable = errors.New("host unreachable")
+
+ // ErrConnectionRefused means the destination actively refused the flow.
+ ErrConnectionRefused = errors.New("connection refused")
+)
+
+// Destination is a requested target exactly as it arrived on the sandbox
+// boundary. Name is a domain when the client sent one, which is the case for
+// every flow that came through tun2connect's virtual DNS; a literal address
+// arrives when a client dialled an IP directly, and IsName says which.
+type Destination struct {
+ Name string
+ Port uint16
+ IsName bool
+
+ // Network is "tcp" for a CONNECT tunnel and "udp" for a connect-udp
+ // session. Empty means "tcp", so the zero value stays the common case.
+ Network string
+}
+
+// Address renders the destination as a dial target.
+func (d Destination) Address() string {
+ return net.JoinHostPort(d.Name, strconv.Itoa(int(d.Port)))
+}
+
+func (d Destination) String() string { return d.Address() }
+
+// network is Network with the zero value made explicit.
+func (d Destination) network() string {
+ if d.Network == "" {
+ return "tcp"
+ }
+ return d.Network
+}
+
+// Credentials are the Proxy-Authorization Basic username and password. When
+// one sam-box multiplexes several agents over a single socket, this is how a
+// flow says which agent it belongs to; the password is never logged.
+type Credentials struct {
+ Username string
+ Password string
+}
+
+// Dialer decides whether a requested destination may be reached and opens it.
+// It is the single policy enforcement point on the sandbox boundary.
+type Dialer interface {
+ DialDestination(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error)
+}
+
+// DialerFunc adapts a function to Dialer.
+type DialerFunc func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error)
+
+func (f DialerFunc) DialDestination(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ return f(ctx, creds, dst)
+}
+
+// ConnectServer serves the sandbox-facing side of the boundary.
+type ConnectServer struct {
+ // Dialer is required.
+ Dialer Dialer
+
+ // Authenticate, when set, makes Proxy-Authorization Basic credentials the
+ // only acceptable greeting: a client that offers none is answered 407
+ // rather than silently downgraded to an anonymous flow.
+ Authenticate func(Credentials) error
+}
+
+// Serve accepts connections until the listener fails or ctx is cancelled.
+func (s *ConnectServer) Serve(ctx context.Context, l net.Listener) error {
+ if s.Dialer == nil {
+ return errors.New("sambox: ConnectServer requires a Dialer")
+ }
+
+ go func() {
+ <-ctx.Done()
+ _ = l.Close()
+ }()
+
+ var wg sync.WaitGroup
+ defer wg.Wait()
+
+ for {
+ conn, err := l.Accept()
+ if err != nil {
+ if ctx.Err() != nil || errors.Is(err, net.ErrClosed) {
+ return nil
+ }
+ return err
+ }
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ // Cancelling must drop flows, not wait them out: an established
+ // relay only ends when one side closes, so an idle keep-alive
+ // connection would otherwise hold shutdown open until some other
+ // timeout fires.
+ stop := context.AfterFunc(ctx, func() { _ = conn.Close() })
+ defer stop()
+ s.handle(ctx, conn)
+ }()
+ }
+}
+
+func (s *ConnectServer) handle(ctx context.Context, conn net.Conn) {
+ defer func() { _ = conn.Close() }()
+
+ if err := conn.SetDeadline(time.Now().Add(handshakeTimeout)); err != nil {
+ return
+ }
+
+ br := bufio.NewReader(conn)
+ req, err := http.ReadRequest(br)
+ if err != nil {
+ // Not HTTP at all: there is nothing well-formed to answer with.
+ return
+ }
+
+ creds, err := s.credentials(req)
+ if err != nil {
+ writeRefusal(conn, http.StatusProxyAuthRequired, "credentials required",
+ "Proxy-Authenticate: Basic realm=\"sam-box\"")
+ return
+ }
+
+ var dst Destination
+ switch {
+ case req.Method == http.MethodConnect:
+ dst, err = connectDestination(req.Host)
+ case req.Method == http.MethodGet && strings.EqualFold(req.Header.Get("Upgrade"), "connect-udp"):
+ // EscapedPath, not Path: the parser has already unescaped Path, so a
+ // %2F inside a segment would change the segment count. The segments
+ // are unescaped individually after splitting.
+ dst, err = masqueDestination(req.URL.EscapedPath())
+ default:
+ writeRefusal(conn, http.StatusMethodNotAllowed, "the boundary speaks CONNECT and connect-udp only")
+ return
+ }
+ if err != nil {
+ writeRefusal(conn, http.StatusBadRequest, err.Error())
+ return
+ }
+
+ // The request is read. Dialling a mesh destination can involve discovery,
+ // so it must not inherit the handshake deadline; bounding it is the
+ // Dialer's job, through the context it is given.
+ if err := conn.SetDeadline(time.Time{}); err != nil {
+ return
+ }
+
+ upstream, err := s.Dialer.DialDestination(ctx, creds, dst)
+ if err != nil {
+ status, reason := refusalFor(err)
+ writeRefusal(conn, status, reason)
+ return
+ }
+ defer func() { _ = upstream.Close() }()
+
+ if dst.network() == "udp" {
+ if _, err := io.WriteString(conn, "HTTP/1.1 101 Switching Protocols\r\n"+
+ "Connection: Upgrade\r\nUpgrade: connect-udp\r\nCapsule-Protocol: ?1\r\n\r\n"); err != nil {
+ return
+ }
+ pumpUDP(NewCapsuleStream(&bufConn{Conn: conn, br: br}), upstream)
+ return
+ }
+
+ if _, err := io.WriteString(conn, "HTTP/1.1 200 OK\r\n\r\n"); err != nil {
+ return
+ }
+ // br first: it may hold bytes the client pipelined behind the request.
+ relay(&bufConn{Conn: conn, br: br}, upstream)
+}
+
+// credentials parses Proxy-Authorization and applies Authenticate when set.
+func (s *ConnectServer) credentials(req *http.Request) (*Credentials, error) {
+ creds := parseProxyBasicAuth(req.Header.Get("Proxy-Authorization"))
+ if s.Authenticate == nil {
+ return creds, nil
+ }
+ if creds == nil {
+ return nil, errors.New("credentials required")
+ }
+ if err := s.Authenticate(*creds); err != nil {
+ log.Printf("sambox: boundary authentication rejected for user %q", creds.Username)
+ return nil, err
+ }
+ return creds, nil
+}
+
+// parseProxyBasicAuth decodes "Basic <base64(user:pass)>", or returns nil.
+func parseProxyBasicAuth(header string) *Credentials {
+ fields := strings.Fields(header)
+ if len(fields) != 2 || !strings.EqualFold(fields[0], "Basic") {
+ return nil
+ }
+ decoded, err := base64.StdEncoding.DecodeString(fields[1])
+ if err != nil {
+ return nil
+ }
+ username, password, ok := strings.Cut(string(decoded), ":")
+ if !ok {
+ return nil
+ }
+ return &Credentials{Username: username, Password: password}
+}
+
+// connectDestination parses the authority-form CONNECT target.
+func connectDestination(hostport string) (Destination, error) {
+ host, rawPort, err := net.SplitHostPort(hostport)
+ if err != nil || host == "" {
+ return Destination{}, fmt.Errorf("malformed CONNECT target %q", hostport)
+ }
+ port, err := strconv.ParseUint(rawPort, 10, 16)
+ if err != nil {
+ return Destination{}, fmt.Errorf("malformed CONNECT port %q", rawPort)
+ }
+ _, isAddr := parseAddr(host)
+ return Destination{Name: host, Port: uint16(port), IsName: !isAddr, Network: "tcp"}, nil
+}
+
+// masqueDestination parses the default connect-udp URI template
+// /.well-known/masque/udp/{host}/{port}/ (RFC 9298 section 2).
+func masqueDestination(path string) (Destination, error) {
+ seg := strings.Split(strings.Trim(path, "/"), "/")
+ if len(seg) != 5 || seg[0] != ".well-known" || seg[1] != "masque" || seg[2] != "udp" {
+ return Destination{}, fmt.Errorf("malformed connect-udp template %q", path)
+ }
+ host, err := url.PathUnescape(seg[3])
+ if err != nil || host == "" {
+ return Destination{}, fmt.Errorf("malformed connect-udp target host")
+ }
+ port, err := strconv.ParseUint(seg[4], 10, 16)
+ if err != nil {
+ return Destination{}, fmt.Errorf("malformed connect-udp port %q", seg[4])
+ }
+ _, isAddr := parseAddr(host)
+ return Destination{Name: host, Port: uint16(port), IsName: !isAddr, Network: "udp"}, nil
+}
+
+func parseAddr(host string) (netip.Addr, bool) {
+ addr, err := netip.ParseAddr(host)
+ return addr, err == nil
+}
+
+// writeRefusal answers a request that will not become a tunnel. The status is
+// what a plain HTTP client sees; Boundary-Reason is what a log is read
+// against, and "not allowed by policy" has to be legible as a decision rather
+// than looking like the mesh being broken.
+func writeRefusal(conn net.Conn, status int, reason string, extraHeaders ...string) {
+ // The reason can quote request input, and a CR or LF in a header value
+ // is response splitting (CWE-113); strip them at the sink.
+ reason = strings.NewReplacer("\r", "", "\n", "").Replace(reason)
+ msg := fmt.Sprintf("HTTP/1.1 %d %s\r\nBoundary-Reason: %s\r\n",
+ status, http.StatusText(status), reason)
+ for _, h := range extraHeaders {
+ msg += h + "\r\n"
+ }
+ msg += "Content-Length: 0\r\n\r\n"
+ _, _ = io.WriteString(conn, msg)
+}
+
+func refusalFor(err error) (int, string) {
+ switch {
+ case errors.Is(err, ErrNotAllowed):
+ return http.StatusForbidden, "not allowed by policy"
+ case errors.Is(err, ErrHostUnreachable):
+ return http.StatusBadGateway, "host unreachable"
+ case errors.Is(err, ErrConnectionRefused):
+ return http.StatusBadGateway, "connection refused"
+ default:
+ return http.StatusInternalServerError, "general failure"
+ }
+}
+
+// pumpUDP carries one connect-udp session: capsules from the client become
+// datagrams upstream and back, until either side ends the session.
+func pumpUDP(cs *CapsuleStream, upstream net.Conn) {
+ go func() {
+ defer func() { _ = upstream.Close() }()
+ for {
+ p, err := cs.ReadDatagram()
+ if err != nil {
+ return
+ }
+ if _, err := upstream.Write(p); err != nil {
+ return
+ }
+ }
+ }()
+ buf := make([]byte, 65535)
+ for {
+ n, err := upstream.Read(buf)
+ if err != nil {
+ return
+ }
+ if cs.WriteDatagram(buf[:n]) != nil {
+ return
+ }
+ }
+}
+
+// bufConn keeps bytes the request reader buffered past the header visible to
+// the relay, and keeps the half-close the relay depends on reachable.
+type bufConn struct {
+ net.Conn
+ br *bufio.Reader
+}
+
+func (c *bufConn) Read(p []byte) (int, error) { return c.br.Read(p) }
+
+func (c *bufConn) CloseWrite() error {
+ if cw, ok := c.Conn.(interface{ CloseWrite() error }); ok {
+ return cw.CloseWrite()
+ }
+ return c.Close()
+}
+
+func relay(client, upstream net.Conn) {
+ var wg sync.WaitGroup
+ wg.Add(2)
+ go func() {
+ defer wg.Done()
+ _, _ = io.Copy(upstream, client)
+ closeWrite(upstream)
+ }()
+ go func() {
+ defer wg.Done()
+ _, _ = io.Copy(client, upstream)
+ closeWrite(client)
+ }()
+ wg.Wait()
+}
+
+// closeWrite propagates a half-close so a peer waiting on EOF is not left
+// hanging until a timeout.
+func closeWrite(conn net.Conn) {
+ if cw, ok := conn.(interface{ CloseWrite() error }); ok {
+ _ = cw.CloseWrite()
+ return
+ }
+ _ = conn.Close()
+}
diff --git a/internal/sambox/connect_test.go b/internal/sambox/connect_test.go
new file mode 100644
index 00000000..8022f7fb
--- /dev/null
+++ b/internal/sambox/connect_test.go
@@ -0,0 +1,638 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package sambox
+
+import (
+ "bufio"
+ "context"
+ "encoding/base64"
+ "errors"
+ "io"
+ "net"
+ "net/http"
+ "net/url"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+// startBoundary serves s on a Unix socket, the transport the sandbox boundary
+// actually uses, and returns its path.
+func startBoundary(t *testing.T, s *ConnectServer) string {
+ t.Helper()
+
+ // Not t.TempDir(): test names make paths long enough to hit the ~108 byte
+ // sockaddr_un limit.
+ dir, err := os.MkdirTemp("", "sambox")
+ if err != nil {
+ t.Fatalf("MkdirTemp: %v", err)
+ }
+ t.Cleanup(func() { _ = os.RemoveAll(dir) })
+
+ path := filepath.Join(dir, "agent.sock")
+ l, err := net.Listen("unix", path)
+ if err != nil {
+ t.Fatalf("listen: %v", err)
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ if err := s.Serve(ctx, l); err != nil {
+ t.Errorf("Serve: %v", err)
+ }
+ }()
+ t.Cleanup(func() {
+ cancel()
+ <-done
+ })
+ return path
+}
+
+// startEcho returns the address of a server that echoes what it is sent.
+func startEcho(t *testing.T) string {
+ t.Helper()
+ l, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatalf("listen: %v", err)
+ }
+ t.Cleanup(func() { _ = l.Close() })
+
+ go func() {
+ for {
+ conn, err := l.Accept()
+ if err != nil {
+ return
+ }
+ go func() {
+ defer func() { _ = conn.Close() }()
+ _, _ = io.Copy(conn, conn)
+ }()
+ }
+ }()
+ return l.Addr().String()
+}
+
+// startUDPEcho returns the address of a datagram server that echoes.
+func startUDPEcho(t *testing.T) string {
+ t.Helper()
+ pc, err := net.ListenPacket("udp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatalf("listen udp: %v", err)
+ }
+ t.Cleanup(func() { _ = pc.Close() })
+
+ go func() {
+ buf := make([]byte, 65535)
+ for {
+ n, from, err := pc.ReadFrom(buf)
+ if err != nil {
+ return
+ }
+ _, _ = pc.WriteTo(buf[:n], from)
+ }
+ }()
+ return pc.LocalAddr().String()
+}
+
+// dialRaw opens a plain connection to the boundary, for the cases a
+// well-behaved client library will never produce.
+func dialRaw(t *testing.T, path string) net.Conn {
+ t.Helper()
+ conn, err := net.Dial("unix", path)
+ if err != nil {
+ t.Fatalf("dial: %v", err)
+ }
+ t.Cleanup(func() { _ = conn.Close() })
+ if err := conn.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
+ t.Fatalf("SetDeadline: %v", err)
+ }
+ return conn
+}
+
+func basicAuth(user, pass string) string {
+ return "Basic " + base64.StdEncoding.EncodeToString([]byte(user+":"+pass))
+}
+
+// boundaryDialContext returns a DialContext that opens each flow as a CONNECT
+// tunnel through the boundary at path, the way tun2connect does in a sandbox.
+func boundaryDialContext(path string) func(ctx context.Context, network, addr string) (net.Conn, error) {
+ return func(ctx context.Context, _, addr string) (net.Conn, error) {
+ var d net.Dialer
+ conn, err := d.DialContext(ctx, "unix", path)
+ if err != nil {
+ return nil, err
+ }
+ req := &http.Request{Method: http.MethodConnect, URL: &url.URL{Host: addr}, Host: addr, Header: make(http.Header)}
+ if err := req.Write(conn); err != nil {
+ _ = conn.Close()
+ return nil, err
+ }
+ br := bufio.NewReader(conn)
+ resp, err := http.ReadResponse(br, req)
+ if err != nil {
+ _ = conn.Close()
+ return nil, err
+ }
+ if resp.StatusCode != http.StatusOK {
+ _ = conn.Close()
+ return nil, errors.New("boundary refused: " + resp.Status)
+ }
+ return &bufConn{Conn: conn, br: br}, nil
+ }
+}
+
+// connectRoundTrip writes an authority-form CONNECT for hostport and returns
+// the connection, the buffered reader holding anything past the response, and
+// the response itself.
+func connectRoundTrip(t *testing.T, path, hostport string, header http.Header) (net.Conn, *bufio.Reader, *http.Response) {
+ t.Helper()
+ conn := dialRaw(t, path)
+ req := &http.Request{
+ Method: http.MethodConnect,
+ URL: &url.URL{Host: hostport},
+ Host: hostport,
+ Header: header,
+ }
+ if req.Header == nil {
+ req.Header = make(http.Header)
+ }
+ if err := req.Write(conn); err != nil {
+ t.Fatalf("write CONNECT: %v", err)
+ }
+ br := bufio.NewReader(conn)
+ resp, err := http.ReadResponse(br, req)
+ if err != nil {
+ t.Fatalf("read CONNECT response: %v", err)
+ }
+ return conn, br, resp
+}
+
+// connectThrough opens a CONNECT tunnel and fails the test on refusal.
+func connectThrough(t *testing.T, path, hostport string) net.Conn {
+ t.Helper()
+ conn, br, resp := connectRoundTrip(t, path, hostport, nil)
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("CONNECT %s = %s (reason %q), want 200", hostport, resp.Status, resp.Header.Get("Boundary-Reason"))
+ }
+ return &bufConn{Conn: conn, br: br}
+}
+
+// TestConnectPreservesDestinationName is the property the whole boundary rests
+// on: policy must see the name the agent asked for, never a resolved address.
+func TestConnectPreservesDestinationName(t *testing.T) {
+ echo := startEcho(t)
+
+ seen := make(chan Destination, 1)
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ seen <- dst
+ return net.Dial("tcp", echo)
+ }),
+ })
+
+ conn := connectThrough(t, path, "api.github.com:443")
+ defer func() { _ = conn.Close() }()
+
+ if _, err := conn.Write([]byte("ping")); err != nil {
+ t.Fatalf("write: %v", err)
+ }
+ got := make([]byte, 4)
+ if _, err := io.ReadFull(conn, got); err != nil {
+ t.Fatalf("read: %v", err)
+ }
+ if string(got) != "ping" {
+ t.Errorf("echo = %q, want %q", got, "ping")
+ }
+
+ dst := <-seen
+ if !dst.IsName {
+ t.Errorf("destination %+v was not reported as a name", dst)
+ }
+ if dst.Name != "api.github.com" || dst.Port != 443 || dst.network() != "tcp" {
+ t.Errorf("destination = %s over %s, want api.github.com:443 over tcp", dst, dst.network())
+ }
+}
+
+func TestConnectDeniedByPolicy(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ return nil, ErrNotAllowed
+ }),
+ })
+
+ _, _, resp := connectRoundTrip(t, path, "evil.example:80", nil)
+ if resp.StatusCode != http.StatusForbidden {
+ t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusForbidden)
+ }
+ if reason := resp.Header.Get("Boundary-Reason"); reason != "not allowed by policy" {
+ t.Errorf("Boundary-Reason = %q, want a legible policy denial", reason)
+ }
+}
+
+func TestNonTunnelMethodsAreRefused(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ t.Error("dialer must not be reached for a non-tunnel request")
+ return nil, errors.New("unreachable")
+ }),
+ })
+
+ // A GET without the connect-udp upgrade is a client that thinks this is a
+ // web server; the boundary is not one.
+ for _, method := range []string{http.MethodGet, http.MethodPost} {
+ conn := dialRaw(t, path)
+ req, err := http.NewRequest(method, "http://boundary/anything", nil)
+ if err != nil {
+ t.Fatalf("NewRequest: %v", err)
+ }
+ if err := req.Write(conn); err != nil {
+ t.Fatalf("write request: %v", err)
+ }
+ resp, err := http.ReadResponse(bufio.NewReader(conn), req)
+ if err != nil {
+ t.Fatalf("read response: %v", err)
+ }
+ if resp.StatusCode != http.StatusMethodNotAllowed {
+ t.Errorf("%s: status = %d, want %d", method, resp.StatusCode, http.StatusMethodNotAllowed)
+ }
+ }
+}
+
+func TestMalformedConnectTargetIsRefused(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ t.Error("dialer must not be reached for a malformed target")
+ return nil, errors.New("unreachable")
+ }),
+ })
+
+ // Authority form requires host:port; a bare host must be refused rather
+ // than guessed at.
+ _, _, resp := connectRoundTrip(t, path, "api.github.com", nil)
+ if resp.StatusCode != http.StatusBadRequest {
+ t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusBadRequest)
+ }
+}
+
+func TestConnectByIPLiteralIsNotReportedAsAName(t *testing.T) {
+ echo := startEcho(t)
+
+ seen := make(chan Destination, 1)
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ seen <- dst
+ return net.Dial("tcp", echo)
+ }),
+ })
+
+ conn := connectThrough(t, path, "192.0.2.10:443")
+ defer func() { _ = conn.Close() }()
+
+ dst := <-seen
+ if dst.IsName {
+ t.Errorf("destination %+v was reported as a name", dst)
+ }
+ if dst.Name != "192.0.2.10" || dst.Port != 443 {
+ t.Errorf("destination = %s, want 192.0.2.10:443", dst)
+ }
+}
+
+// TestAuthenticationIsNotDowngraded pins that a server expecting credentials
+// refuses an anonymous client instead of serving it unidentified.
+func TestAuthenticationIsNotDowngraded(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ t.Error("dialer must not be reached for an unauthenticated client")
+ return nil, errors.New("unreachable")
+ }),
+ Authenticate: func(Credentials) error { return nil },
+ })
+
+ _, _, resp := connectRoundTrip(t, path, "api.github.com:443", nil)
+ if resp.StatusCode != http.StatusProxyAuthRequired {
+ t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusProxyAuthRequired)
+ }
+ if resp.Header.Get("Proxy-Authenticate") == "" {
+ t.Error("a 407 must say how to authenticate")
+ }
+}
+
+func TestAuthenticatedFlowCarriesCredentials(t *testing.T) {
+ echo := startEcho(t)
+
+ seen := make(chan *Credentials, 1)
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ seen <- creds
+ return net.Dial("tcp", echo)
+ }),
+ Authenticate: func(c Credentials) error {
+ if c.Username != "reviewer-7.prod.acme.example" {
+ return errors.New("unknown agent")
+ }
+ return nil
+ },
+ })
+
+ header := make(http.Header)
+ header.Set("Proxy-Authorization", basicAuth("reviewer-7.prod.acme.example", "admission-token"))
+ _, _, resp := connectRoundTrip(t, path, "code-reviewer.mcp.sam.alt:80", header)
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("status = %d, want 200", resp.StatusCode)
+ }
+
+ creds := <-seen
+ if creds == nil {
+ t.Fatal("dialer received no credentials")
+ }
+ if creds.Username != "reviewer-7.prod.acme.example" || creds.Password != "admission-token" {
+ t.Errorf("credentials = %+v, want the agent id and its admission token", creds)
+ }
+}
+
+func TestRejectedCredentialsFailTheHandshake(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ t.Error("dialer must not be reached when authentication fails")
+ return nil, errors.New("unreachable")
+ }),
+ Authenticate: func(Credentials) error { return errors.New("unknown agent") },
+ })
+
+ header := make(http.Header)
+ header.Set("Proxy-Authorization", basicAuth("bar", "nope"))
+ _, _, resp := connectRoundTrip(t, path, "api.github.com:443", header)
+ if resp.StatusCode != http.StatusProxyAuthRequired {
+ t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusProxyAuthRequired)
+ }
+}
+
+func TestNonHTTPGreetingIsDropped(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ t.Error("dialer must not be reached for a non-HTTP client")
+ return nil, errors.New("unreachable")
+ }),
+ })
+
+ conn := dialRaw(t, path)
+ // A SOCKS5 greeting, which is what the previous boundary spoke: there is
+ // nothing well-formed to answer it with. The newline lets the boundary
+ // judge the line now rather than waiting out the handshake deadline.
+ if _, err := conn.Write([]byte("\x05\x01\x00\r\n")); err != nil {
+ t.Fatalf("write greeting: %v", err)
+ }
+ if _, err := io.ReadFull(conn, make([]byte, 1)); !errors.Is(err, io.EOF) {
+ t.Errorf("read after non-HTTP greeting = %v, want EOF", err)
+ }
+}
+
+// TestConnectUDPRoundTrip pins the boundary's UDP shape: a connect-udp upgrade
+// naming the destination, then DATAGRAM capsules both ways.
+func TestConnectUDPRoundTrip(t *testing.T) {
+ echo := startUDPEcho(t)
+
+ seen := make(chan Destination, 1)
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ seen <- dst
+ return net.Dial("udp", echo)
+ }),
+ })
+
+ conn := dialRaw(t, path)
+ req := &http.Request{
+ Method: http.MethodGet,
+ URL: &url.URL{Scheme: "http", Host: "boundary", Path: "/.well-known/masque/udp/dns.example/53/"},
+ Host: "boundary",
+ Header: make(http.Header),
+ }
+ req.Header.Set("Connection", "Upgrade")
+ req.Header.Set("Upgrade", "connect-udp")
+ req.Header.Set("Capsule-Protocol", "?1")
+ if err := req.Write(conn); err != nil {
+ t.Fatalf("write connect-udp: %v", err)
+ }
+ br := bufio.NewReader(conn)
+ resp, err := http.ReadResponse(br, req)
+ if err != nil {
+ t.Fatalf("read response: %v", err)
+ }
+ if resp.StatusCode != http.StatusSwitchingProtocols || resp.Header.Get("Upgrade") != "connect-udp" {
+ t.Fatalf("response = %s (Upgrade %q), want 101 connect-udp", resp.Status, resp.Header.Get("Upgrade"))
+ }
+
+ dst := <-seen
+ if dst.Name != "dns.example" || dst.Port != 53 || dst.network() != "udp" || !dst.IsName {
+ t.Errorf("destination = %+v, want dns.example:53 over udp as a name", dst)
+ }
+
+ cs := NewCapsuleStream(&bufConn{Conn: conn, br: br})
+ if err := cs.WriteDatagram([]byte("ping")); err != nil {
+ t.Fatalf("WriteDatagram: %v", err)
+ }
+ got, err := cs.ReadDatagram()
+ if err != nil {
+ t.Fatalf("ReadDatagram: %v", err)
+ }
+ if string(got) != "ping" {
+ t.Errorf("echo = %q, want %q", got, "ping")
+ }
+}
+
+// TestMasqueDestinationSurvivesEscapedSlashes pins the parsing order: split
+// the escaped path first, unescape each segment after, so a %2F inside the
+// host cannot change the segment count.
+func TestMasqueDestinationSurvivesEscapedSlashes(t *testing.T) {
+ dst, err := masqueDestination("/.well-known/masque/udp/odd%2Fname/53/")
+ if err != nil {
+ t.Fatalf("masqueDestination: %v", err)
+ }
+ if dst.Name != "odd/name" || dst.Port != 53 {
+ t.Errorf("destination = %+v, want odd/name:53", dst)
+ }
+}
+
+func TestParseProxyBasicAuth(t *testing.T) {
+ valid := basicAuth("user", "pass")
+ tests := []struct {
+ name string
+ header string
+ want *Credentials
+ }{
+ {"well formed", valid, &Credentials{Username: "user", Password: "pass"}},
+ {"case-insensitive scheme", "basic " + strings.TrimPrefix(valid, "Basic "), &Credentials{Username: "user", Password: "pass"}},
+ {"extra whitespace", "Basic " + strings.TrimPrefix(valid, "Basic "), &Credentials{Username: "user", Password: "pass"}},
+ {"empty", "", nil},
+ {"wrong scheme", "Bearer token", nil},
+ {"not base64", "Basic !!!", nil},
+ {"no colon", "Basic " + base64.StdEncoding.EncodeToString([]byte("nocolon")), nil},
+ }
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ got := parseProxyBasicAuth(tc.header)
+ if (got == nil) != (tc.want == nil) || (got != nil && *got != *tc.want) {
+ t.Errorf("parseProxyBasicAuth(%q) = %+v, want %+v", tc.header, got, tc.want)
+ }
+ })
+ }
+}
+
+// TestRefusalReasonCannotSplitTheResponse pins the CWE-113 fix: a reason
+// carrying CRLF must not become a second header or response.
+func TestRefusalReasonCannotSplitTheResponse(t *testing.T) {
+ client, server := net.Pipe()
+ defer func() { _ = client.Close() }()
+ go func() {
+ writeRefusal(server, http.StatusForbidden, "bad\r\nInjected: header\r\n\r\nHTTP/1.1 200 OK")
+ _ = server.Close()
+ }()
+
+ resp, err := http.ReadResponse(bufio.NewReader(client), nil)
+ if err != nil {
+ t.Fatalf("ReadResponse: %v", err)
+ }
+ if resp.StatusCode != http.StatusForbidden {
+ t.Errorf("status = %d, want 403", resp.StatusCode)
+ }
+ if got := resp.Header.Get("Injected"); got != "" {
+ t.Errorf("Injected header = %q, the reason split the response", got)
+ }
+}
+
+func TestConnectUDPDeniedByPolicy(t *testing.T) {
+ path := startBoundary(t, &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ return nil, ErrNotAllowed
+ }),
+ })
+
+ conn := dialRaw(t, path)
+ req := &http.Request{
+ Method: http.MethodGet,
+ URL: &url.URL{Scheme: "http", Host: "boundary", Path: "/.well-known/masque/udp/evil.example/53/"},
+ Host: "boundary",
+ Header: make(http.Header),
+ }
+ req.Header.Set("Connection", "Upgrade")
+ req.Header.Set("Upgrade", "connect-udp")
+ req.Header.Set("Capsule-Protocol", "?1")
+ if err := req.Write(conn); err != nil {
+ t.Fatalf("write connect-udp: %v", err)
+ }
+ resp, err := http.ReadResponse(bufio.NewReader(conn), req)
+ if err != nil {
+ t.Fatalf("read response: %v", err)
+ }
+ if resp.StatusCode != http.StatusForbidden {
+ t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusForbidden)
+ }
+}
+
+// TestServeDropsFlowsOnCancel pins that shutdown is prompt. An established
+// relay only ends when one side closes, so without this an idle keep-alive
+// connection holds the gateway open until some unrelated timeout fires.
+func TestServeDropsFlowsOnCancel(t *testing.T) {
+ echo := startEcho(t)
+
+ dir, err := os.MkdirTemp("", "sambox")
+ if err != nil {
+ t.Fatalf("MkdirTemp: %v", err)
+ }
+ t.Cleanup(func() { _ = os.RemoveAll(dir) })
+ socket := filepath.Join(dir, "agent.sock")
+
+ l, err := net.Listen("unix", socket)
+ if err != nil {
+ t.Fatalf("listen: %v", err)
+ }
+
+ server := &ConnectServer{
+ Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
+ return net.Dial("tcp", echo)
+ }),
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
+ served := make(chan error, 1)
+ go func() { served <- server.Serve(ctx, l) }()
+
+ // Serve is racing this dial; retry briefly until the listener answers.
+ var conn net.Conn
+ for range 50 {
+ conn, _, _ = func() (net.Conn, *bufio.Reader, *http.Response) {
+ c, err := net.Dial("unix", socket)
+ if err != nil {
+ time.Sleep(10 * time.Millisecond)
+ return nil, nil, nil
+ }
+ req := &http.Request{Method: http.MethodConnect, URL: &url.URL{Host: "api.github.com:443"}, Host: "api.github.com:443", Header: make(http.Header)}
+ if err := req.Write(c); err != nil {
+ _ = c.Close()
+ return nil, nil, nil
+ }
+ br := bufio.NewReader(c)
+ if _, err := http.ReadResponse(br, req); err != nil {
+ _ = c.Close()
+ return nil, nil, nil
+ }
+ return c, br, nil
+ }()
+ if conn != nil {
+ break
+ }
+ }
+ if conn == nil {
+ t.Fatal("could not establish a flow through the boundary")
+ }
+ defer func() { _ = conn.Close() }()
+
+ // The flow is established and idle, which is the case that used to hang.
+ cancel()
+ select {
+ case err := <-served:
+ if err != nil {
+ t.Fatalf("Serve: %v", err)
+ }
+ case <-time.After(10 * time.Second):
+ t.Fatal("Serve did not return after cancel; an idle flow is holding shutdown open")
+ }
+}
+
+func TestRefusalFor(t *testing.T) {
+ tests := []struct {
+ name string
+ err error
+ wantStatus int
+ }{
+ {"policy denial", ErrNotAllowed, http.StatusForbidden},
+ {"unreachable", ErrHostUnreachable, http.StatusBadGateway},
+ {"refused", ErrConnectionRefused, http.StatusBadGateway},
+ {"wrapped denial", errors.Join(errors.New("context"), ErrNotAllowed), http.StatusForbidden},
+ {"anything else stays generic", errors.New("boom"), http.StatusInternalServerError},
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ if got, _ := refusalFor(tc.err); got != tc.wantStatus {
+ t.Errorf("refusalFor(%v) = %d, want %d", tc.err, got, tc.wantStatus)
+ }
+ })
+ }
+}
diff --git a/internal/sambox/dial.go b/internal/sambox/dial.go
index 8c77ea00..e5516572 100644
--- a/internal/sambox/dial.go
+++ b/internal/sambox/dial.go
@@ -24,14 +24,14 @@ import (
"time"
)
-// dialTimeout bounds opening a destination. The SOCKS5 layer deliberately drops
-// its handshake deadline before dialling, so this is the only bound and it has
-// to exist here.
+// dialTimeout bounds opening a destination. The CONNECT layer deliberately
+// drops its handshake deadline before dialling, so this is the only bound and
+// it has to exist here.
const dialTimeout = 30 * time.Second
// AgentDialer opens whatever a Route calls for. It is the only place in the
// sandbox boundary that touches the network, which keeps the routing decision
-// (route.go) and the protocol (socks5.go) free of I/O.
+// (route.go) and the protocol (connect.go) free of I/O.
type AgentDialer struct {
// Router classifies destinations. Required.
Router *Router
@@ -87,7 +87,7 @@ func (d *AgentDialer) dialRoute(ctx context.Context, route Route, dst Destinatio
case RouteMeshEntrypoint:
return d.dialMeshEntrypoint()
case RouteExternal:
- return d.dial(ctx, "tcp", dst.Address())
+ return d.dial(ctx, dst.network(), dst.Address())
case RouteMeshService:
return d.dialMeshService(ctx, route)
default:
@@ -139,7 +139,7 @@ func (d *AgentDialer) dial(ctx context.Context, network, address string) (net.Co
return conn, nil
}
-// classifyDialError maps a dial failure onto the vocabulary the SOCKS5 layer
+// classifyDialError maps a dial failure onto the vocabulary the CONNECT layer
// can report, so an agent sees "refused" or "unreachable" rather than a
// generic failure it cannot act on.
func classifyDialError(err error) error {
diff --git a/internal/sambox/dial_test.go b/internal/sambox/dial_test.go
index c3695a2f..b73eaf99 100644
--- a/internal/sambox/dial_test.go
+++ b/internal/sambox/dial_test.go
@@ -18,6 +18,7 @@ import (
"context"
"errors"
"net"
+ "net/http"
"testing"
"github.com/google/sam/api"
@@ -83,8 +84,8 @@ func TestRefusedDestinationIsReportedAsRefused(t *testing.T) {
if !errors.Is(err, ErrConnectionRefused) {
t.Fatalf("DialDestination to a closed port = %v, want ErrConnectionRefused", err)
}
- if code := replyCodeFor(err); code != replyConnectionRefused {
- t.Errorf("reply code = %#x, want %#x", code, replyConnectionRefused)
+ if status, _ := refusalFor(err); status != http.StatusBadGateway {
+ t.Errorf("refusal status = %d, want %d", status, http.StatusBadGateway)
}
}
diff --git a/internal/sambox/entrypoint_test.go b/internal/sambox/entrypoint_test.go
index a6663ba8..6b1e0cf5 100644
--- a/internal/sambox/entrypoint_test.go
+++ b/internal/sambox/entrypoint_test.go
@@ -21,7 +21,6 @@ import (
"testing"
"github.com/google/sam/api"
- "golang.org/x/net/proxy"
)
type sidecarCall struct {
@@ -52,18 +51,10 @@ func entrypointClient(t *testing.T, socket string) *http.Client {
func entrypointClientForAgent(t *testing.T, socket, agentID string) *http.Client {
t.Helper()
- boundary := startSOCKS5(t, &SOCKS5Server{
+ boundary := startBoundary(t, &ConnectServer{
Dialer: &AgentDialer{Router: &Router{}, SidecarSocket: socket, AgentID: agentID},
})
- dialer, err := proxy.SOCKS5("unix", boundary, nil, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- contextDialer, ok := dialer.(proxy.ContextDialer)
- if !ok {
- t.Fatal("SOCKS5 dialer does not implement ContextDialer")
- }
- return &http.Client{Transport: &http.Transport{DialContext: contextDialer.DialContext}}
+ return &http.Client{Transport: &http.Transport{DialContext: boundaryDialContext(boundary)}}
}
// TestAgentIdentityIsAssertedToTheNode covers the half of admission that makes
@@ -132,7 +123,8 @@ func TestAgentCannotForgeItsIdentity(t *testing.T) {
}
// TestAgentReachesInferenceAndTools covers what an agent is supposed to have:
-// the mesh's inference and tool endpoints, reached by name, over SOCKS5.
+// the mesh's inference and tool endpoints, reached by name, through the
+// boundary's CONNECT tunnels.
func TestAgentReachesInferenceAndTools(t *testing.T) {
socket, calls := recordingSidecar(t)
client := entrypointClient(t, socket)
diff --git a/internal/sambox/mesh.go b/internal/sambox/mesh.go
index bf82d7e3..22cff68a 100644
--- a/internal/sambox/mesh.go
+++ b/internal/sambox/mesh.go
@@ -33,8 +33,8 @@ import (
// The agent speaks HTTP to "openrouter.inference.sam.alt", while the sidecar
// routes by path, so somebody has to discover a provider and rewrite the
// request onto /sam/<peer>/<type>/<name>. That happens here, on an in-process
-// HTTP server whose other end is handed back to the SOCKS5 layer as an ordinary
-// connection.
+// HTTP server whose other end is handed back to the CONNECT layer as an
+// ordinary connection.
const (
// maxDiscoverBody bounds the discovery response. It is small and local, but
@@ -78,7 +78,7 @@ func (d *AgentDialer) dialMeshService(ctx context.Context, route Route) (net.Con
}
// serveOnPipe runs h on one end of an in-memory connection and hands back the
-// other, so an HTTP handler can be given to the SOCKS5 layer as an ordinary
+// other, so an HTTP handler can be given to the CONNECT layer as an ordinary
// connection.
func serveOnPipe(h http.Handler) net.Conn {
agentSide, boundarySide := net.Pipe()
diff --git a/internal/sambox/mesh_test.go b/internal/sambox/mesh_test.go
index 2bd68656..cf995e1b 100644
--- a/internal/sambox/mesh_test.go
+++ b/internal/sambox/mesh_test.go
@@ -84,7 +84,7 @@ func discoverHandler(t *testing.T, peerID string, seen *chan string) http.Handle
}
// clientOver speaks HTTP over an already-established connection, the way an
-// agent's HTTP client speaks over the connection SOCKS5 handed it.
+// agent's HTTP client speaks over the tunnel CONNECT handed it.
func clientOver(conn net.Conn) *http.Client {
return &http.Client{
Transport: &http.Transport{
@@ -138,8 +138,8 @@ func TestMeshServiceWithNoProviderIsUnreachable(t *testing.T) {
if !errors.Is(err, ErrHostUnreachable) {
t.Fatalf("DialDestination = %v, want ErrHostUnreachable", err)
}
- if code := replyCodeFor(err); code != replyHostUnreachable {
- t.Errorf("reply code = %#x, want %#x", code, replyHostUnreachable)
+ if status, _ := refusalFor(err); status != http.StatusBadGateway {
+ t.Errorf("refusal status = %d, want %d", status, http.StatusBadGateway)
}
}
diff --git a/internal/sambox/route.go b/internal/sambox/route.go
index 452aa725..82087dcb 100644
--- a/internal/sambox/route.go
+++ b/internal/sambox/route.go
@@ -139,6 +139,14 @@ type Router struct {
// sandbox, "not permitted" and "does not exist" must look the same, or the
// boundary becomes a discovery oracle for the mesh's contents.
func (r *Router) Route(dst Destination) (Route, error) {
+ if api.IsMeshEntrypointHost(dst.Name) || api.IsMeshHost(dst.Name) {
+ // Mesh services are HTTP surfaces; a datagram session to one names
+ // nothing that exists, and is denied like any other non-service.
+ if dst.network() == "udp" {
+ return Route{}, fmt.Errorf("%w: %s is not reachable over UDP", ErrNotAllowed, dst.Name)
+ }
+ }
+
if api.IsMeshEntrypointHost(dst.Name) {
return Route{Kind: RouteMeshEntrypoint, Destination: dst}, nil
}
diff --git a/internal/sambox/socks5.go b/internal/sambox/socks5.go
deleted file mode 100644
index 8fc863f3..00000000
--- a/internal/sambox/socks5.go
+++ /dev/null
@@ -1,398 +0,0 @@
-// Copyright 2026 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package sambox
-
-import (
- "context"
- "encoding/binary"
- "errors"
- "fmt"
- "io"
- "log"
- "net"
- "strconv"
- "sync"
- "time"
-)
-
-// SOCKS5 (RFC 1928) is the sandbox boundary protocol. It is chosen over HTTP
-// proxying for one property above all: a request carries the destination
-// *name*, so egress policy is decided on "api.github.com" rather than on an
-// address that says nothing about who is being talked to. It is also
-// protocol-agnostic, and its reply codes give a policy denial a first-class
-// representation that the guest kernel turns into a clean connection refusal.
-//
-// Only CONNECT is implemented. BIND is meaningless here, and UDP ASSOCIATE is
-// refused deliberately: leaving it out means the only way out of a sandbox is a
-// named TCP flow, which is also the only shape the policy engine can reason
-// about. Inbound traffic reaches an agent over its own reverse channel, not
-// over BIND.
-
-const (
- socks5Version = 0x05
- userAuthVersion = 0x01
-
- methodNoAuth = 0x00
- methodUserPass = 0x02
- methodNoAcceptable = 0xFF
-
- cmdConnect = 0x01
-
- atypIPv4 = 0x01
- atypDomain = 0x03
- atypIPv6 = 0x04
-)
-
-// SOCKS5 reply codes (RFC 1928 section 6).
-const (
- replySuccess = 0x00
- replyGeneralFailure = 0x01
- replyNotAllowed = 0x02
- replyHostUnreachable = 0x04
- replyConnectionRefused = 0x05
- replyCommandNotSupported = 0x07
- replyAddrTypeNotSupported = 0x08
-)
-
-// handshakeTimeout bounds the negotiation only. Once a flow is established it
-// may stream for as long as it likes, so no deadline survives into the proxy.
-const handshakeTimeout = 10 * time.Second
-
-// Errors a Dialer returns to select a SOCKS5 reply code. Anything else becomes
-// a general failure, which is the right default: an unrecognised failure must
-// not be reported to a sandbox as a precise diagnostic.
-var (
- // ErrNotAllowed is a policy denial: the destination is not permitted.
- ErrNotAllowed = errors.New("connection not allowed by ruleset")
-
- // ErrHostUnreachable means the destination could not be resolved or routed.
- ErrHostUnreachable = errors.New("host unreachable")
-
- // ErrConnectionRefused means the destination actively refused the flow.
- ErrConnectionRefused = errors.New("connection refused")
-)
-
-// Destination is a requested target exactly as it arrived on the sandbox
-// boundary. Name is a domain when the client sent one, which is the case for
-// every flow that came through tun2socks with virtual DNS; a literal address
-// arrives when the sandbox dialled an IP directly, and IsName says which.
-type Destination struct {
- Name string
- Port uint16
- IsName bool
-}
-
-// Address renders the destination as a dial target.
-func (d Destination) Address() string {
- return net.JoinHostPort(d.Name, strconv.Itoa(int(d.Port)))
-}
-
-func (d Destination) String() string { return d.Address() }
-
-// Credentials are the RFC 1929 username and password. When one sam-box
-// multiplexes several agents over a single socket, this is how a flow says
-// which agent it belongs to; the password is never logged.
-type Credentials struct {
- Username string
- Password string
-}
-
-// Dialer decides whether a requested destination may be reached and opens it.
-// It is the single policy enforcement point on the sandbox boundary.
-type Dialer interface {
- DialDestination(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error)
-}
-
-// DialerFunc adapts a function to Dialer.
-type DialerFunc func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error)
-
-func (f DialerFunc) DialDestination(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- return f(ctx, creds, dst)
-}
-
-// SOCKS5Server serves the sandbox-facing side of the boundary.
-type SOCKS5Server struct {
- // Dialer is required.
- Dialer Dialer
-
- // Authenticate, when set, makes RFC 1929 username/password the only
- // acceptable method: a client that offers no credentials is rejected rather
- // than silently downgraded to an anonymous flow.
- Authenticate func(Credentials) error
-}
-
-// Serve accepts connections until the listener fails or ctx is cancelled.
-func (s *SOCKS5Server) Serve(ctx context.Context, l net.Listener) error {
- if s.Dialer == nil {
- return errors.New("sambox: SOCKS5Server requires a Dialer")
- }
-
- go func() {
- <-ctx.Done()
- _ = l.Close()
- }()
-
- var wg sync.WaitGroup
- defer wg.Wait()
-
- for {
- conn, err := l.Accept()
- if err != nil {
- if ctx.Err() != nil || errors.Is(err, net.ErrClosed) {
- return nil
- }
- return err
- }
- wg.Add(1)
- go func() {
- defer wg.Done()
- // Cancelling must drop flows, not wait them out: an established
- // relay only ends when one side closes, so an idle keep-alive
- // connection would otherwise hold shutdown open until some other
- // timeout fires.
- stop := context.AfterFunc(ctx, func() { _ = conn.Close() })
- defer stop()
- s.handle(ctx, conn)
- }()
- }
-}
-
-func (s *SOCKS5Server) handle(ctx context.Context, conn net.Conn) {
- defer func() { _ = conn.Close() }()
-
- if err := conn.SetDeadline(time.Now().Add(handshakeTimeout)); err != nil {
- return
- }
-
- creds, err := s.negotiate(conn)
- if err != nil {
- return
- }
-
- dst, err := readRequest(conn)
- if err != nil {
- var rerr *replyError
- if errors.As(err, &rerr) {
- _ = writeReply(conn, rerr.code)
- }
- return
- }
-
- // Negotiation is over. Dialling a mesh destination can involve discovery, so
- // it must not inherit the handshake deadline; bounding it is the Dialer's
- // job, through the context it is given.
- if err := conn.SetDeadline(time.Time{}); err != nil {
- return
- }
-
- upstream, err := s.Dialer.DialDestination(ctx, creds, dst)
- if err != nil {
- _ = writeReply(conn, replyCodeFor(err))
- return
- }
- defer func() { _ = upstream.Close() }()
-
- if err := writeReply(conn, replySuccess); err != nil {
- return
- }
-
- relay(conn, upstream)
-}
-
-// negotiate performs method selection and, when required, RFC 1929 auth.
-func (s *SOCKS5Server) negotiate(conn net.Conn) (*Credentials, error) {
- header := make([]byte, 2)
- if _, err := io.ReadFull(conn, header); err != nil {
- return nil, err
- }
- if header[0] != socks5Version {
- return nil, fmt.Errorf("unsupported SOCKS version %d", header[0])
- }
-
- methods := make([]byte, int(header[1]))
- if _, err := io.ReadFull(conn, methods); err != nil {
- return nil, err
- }
-
- want := byte(methodNoAuth)
- if s.Authenticate != nil {
- want = methodUserPass
- }
- if !containsByte(methods, want) {
- _, _ = conn.Write([]byte{socks5Version, methodNoAcceptable})
- return nil, fmt.Errorf("client offered no acceptable authentication method")
- }
- if _, err := conn.Write([]byte{socks5Version, want}); err != nil {
- return nil, err
- }
- if s.Authenticate == nil {
- return nil, nil
- }
-
- creds, err := readUserPass(conn)
- if err != nil {
- return nil, err
- }
- if err := s.Authenticate(*creds); err != nil {
- _, _ = conn.Write([]byte{userAuthVersion, 0x01})
- log.Printf("sambox: SOCKS5 authentication rejected for user %q", creds.Username)
- return nil, err
- }
- if _, err := conn.Write([]byte{userAuthVersion, 0x00}); err != nil {
- return nil, err
- }
- return creds, nil
-}
-
-func readUserPass(conn net.Conn) (*Credentials, error) {
- header := make([]byte, 2)
- if _, err := io.ReadFull(conn, header); err != nil {
- return nil, err
- }
- if header[0] != userAuthVersion {
- return nil, fmt.Errorf("unsupported username/password auth version %d", header[0])
- }
-
- username := make([]byte, int(header[1]))
- if _, err := io.ReadFull(conn, username); err != nil {
- return nil, err
- }
-
- plen := make([]byte, 1)
- if _, err := io.ReadFull(conn, plen); err != nil {
- return nil, err
- }
- password := make([]byte, int(plen[0]))
- if _, err := io.ReadFull(conn, password); err != nil {
- return nil, err
- }
-
- return &Credentials{Username: string(username), Password: string(password)}, nil
-}
-
-// replyError carries the SOCKS5 code a malformed or unsupported request must be
-// answered with.
-type replyError struct {
- code byte
- err error
-}
-
-func (e *replyError) Error() string { return e.err.Error() }
-
-func readRequest(conn net.Conn) (Destination, error) {
- header := make([]byte, 4)
- if _, err := io.ReadFull(conn, header); err != nil {
- return Destination{}, err
- }
- if header[0] != socks5Version {
- return Destination{}, fmt.Errorf("unsupported SOCKS version %d", header[0])
- }
- if header[1] != cmdConnect {
- return Destination{}, &replyError{replyCommandNotSupported, fmt.Errorf("unsupported command %d", header[1])}
- }
-
- var dst Destination
- switch header[3] {
- case atypDomain:
- length := make([]byte, 1)
- if _, err := io.ReadFull(conn, length); err != nil {
- return Destination{}, err
- }
- if length[0] == 0 {
- return Destination{}, &replyError{replyGeneralFailure, errors.New("empty domain name")}
- }
- name := make([]byte, int(length[0]))
- if _, err := io.ReadFull(conn, name); err != nil {
- return Destination{}, err
- }
- dst.Name = string(name)
- dst.IsName = true
- case atypIPv4, atypIPv6:
- size := net.IPv4len
- if header[3] == atypIPv6 {
- size = net.IPv6len
- }
- addr := make([]byte, size)
- if _, err := io.ReadFull(conn, addr); err != nil {
- return Destination{}, err
- }
- dst.Name = net.IP(addr).String()
- default:
- return Destination{}, &replyError{replyAddrTypeNotSupported, fmt.Errorf("unsupported address type %d", header[3])}
- }
-
- port := make([]byte, 2)
- if _, err := io.ReadFull(conn, port); err != nil {
- return Destination{}, err
- }
- dst.Port = binary.BigEndian.Uint16(port)
-
- return dst, nil
-}
-
-// writeReply answers with a bound address of 0.0.0.0:0: the client has no use
-// for the real one, and it would leak the host's addressing into the sandbox.
-func writeReply(conn net.Conn, code byte) error {
- _, err := conn.Write([]byte{socks5Version, code, 0x00, atypIPv4, 0, 0, 0, 0, 0, 0})
- return err
-}
-
-func replyCodeFor(err error) byte {
- switch {
- case errors.Is(err, ErrNotAllowed):
- return replyNotAllowed
- case errors.Is(err, ErrHostUnreachable):
- return replyHostUnreachable
- case errors.Is(err, ErrConnectionRefused):
- return replyConnectionRefused
- default:
- return replyGeneralFailure
- }
-}
-
-func relay(client, upstream net.Conn) {
- var wg sync.WaitGroup
- wg.Add(2)
- go func() {
- defer wg.Done()
- _, _ = io.Copy(upstream, client)
- closeWrite(upstream)
- }()
- go func() {
- defer wg.Done()
- _, _ = io.Copy(client, upstream)
- closeWrite(client)
- }()
- wg.Wait()
-}
-
-// closeWrite propagates a half-close so a peer waiting on EOF is not left
-// hanging until a timeout.
-func closeWrite(conn net.Conn) {
- if cw, ok := conn.(interface{ CloseWrite() error }); ok {
- _ = cw.CloseWrite()
- return
- }
- _ = conn.Close()
-}
-
-func containsByte(haystack []byte, needle byte) bool {
- for _, b := range haystack {
- if b == needle {
- return true
- }
- }
- return false
-}
diff --git a/internal/sambox/socks5_test.go b/internal/sambox/socks5_test.go
deleted file mode 100644
index 96c3e482..00000000
--- a/internal/sambox/socks5_test.go
+++ /dev/null
@@ -1,435 +0,0 @@
-// Copyright 2026 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package sambox
-
-import (
- "context"
- "errors"
- "io"
- "net"
- "os"
- "path/filepath"
- "testing"
- "time"
-
- "golang.org/x/net/proxy"
-)
-
-// startSOCKS5 serves s on a Unix socket, the transport the sandbox boundary
-// actually uses, and returns its path.
-func startSOCKS5(t *testing.T, s *SOCKS5Server) string {
- t.Helper()
-
- // Not t.TempDir(): test names make paths long enough to hit the ~108 byte
- // sockaddr_un limit.
- dir, err := os.MkdirTemp("", "sambox")
- if err != nil {
- t.Fatalf("MkdirTemp: %v", err)
- }
- t.Cleanup(func() { _ = os.RemoveAll(dir) })
-
- path := filepath.Join(dir, "agent.sock")
- l, err := net.Listen("unix", path)
- if err != nil {
- t.Fatalf("listen: %v", err)
- }
-
- ctx, cancel := context.WithCancel(context.Background())
- done := make(chan struct{})
- go func() {
- defer close(done)
- if err := s.Serve(ctx, l); err != nil {
- t.Errorf("Serve: %v", err)
- }
- }()
- t.Cleanup(func() {
- cancel()
- <-done
- })
- return path
-}
-
-// startEcho returns the address of a server that echoes what it is sent.
-func startEcho(t *testing.T) string {
- t.Helper()
- l, err := net.Listen("tcp", "127.0.0.1:0")
- if err != nil {
- t.Fatalf("listen: %v", err)
- }
- t.Cleanup(func() { _ = l.Close() })
-
- go func() {
- for {
- conn, err := l.Accept()
- if err != nil {
- return
- }
- go func() {
- defer func() { _ = conn.Close() }()
- _, _ = io.Copy(conn, conn)
- }()
- }
- }()
- return l.Addr().String()
-}
-
-// dialRaw speaks the protocol by hand, for the cases a well-behaved client
-// library will never produce.
-func dialRaw(t *testing.T, path string) net.Conn {
- t.Helper()
- conn, err := net.Dial("unix", path)
- if err != nil {
- t.Fatalf("dial: %v", err)
- }
- t.Cleanup(func() { _ = conn.Close() })
- if err := conn.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
- t.Fatalf("SetDeadline: %v", err)
- }
- return conn
-}
-
-// greetNoAuth completes method selection and returns the connection ready for a
-// request.
-func greetNoAuth(t *testing.T, conn net.Conn) {
- t.Helper()
- if _, err := conn.Write([]byte{socks5Version, 1, methodNoAuth}); err != nil {
- t.Fatalf("write greeting: %v", err)
- }
- reply := make([]byte, 2)
- if _, err := io.ReadFull(conn, reply); err != nil {
- t.Fatalf("read method selection: %v", err)
- }
- if reply[0] != socks5Version || reply[1] != methodNoAuth {
- t.Fatalf("method selection = %v, want [5 0]", reply)
- }
-}
-
-func readReplyCode(t *testing.T, conn net.Conn) byte {
- t.Helper()
- reply := make([]byte, 10)
- if _, err := io.ReadFull(conn, reply); err != nil {
- t.Fatalf("read reply: %v", err)
- }
- if reply[0] != socks5Version {
- t.Fatalf("reply version = %d, want %d", reply[0], socks5Version)
- }
- return reply[1]
-}
-
-// TestConnectPreservesDestinationName is the property the whole boundary rests
-// on: policy must see the name the agent asked for, never a resolved address.
-func TestConnectPreservesDestinationName(t *testing.T) {
- echo := startEcho(t)
-
- seen := make(chan Destination, 1)
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- seen <- dst
- return net.Dial("tcp", echo)
- }),
- })
-
- dialer, err := proxy.SOCKS5("unix", path, nil, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- conn, err := dialer.Dial("tcp", "api.github.com:443")
- if err != nil {
- t.Fatalf("Dial: %v", err)
- }
- defer func() { _ = conn.Close() }()
-
- if _, err := conn.Write([]byte("ping")); err != nil {
- t.Fatalf("write: %v", err)
- }
- got := make([]byte, 4)
- if _, err := io.ReadFull(conn, got); err != nil {
- t.Fatalf("read: %v", err)
- }
- if string(got) != "ping" {
- t.Errorf("echo = %q, want %q", got, "ping")
- }
-
- dst := <-seen
- if !dst.IsName {
- t.Errorf("destination %+v was not reported as a name", dst)
- }
- if dst.Name != "api.github.com" || dst.Port != 443 {
- t.Errorf("destination = %s, want api.github.com:443", dst)
- }
-}
-
-func TestConnectDeniedByPolicy(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- return nil, ErrNotAllowed
- }),
- })
-
- conn := dialRaw(t, path)
- greetNoAuth(t, conn)
- writeConnectByName(t, conn, "evil.example", 80)
-
- if code := readReplyCode(t, conn); code != replyNotAllowed {
- t.Errorf("reply = %#x, want %#x (connection not allowed by ruleset)", code, replyNotAllowed)
- }
-}
-
-func TestUnsupportedCommandsAreRefused(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- t.Error("dialer must not be reached for an unsupported command")
- return nil, errors.New("unreachable")
- }),
- })
-
- // BIND and UDP ASSOCIATE. UDP is refused on purpose: the only way out of a
- // sandbox is a named TCP flow.
- for _, cmd := range []byte{0x02, 0x03} {
- conn := dialRaw(t, path)
- greetNoAuth(t, conn)
- if _, err := conn.Write([]byte{socks5Version, cmd, 0x00, atypIPv4, 127, 0, 0, 1, 0x00, 0x50}); err != nil {
- t.Fatalf("write request: %v", err)
- }
- if code := readReplyCode(t, conn); code != replyCommandNotSupported {
- t.Errorf("cmd %#x: reply = %#x, want %#x", cmd, code, replyCommandNotSupported)
- }
- }
-}
-
-func TestUnsupportedAddressTypeIsRefused(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- t.Error("dialer must not be reached for an unsupported address type")
- return nil, errors.New("unreachable")
- }),
- })
-
- conn := dialRaw(t, path)
- greetNoAuth(t, conn)
- if _, err := conn.Write([]byte{socks5Version, cmdConnect, 0x00, 0x02, 0x00, 0x50}); err != nil {
- t.Fatalf("write request: %v", err)
- }
- if code := readReplyCode(t, conn); code != replyAddrTypeNotSupported {
- t.Errorf("reply = %#x, want %#x", code, replyAddrTypeNotSupported)
- }
-}
-
-func TestConnectByIPLiteralIsNotReportedAsAName(t *testing.T) {
- echo := startEcho(t)
-
- seen := make(chan Destination, 1)
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- seen <- dst
- return net.Dial("tcp", echo)
- }),
- })
-
- conn := dialRaw(t, path)
- greetNoAuth(t, conn)
- if _, err := conn.Write([]byte{socks5Version, cmdConnect, 0x00, atypIPv4, 192, 0, 2, 10, 0x01, 0xBB}); err != nil {
- t.Fatalf("write request: %v", err)
- }
- if code := readReplyCode(t, conn); code != replySuccess {
- t.Fatalf("reply = %#x, want success", code)
- }
-
- dst := <-seen
- if dst.IsName {
- t.Errorf("destination %+v was reported as a name", dst)
- }
- if dst.Name != "192.0.2.10" || dst.Port != 443 {
- t.Errorf("destination = %s, want 192.0.2.10:443", dst)
- }
-}
-
-// TestAuthenticationIsNotDowngraded pins that a server expecting credentials
-// refuses an anonymous client instead of serving it unidentified.
-func TestAuthenticationIsNotDowngraded(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- t.Error("dialer must not be reached for an unauthenticated client")
- return nil, errors.New("unreachable")
- }),
- Authenticate: func(Credentials) error { return nil },
- })
-
- conn := dialRaw(t, path)
- if _, err := conn.Write([]byte{socks5Version, 1, methodNoAuth}); err != nil {
- t.Fatalf("write greeting: %v", err)
- }
- reply := make([]byte, 2)
- if _, err := io.ReadFull(conn, reply); err != nil {
- t.Fatalf("read method selection: %v", err)
- }
- if reply[1] != methodNoAcceptable {
- t.Errorf("method selection = %#x, want %#x (no acceptable methods)", reply[1], methodNoAcceptable)
- }
-}
-
-func TestAuthenticatedFlowCarriesCredentials(t *testing.T) {
- echo := startEcho(t)
-
- seen := make(chan *Credentials, 1)
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- seen <- creds
- return net.Dial("tcp", echo)
- }),
- Authenticate: func(c Credentials) error {
- if c.Username != "reviewer-7.prod.acme.example" {
- return errors.New("unknown agent")
- }
- return nil
- },
- })
-
- auth := &proxy.Auth{User: "reviewer-7.prod.acme.example", Password: "admission-token"}
- dialer, err := proxy.SOCKS5("unix", path, auth, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- conn, err := dialer.Dial("tcp", "code-reviewer.mcp.sam.alt:80")
- if err != nil {
- t.Fatalf("Dial: %v", err)
- }
- defer func() { _ = conn.Close() }()
-
- creds := <-seen
- if creds == nil {
- t.Fatal("dialer received no credentials")
- }
- if creds.Username != "reviewer-7.prod.acme.example" || creds.Password != "admission-token" {
- t.Errorf("credentials = %+v, want the agent id and its admission token", creds)
- }
-}
-
-func TestRejectedCredentialsFailTheHandshake(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- t.Error("dialer must not be reached when authentication fails")
- return nil, errors.New("unreachable")
- }),
- Authenticate: func(Credentials) error { return errors.New("unknown agent") },
- })
-
- dialer, err := proxy.SOCKS5("unix", path, &proxy.Auth{User: "bar", Password: "nope"}, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- if _, err := dialer.Dial("tcp", "api.github.com:443"); err == nil {
- t.Fatal("Dial succeeded with rejected credentials, want an error")
- }
-}
-
-func TestNonSOCKS5GreetingIsDropped(t *testing.T) {
- path := startSOCKS5(t, &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- t.Error("dialer must not be reached for a non-SOCKS5 client")
- return nil, errors.New("unreachable")
- }),
- })
-
- conn := dialRaw(t, path)
- if _, err := conn.Write([]byte{0x04, 0x01}); err != nil {
- t.Fatalf("write greeting: %v", err)
- }
- if _, err := io.ReadFull(conn, make([]byte, 1)); !errors.Is(err, io.EOF) {
- t.Errorf("read after bad version = %v, want EOF", err)
- }
-}
-
-// TestServeDropsFlowsOnCancel pins that shutdown is prompt. An established
-// relay only ends when one side closes, so without this an idle keep-alive
-// connection holds the gateway open until some unrelated timeout fires.
-func TestServeDropsFlowsOnCancel(t *testing.T) {
- echo := startEcho(t)
-
- dir, err := os.MkdirTemp("", "sambox")
- if err != nil {
- t.Fatalf("MkdirTemp: %v", err)
- }
- t.Cleanup(func() { _ = os.RemoveAll(dir) })
- socket := filepath.Join(dir, "agent.sock")
-
- l, err := net.Listen("unix", socket)
- if err != nil {
- t.Fatalf("listen: %v", err)
- }
-
- server := &SOCKS5Server{
- Dialer: DialerFunc(func(ctx context.Context, creds *Credentials, dst Destination) (net.Conn, error) {
- return net.Dial("tcp", echo)
- }),
- }
-
- ctx, cancel := context.WithCancel(context.Background())
- served := make(chan error, 1)
- go func() { served <- server.Serve(ctx, l) }()
-
- dialer, err := proxy.SOCKS5("unix", socket, nil, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- conn, err := dialer.Dial("tcp", "api.github.com:443")
- if err != nil {
- t.Fatalf("Dial: %v", err)
- }
- defer func() { _ = conn.Close() }()
-
- // The flow is established and idle, which is the case that used to hang.
- cancel()
- select {
- case err := <-served:
- if err != nil {
- t.Fatalf("Serve: %v", err)
- }
- case <-time.After(10 * time.Second):
- t.Fatal("Serve did not return after cancel; an idle flow is holding shutdown open")
- }
-}
-
-func TestReplyCodeFor(t *testing.T) {
- tests := []struct {
- name string
- err error
- want byte
- }{
- {"policy denial", ErrNotAllowed, replyNotAllowed},
- {"unreachable", ErrHostUnreachable, replyHostUnreachable},
- {"refused", ErrConnectionRefused, replyConnectionRefused},
- {"wrapped denial", errors.Join(errors.New("context"), ErrNotAllowed), replyNotAllowed},
- {"anything else stays generic", errors.New("boom"), replyGeneralFailure},
- }
-
- for _, tc := range tests {
- t.Run(tc.name, func(t *testing.T) {
- if got := replyCodeFor(tc.err); got != tc.want {
- t.Errorf("replyCodeFor(%v) = %#x, want %#x", tc.err, got, tc.want)
- }
- })
- }
-}
-
-func writeConnectByName(t *testing.T, conn net.Conn, name string, port uint16) {
- t.Helper()
- req := []byte{socks5Version, cmdConnect, 0x00, atypDomain, byte(len(name))}
- req = append(req, name...)
- req = append(req, byte(port>>8), byte(port))
- if _, err := conn.Write(req); err != nil {
- t.Fatalf("write request: %v", err)
- }
-}
diff --git a/site/content/docs/agent-architecture.md b/site/content/docs/agent-architecture.md
index 1d7d181d..10e34f67 100644
--- a/site/content/docs/agent-architecture.md
+++ b/site/content/docs/agent-architecture.md
@@ -58,7 +58,7 @@ exactly one of them — one place where a flow is named, decided and opened.
## 3. The layering
-One socket, one protocol, one policy point. SOCKS5 is the waist.
+One socket, one protocol, one policy point. Named HTTP tunnels are the waist.
```text
┌─ sandbox (microVM, or container with network=none) ───────────────┐
@@ -67,16 +67,17 @@ One socket, one protocol, one policy point. SOCKS5 is the waist.
│ │ IP │
│ tun0 ── default route, the only device besides lo │
│ │ │
-│ tun2socks ── IP flows → SOCKS5, destination kept as a NAME │
-│ │ (virtual-DNS / fake-IP, see Decision 2) │
+│ tun2connect ── IP flows → CONNECT (TCP) / connect-udp (UDP), │
+│ │ destination kept as a NAME │
+│ │ (virtual DNS, see Decision 2) │
└────────┼──────────────────────────────────────────────────────────┘
- │ one byte stream
+ │ one byte stream per flow
│ microVM : AF_VSOCK → firecracker → host UDS <uds>_<port>
│ container: bind-mounted UDS
┌────────┼──────────────────────────────────────────────────────────┐
│ host ▼ │
│ sam-box (one per sandbox, NO libp2p host, NO enrollment) │
-│ = SOCKS5 server = THE policy enforcement point │
+│ = CONNECT server = THE policy enforcement point │
│ │ │
│ ├── mesh.sam.alt ── /v1 + /mcp only ─────┐ │
│ ├── <svc>.<type>.sam.alt ── HTTP: discover, then ┤ │
@@ -93,20 +94,43 @@ One socket, one protocol, one policy point. SOCKS5 is the waist.
mesh
```
-### Decision 1 — SOCKS5, not HTTP CONNECT, is the sandbox boundary protocol
-
-SOCKS5 is chosen for three properties HTTP proxying does not have:
-
-* **It carries the destination name.** `ATYP=0x03` is a domain name. The gateway
- authorizes `api.github.com`, not `140.82.121.5`. Domain filtering therefore
- needs no DNS interception, no MITM, and no IP allowlists that rot.
-* **It is protocol-agnostic.** TCP is TCP. `git`, Postgres, gRPC and a raw socket
- are all first-class; HTTP becomes a payload rather than a requirement.
-* **It has a refusal vocabulary.** Reply `0x02 connection not allowed by
- ruleset` is a policy denial the guest kernel turns into a clean
- `ECONNREFUSED` — exactly what an agent should observe when it reaches for
- something it may not have. UDP (`UDP ASSOCIATE`) is specified but stays **out
- of scope** for v1: deny it, so the only way out is a named TCP flow.
+### Decision 1 — named HTTP tunnels are the sandbox boundary protocol
+
+The boundary speaks authority-form `CONNECT` (RFC 9110) for TCP and
+connect-udp (RFC 9298, capsules per RFC 9297) for UDP. An earlier revision of
+this document chose SOCKS5 over HTTP proxying, for three properties; the
+reversal is worth being explicit about, because all three properties are kept
+and the reasons the comparison once favoured SOCKS5 stopped being true:
+
+* **It carries the destination name.** `CONNECT api.github.com:443` is
+ authority-form: the gateway authorizes `api.github.com`, not
+ `140.82.121.5`. Domain filtering still needs no DNS interception, no MITM
+ and no IP allowlists that rot. connect-udp carries the name the same way,
+ in the URI template `/.well-known/masque/udp/{host}/{port}/`.
+* **It is protocol-agnostic.** After the `200 OK` the tunnel is a byte pipe.
+ `git`, Postgres, gRPC and a raw socket are all first-class; HTTP is the
+ *handshake*, not a requirement on the payload.
+* **It has a refusal vocabulary.** A policy denial is `403` with a
+ `Boundary-Reason` header, which tun2connect turns into a clean
+ `ECONNREFUSED` in the guest — exactly what an agent should observe when it
+ reaches for something it may not have — while an operator reading a log
+ sees the reason in words.
+
+What SOCKS5 could not offer, and what decided the reversal:
+
+* **One protocol in both directions.** The reverse channel into a sandbox
+ (§9.2) always spoke `CONNECT <port>`; now egress and ingress are the same
+ shape, and there is one grammar to reason about on the whole boundary.
+* **Headers are the extension point.** Sandbox identity for multiplexing
+ rides in `Proxy-Authorization` (§8.5), and anything else — tracing, a
+ sandbox id — is a header away. SOCKS5 had a fixed binary vocabulary and
+ nowhere to put any of that.
+* **UDP fits.** `UDP ASSOCIATE` presumes a datagram socket beside the TCP
+ one, which never fit a boundary that is a single Unix socket. connect-udp
+ frames datagrams as capsules *on the same stream*, so UDP arrives named,
+ policy-checked and audit-delimited like every TCP flow (§11).
+* **It is curl-testable.** `curl --proxy` speaks the TCP half natively, which
+ makes the boundary probeable with a tool every operator already has.
HTTP MITM does not disappear; it moves *above* the waist. When a domain is
configured for secret injection, the gateway terminates TLS for that flow with
@@ -116,10 +140,15 @@ the status quo, where every flow is MITM'd.
### Decision 2 — names are resolved on the host, never in the guest
-`tun2socks` runs with a virtual-DNS pool (fake IPs out of `198.18.0.0/15`). The
-guest resolver gets a synthetic address, `tun2socks` maps that address back to
-the FQDN when the flow opens, and the gateway receives the FQDN in the SOCKS5
-request. Nothing in the guest ever performs a real DNS lookup, so:
+tun2connect answers guest DNS from synthetic pools it invents — IPv4 out of
+`100.64.0.0/10` (CGNAT space: link-local would be leak-proof, but SSRF guards
+in HTTP clients commonly block `169.254/16` and would break legitimate
+egress), IPv6 out of `100::/64` (the RFC 6666 discard prefix, so an escaped
+packet blackholes). The guest resolver gets a synthetic address, the engine
+maps it back to the FQDN when the flow opens, and the gateway receives the
+FQDN in the tunnel request. A flow whose destination was never resolved has
+no name and is refused in the guest. Nothing in the guest ever performs a
+real DNS lookup, so:
* `nano-init`'s DNS spoofer, `/etc/resolv.conf` rewrite, `HTTP_PROXY` injection
and `libinterceptor.so` bootstrap are **deleted**, not reimplemented;
@@ -135,8 +164,8 @@ become the same code path, and the difference is one line of sandbox setup:
| sandbox | guest side | host side |
|---|---|---|
-| Firecracker microVM | `tun2socks` → vsock CID 2, port *P* | listener on `<uds>_P` |
-| container, `network=none` | `tun2socks` → `/run/sam/agent.sock` | listener on the bind-mounted path |
+| Firecracker microVM | `tun2connect` → vsock CID 2, port *P* | listener on `<uds>_P` |
+| container, `network=none` | `tun2connect` → `/run/sam/agent.sock` | listener on the bind-mounted path |
This keeps AF_VSOCK out of the Go code entirely (no new dependency) and — more
importantly for the test pyramid — makes the whole datapath exercisable in a Go
@@ -223,18 +252,18 @@ discovery and the sidecar API (`/mcp`, `/v1/*`, `/sam/service/*`,
`/sam/<peer>/…`) over TCP and its Unix socket.
**`sam-box` — the sandbox dataplane.** One per sandbox. It holds **no libp2p
-host, no enrollment, no mesh identity**. It serves SOCKS5 on the sandbox-facing
-socket, enforces the egress policy, does MITM/secret injection where configured,
-and reaches the mesh solely by dialling the local `sam-node` sidecar Unix socket
-as a client.
+host, no enrollment, no mesh identity**. It serves the named-tunnel boundary
+(CONNECT, connect-udp) on the sandbox-facing socket, enforces the egress
+policy, does MITM/secret injection where configured, and reaches the mesh
+solely by dialling the local `sam-node` sidecar Unix socket as a client.
What this buys:
* *N* sandboxes per host still share **one** libp2p host, so no *N*× DHT
clients, identify/ping loops or router connections — the thing that would
otherwise cap density in the scale experiment.
-* `sam-box` becomes small and boring: a SOCKS5 server plus an HTTP client. No
- `join`, no OIDC, no Biscuit handling, no bbolt store. Most of
+* `sam-box` becomes small and boring: an HTTP CONNECT server plus an HTTP
+ client. No `join`, no OIDC, no Biscuit handling, no bbolt store. Most of
[cmd/sam-box/main.go](cmd/sam-box/main.go) is deleted.
* The blast radius of a compromised sandbox stops at its `sam-box`, which holds
one agent credential and can be killed and reissued in isolation.
@@ -246,7 +275,7 @@ identity (Decision 5, §8). Losing the libp2p host costs it nothing here — the
agent's authority never came from the host in the first place.
`internal/sambox` keeps the ephemeral CA and secret injection and gains the
-SOCKS5 server; `internal/node` keeps everything mesh.
+CONNECT server; `internal/node` keeps everything mesh.
## 5. Contracts
@@ -267,8 +296,8 @@ its mesh name directly: `http://code-reviewer.mcp.sam.alt/`.
### 5.2 Gateway dispatch
-Applied to the SOCKS5 request's `(host, port)` — `host` is the name
-`tun2socks` preserved, never an IP — in order:
+Applied to the tunnel request's `(host, port)` — `host` is the name
+`tun2connect` preserved, never an IP — in order:
1. **`mesh.sam.alt`** (`api.IsMeshEntrypointHost`) → the gateway's own
agent-facing surface, served in process: `/v1/models`,
@@ -296,8 +325,8 @@ Applied to the SOCKS5 request's `(host, port)` — `host` is the name
new sidecar endpoint, no libp2p in `sam-box`.
3. **anything else** → egress policy (§5.3). Allowed flows are dialled directly;
flows on a secret-injection domain are terminated with the ephemeral CA.
-4. **no match, or a name in the zone that resolves to nothing** → SOCKS5 reply
- `0x02`.
+4. **no match, or a name in the zone that resolves to nothing** → `403` with
+ `Boundary-Reason: not allowed by policy`.
Case 2 is the only one that inspects payload, and only because provider
selection is an HTTP-level decision. `https://` to a mesh name therefore needs
@@ -383,7 +412,8 @@ quietly lose the boundary.
Coverage is pushed as far down the pyramid as it will go. Firecracker appears
exactly once, at the top.
-**Unit (`internal/…`, `api/`).** SOCKS5 request/reply codec; the name↔URI
+**Unit (`internal/…`, `api/`).** CONNECT and connect-udp request parsing, the
+refusal-status mapping and the RFC 9297 capsule codec; the name↔URI
projection (`api/names_test.go`, already landed); dispatch classification
(`mesh.sam.alt` / mesh name / public / denied); the agent-facing path allowlist;
wildcard matching in the egress allowlist; SNI-vs-authorized-name mismatch.
@@ -397,20 +427,20 @@ containers:
`openai_facade_test.go`;
* node B registers a fake MCP service — reuse `newFakeMCPHandler`;
* node C runs with a sidecar Unix socket, and a `sam-box` beside it serves
- SOCKS5 on a second socket in `t.TempDir()`;
-* the test drives a real SOCKS5 client (`golang.org/x/net/proxy`, already a
- direct dependency) over that socket and asserts:
+ the boundary on a second socket in `t.TempDir()`;
+* the test opens real CONNECT tunnels over that socket (stdlib `net/http`, the
+ same wire shape tun2connect produces) and asserts:
1. `mesh.sam.alt:80` → `/v1/chat/completions` reaches A's fake LLM across the mesh,
2. `mesh.sam.alt:80` → `/mcp` `call_remote_tool` reaches B's fake MCP,
3. `<svc>.mcp.sam.alt:80` resolves through discovery to B and reaches it,
4. an allowlisted public name reaches a local `httptest` server,
- 5. a non-allowlisted name is refused with SOCKS5 `0x02`,
+ 5. a non-allowlisted name is refused with `403`,
6. no path outside `/v1/*` and `/mcp` reaches node C at all.
**E2E (`tests/e2e/*.bats`).** Two CUJs, no more:
* *Container sandbox*: `docker run --network none` with the real harness plus
- `tun2socks`, a bind-mounted UDS to a host `sam-node`, against the existing bats
+ `nano-init`, a bind-mounted UDS to a host `sam-node`, against the existing bats
mesh (`lib/container_mesh.bash`). Asserts a real inference call, a real tool
call, and one blocked domain.
* *microVM sandbox*: the same rootfs under Firecracker, `skip` unless `/dev/kvm`
@@ -421,27 +451,38 @@ containers:
Nothing on the host requires a `go.mod` change:
-* SOCKS5 **server** — a few hundred lines against the stdlib; we implement only
- `CONNECT` with `NO AUTH` (RFC 1928) on a Unix socket.
-* SOCKS5 **client** (tests) — `golang.org/x/net/proxy`, already a direct dep.
+* CONNECT / connect-udp **server** — a few hundred lines against the stdlib,
+ including the RFC 9297 capsule codec, on a Unix socket.
+* CONNECT **client** (tests, `sam-bench`) — stdlib `net/http` request writing.
* AF_VSOCK — never touched by Go code (Decision 3).
* MITM CA and secret injection — `internal/sambox`, already ours.
* Mesh name projection — `api/names.go`, stdlib only.
-### 7.1 The guest-side tun2socks
+### 7.1 The guest-side datapath: tun2connect
The guest side is Go, in `cmd/nano-init`, which is **its own module**
-(`github.com/google/sam/cmd/nano-init`). It uses
-`github.com/xjasonlyu/tun2socks/v2` for the userspace TCP/IP stack and
-`github.com/vishvananda/netlink` to build `tun0`, so the root `go.mod` is
-untouched and the host binaries carry none of it.
+(`github.com/google/sam/cmd/nano-init`). Its datapath is the
+[`tun2connect`](https://github.com/aojea/agents.net) library — gVisor's
+netstack terminating the sandbox's TCP/IP in userspace, a `BoundaryClient`
+speaking CONNECT and connect-udp, and a `VirtualDNS` preserving names — plus
+`github.com/vishvananda/netlink` to build `tun0`. All of it lives in the
+nano-init module, so the root `go.mod` is untouched and the host binaries
+carry none of it.
+
+Consuming the datapath as a library, rather than shipping a universal guest
+binary, is a deliberate split: the engine, the tunnel client and the name
+preservation are universal and live upstream with their own tests; what stays
+in `nano-init` is exactly what is SAM- and platform-specific — the vsock
+boundary for microVMs, `--create-namespaces` for pods, the `copy` mode for
+image builds, and PID 1 duty.
Owning the guest datapath is what makes the rest of this design possible:
-* the destination stays a **name** all the way to the SOCKS5 request. A stack
+* the destination stays a **name** all the way to the tunnel request. A stack
that proxies by address has already thrown away the thing policy reasons
- about, so `nano-init` runs its own resolver, hands out placeholder addresses
- from `169.254.64.0/18`, and restores the name when it opens the flow;
+ about, so the virtual DNS hands out synthetic addresses from
+ `100.64.0.0/10` and `100::/64` and the engine restores the name when it
+ opens the flow — and refuses a flow that never had one;
* policy and telemetry decisions can be made *inside* the guest — per-process
attribution, for instance — which an external binary cannot be extended to do;
* it builds for whatever architectures the project builds for, with no
@@ -452,7 +493,7 @@ The module boundary is the point. A userspace network stack is a large
dependency, and keeping it in a separate module means it is a guest-image
concern rather than something every `sam-node` and `sam-box` build has to carry.
-The host is unaffected either way: the sandbox boundary is SOCKS5 over a byte
+The host is unaffected either way: the sandbox boundary is CONNECT over a byte
stream, so the guest implementation could be replaced without changing anything
on the host or rewriting any test above.
@@ -639,11 +680,11 @@ in-band afterwards:
1. **One socket per agent (default).** Identity is a property of the socket,
fixed when the sandbox is created: one vsock UDS per microVM, one bind-mounted
socket per container. Nothing in-band, nothing to spoof.
-2. **SOCKS5 username (multiplexing).** When one `sam-box` fronts many agents over
- one socket, the RFC 1929 username/password sub-negotiation carries the agent
- id and its admission token. It is standard, in-band, supported by every SOCKS
- client (`socks5://user:pass@host`), and it makes identity
- **per-connection** — which is exactly what a multiplexer needs.
+2. **Proxy-Authorization (multiplexing).** When one `sam-box` fronts many agents
+ over one socket, Basic credentials on the tunnel request carry the agent id
+ and its admission token. It is standard, in-band, supported by every HTTP
+ proxy client, and it makes identity **per-connection** — which is exactly
+ what a multiplexer needs.
### 8.6 The honest limit
@@ -680,7 +721,7 @@ blocks in `biscuit-go` to be attributable. It is a clean upgrade, not a rewrite.
* `internal/node` — **nothing** for authorization: appended blocks are already
verified and evaluated. Only the namespace-binding policy is new.
* `internal/sambox` — holds the bundle, attaches it per flow, per socket or per
- SOCKS5 connection; serves the §10 control socket and the §9 ingress endpoint.
+ tunnel connection; serves the §10 control socket and the §9 ingress endpoint.
* `cmd/nano-init` — owns the guest side of the ingress channel (§9.2).
* Sidecar — propagates the agent header on egress alongside `X-Sam-Biscuit`.
* Tests — the CUJ that demonstrates the selling point belongs at integration
@@ -846,8 +887,8 @@ So a sandbox has exactly two channels, one per direction:
| channel | direction | protocol | who listens |
|---|---|---|---|
-| egress | guest → host | SOCKS5 | host (`sam-box`) |
-| ingress | host → guest | one stream per request | guest (`nano-init`) |
+| egress | guest → host | named HTTP tunnels (CONNECT, connect-udp) | host (`sam-box`) |
+| ingress | host → guest | one stream per request (`CONNECT <port>`) | guest (`nano-init`) |
Firecracker's vsock is bidirectional, so host→guest needs no new transport: the
host connects to the firecracker UDS and writes `CONNECT <port>`, with the guest
@@ -944,9 +985,11 @@ becomes `agent:my-counter-1.demo.actors.resources.substrate.ate.dev`, and
Two things to settle **with** the Substrate side rather than assume:
* **Egress ownership.** `atenet` already supplies DNS, routing, proxy sidecars
- and CONNECT. The SOCKS5 boundary has to slot in as the sandbox's egress rather
- than compete with it. `sam-box` behind atenet's sidecar seam is the likely
- fit, but that is a conversation, not a decision to take unilaterally.
+ and CONNECT. The named-tunnel boundary has to slot in as the sandbox's egress
+ rather than compete with it — speaking CONNECT is what makes that a fit
+ rather than a translation. `sam-box` behind atenet's sidecar seam is the
+ likely arrangement, but that is a conversation, not a decision to take
+ unilaterally.
* **Ingress.** Substrate already routes inbound to actors by Host header. §9
must reuse that path rather than build a parallel one: a SAM ingress
declaration should end up as a Substrate route.
@@ -968,8 +1011,10 @@ Two things to settle **with** the Substrate side rather than assume:
## 11. Remaining smaller open items
-1. **UDP.** Denied in v1. If an agent ever needs QUIC or real DNS, it returns as
- `UDP ASSOCIATE` under the same name-based policy.
+1. **UDP — shipped.** Carried as connect-udp (RFC 9298) with capsules on the
+ same one-socket boundary, under the same name-based deny-by-default policy.
+ DNS never leaves the guest either way: port 53 is answered by the virtual
+ DNS, and everything else is a named, policy-checked session.
2. **Guest trust of the ephemeral CA.** Baked into the sandbox image at build
time, or re-introduce a bootstrap endpoint? v1 avoids the question by keeping
mesh names on `http://` (§5.2).
diff --git a/site/content/docs/integrations/vscode-copilot.md b/site/content/docs/integrations/vscode-copilot.md
index 06e926b4..02653a4e 100644
--- a/site/content/docs/integrations/vscode-copilot.md
+++ b/site/content/docs/integrations/vscode-copilot.md
@@ -372,7 +372,7 @@ for url in ["https://api.github.com/zen", "https://example.com"]:
```
```text
-[TCP] dial 169.254.64.2:443: boundary refused: not allowed by policy
+[TCP] dial 100.64.0.2:443: boundary refused: 403 Forbidden (not allowed by policy)
https://api.github.com/zen -> 200 b'Responsive is better than fast.'
https://example.com -> URLError: [Errno 104] Connection reset by peer
```
diff --git a/site/content/docs/user/running-agents.md b/site/content/docs/user/running-agents.md
index c440f562..6d8fd4a4 100644
--- a/site/content/docs/user/running-agents.md
+++ b/site/content/docs/user/running-agents.md
@@ -76,7 +76,8 @@ denial is information the agent should reason about, not an outage.
### The boundary is the only way out
The sandbox has no network interface, no DNS resolver and no route. It has a
-single Unix socket, on which `sam-box` speaks SOCKS5.
+single Unix socket, on which `sam-box` serves named HTTP tunnels: CONNECT for
+TCP, connect-udp for UDP.
Every connection the agent opens arrives there as a **name**, and the boundary
decides what it is:
@@ -146,7 +147,7 @@ flowchart LR
M(["the mesh<br/>models · tools · peers"])
- H -- "SOCKS5 over a unix socket" --> B
+ H -- "CONNECT over a unix socket" --> B
B -- "node API socket<br/>+ X-Sam-Agent" --> N
N <--> M
B -. "allowed names only" .-> E([internet])
@@ -216,10 +217,10 @@ worked because the container could route somewhere, it would be proving nothing.
Notice what is *not* passed: no API key, no mesh token, no endpoint, and **no
proxy variable**. `nano-init` runs as PID 1, builds one `tun0`, makes it the
-default route and terminates the sandbox's TCP itself, opening a SOCKS5 flow to
-the boundary per connection. The agent asks for `mesh.sam.alt` like any other
-host and its traffic leaves through the tun because there is nowhere else for
-it to go.
+default route and terminates the sandbox's TCP itself, opening a named CONNECT
+tunnel to the boundary per connection. The agent asks for `mesh.sam.alt` like
+any other host and its traffic leaves through the tun because there is nowhere
+else for it to go.
That distinction is worth dwelling on, because the obvious alternative is to set
`HTTP_PROXY` and be done. That is the wrong layering: an agent that has to
@@ -265,25 +266,30 @@ flowchart LR
```
The guest has no network device at all. `nano-init` presents a `tun0` that is
-the default route, terminates TCP on it, and opens a SOCKS5 flow to the
-boundary for each connection. The harness makes ordinary HTTP requests and needs
-no configuration, because from inside the VM there is nothing else it could be
-doing.
+the default route, terminates TCP on it, and opens a named CONNECT tunnel to
+the boundary for each connection. The harness makes ordinary HTTP requests
+and needs no configuration, because from inside the VM there is nothing else it
+could be doing.
The only difference from the container is how the boundary is named: a path when
it is bind-mounted in, `vsock://2:1080` when there is no shared filesystem.
Nothing else in the sandbox knows which kind it is.
Names are resolved by the boundary rather than in the guest, which is why the
-sandbox needs no resolver: `nano-init` answers with a placeholder address per
+sandbox needs no resolver: the virtual DNS answers with a synthetic address per
name and remembers the pairing, so `mesh.sam.alt` reaches the boundary as a
-name and the boundary chooses a provider for it.
-
-Every address inside the sandbox is link-local (`169.254.0.0/16`), which is
-what those addresses are for: RFC 3927 describes a single link with no router,
-and a tun to the boundary is exactly that. It also means nothing in the sandbox
-can be confused with a real destination — a sandbox numbered out of
-`10.0.0.0/8` will eventually be deployed somewhere that already uses it.
+name and the boundary chooses a provider for it. An address the guest never
+resolved stands for no name, and a flow to one is refused.
+
+Every address inside the sandbox is synthetic: IPv4 out of `100.64.0.0/10`
+(CGNAT space, RFC 6598) and IPv6 out of `100::/64` (the discard-only prefix,
+RFC 6666). Link-local would have been the leak-proof choice, but SSRF guards
+in HTTP clients commonly block `169.254/16` and would break legitimate egress;
+the discard prefix keeps the leak-proofing for IPv6, since a packet that ever
+escapes through a stray interface is blackholed by the first conforming
+router. Neither range can be confused with a real destination — a sandbox
+numbered out of `10.0.0.0/8` will eventually be deployed somewhere that
+already uses it.
One detail costs people an afternoon: Firecracker's vsock multiplexes guest
connections onto **`<uds_path>_<port>`** on the host. A guest connecting to CID
@@ -377,7 +383,7 @@ metadata:
name: sandbox-resolv
data:
resolv.conf: |
- nameserver 169.254.1.1
+ nameserver 100.127.255.253
```
Note what is **not** there: no `securityContext`, no added capabilities, no
@@ -420,13 +426,13 @@ and apply to every container in the pod. Measured on GKE, the per-container
mount gives you this:
```console
-[sandbox] nameserver 169.254.1.1
+[sandbox] nameserver 100.127.255.253
[node] search default.svc.cluster.local ... nameserver 34.118.224.10
[node] cluster DNS works
```
-With `dnsConfig`, `sam-node` would get `169.254.1.1` as well and could no longer
-resolve the control plane.
+With `dnsConfig`, `sam-node` would get `100.127.255.253` as well and could no
+longer resolve the control plane.
**If you do not supply one, it needs somewhere writable.** Without the mount
above, `nano-init` falls back to bind-mounting a private `resolv.conf` itself,
@@ -516,6 +522,6 @@ property of the deployment, not of how well the prompt was written.
## See also
-- [Agent architecture](../../agent-architecture/) — the design decisions and why the boundary is SOCKS5
+- [Agent architecture](../../agent-architecture/) — the design decisions and why the boundary is named HTTP tunnels
- [What an agent costs](../../scale-report/) — measured memory, startup and enforcement overhead
- [Secure gateway](../secure-gateway/) — the gateway's configuration surface
diff --git a/site/content/docs/user/secure-gateway.md b/site/content/docs/user/secure-gateway.md
index 5bc5c18a..09370848 100644
--- a/site/content/docs/user/secure-gateway.md
+++ b/site/content/docs/user/secure-gateway.md
@@ -27,7 +27,7 @@ sequenceDiagram
participant Node as sam-node (mesh member)
participant Mesh as The mesh / the internet
- Agent->>Box: SOCKS5 CONNECT mesh.sam.alt:80
+ Agent->>Box: CONNECT mesh.sam.alt:80
Box->>Box: Classify by name, apply policy
Box->>Node: /v1/chat/completions over the node's API socket
Node->>Mesh: Route to a provider, authorized by the node's Biscuit
@@ -91,29 +91,31 @@ with 403 and never reaches the node.
A specific service can be addressed by its own name instead of letting policy
choose: `http://code-reviewer.mcp.sam.alt/`.
-Destinations that policy refuses fail the SOCKS5 handshake, which the sandbox's
-kernel turns into an ordinary connection refusal — so an agent sees "refused"
-rather than a hang.
+Destinations that policy refuses fail the CONNECT handshake with a 403 and a
+`Boundary-Reason` header, which the sandbox's own network stack turns into an
+ordinary connection refusal — so an agent sees "refused" rather than a hang,
+and an operator reading the log sees the reason in words.
---
## 4. Connecting a sandbox to the socket
-The sandbox has no network of its own. It runs `tun2socks` against a `tun`
-device and points it at the boundary socket, so every flow leaves as SOCKS5
-carrying the destination *name*:
+The sandbox has no network of its own. `nano-init` terminates its TCP/IP in
+userspace on a `tun` device and points every flow at the boundary socket as a
+named HTTP tunnel — CONNECT for TCP, connect-udp for UDP — carrying the
+destination *name*:
| sandbox | how it reaches the socket |
|---|---|
| Firecracker microVM | vsock; firecracker terminates it as `<uds_path>_<port>` on the host |
| container with `network=none` | the socket is bind-mounted in |
-For a quick test without a sandbox, bridge a TCP port to the socket and use any
-SOCKS5 client:
+For a quick test without a sandbox, curl speaks the TCP half natively through
+any HTTP proxy client; bridge a TCP port to the socket first:
```bash
socat TCP-LISTEN:1080,fork,reuseaddr UNIX-CONNECT:/var/run/sam/agent.sock &
-curl --socks5-hostname 127.0.0.1:1080 http://mesh.sam.alt/v1/models
+curl --proxy http://127.0.0.1:1080 http://mesh.sam.alt/v1/models
```
---
diff --git a/site/static/install.sh b/site/static/install.sh
index 0e626719..8acf692d 100755
--- a/site/static/install.sh
+++ b/site/static/install.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-set -e
+set -euo pipefail
REPO="google/sam"
INSTALL_DIR="/usr/local/bin"
@@ -25,7 +25,9 @@ esac
# Get latest release version
echo "Fetching latest release information..."
LATEST_RELEASE_URL="https://api.github.com/repos/${REPO}/releases/latest"
-VERSION=$(curl -s $LATEST_RELEASE_URL | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
+# `|| true`: with pipefail, a grep that matches nothing would kill the script
+# here instead of reaching the friendly error below.
+VERSION=$(curl -s $LATEST_RELEASE_URL | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/' || true)
if [ -z "$VERSION" ]; then
echo "Error: Could not find the latest release."
@@ -40,12 +42,12 @@ DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${VERSION}/${TAR_NAME
# Create a temporary directory
TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
cd "$TMP_DIR"
echo "Downloading ${DOWNLOAD_URL}..."
if ! curl -sfL -o "${TAR_NAME}" "${DOWNLOAD_URL}"; then
echo "Error: Failed to download ${DOWNLOAD_URL}"
- rm -rf "$TMP_DIR"
exit 1
fi
@@ -53,11 +55,22 @@ echo "Extracting..."
tar -xzf "${TAR_NAME}"
echo "Installing to ${INSTALL_DIR} (may require sudo)..."
-# In some environments, sudo might not be available or required
+INSTALLED_BINS=()
+for b in sam-node sam-control-plane sam-router mcp-client sam-box sam-console nano-init; do
+ if [ -f "$b" ]; then
+ INSTALLED_BINS+=("$b")
+ fi
+done
+
+if [ ${#INSTALLED_BINS[@]} -eq 0 ]; then
+ echo "Error: No SAM binaries found in release archive."
+ exit 1
+fi
+
if [ -w "$INSTALL_DIR" ]; then
- mv sam-node sam-control-plane sam-router mcp-client "$INSTALL_DIR/" 2>/dev/null || true
+ mv "${INSTALLED_BINS[@]}" "$INSTALL_DIR/"
else
- sudo mv sam-node sam-control-plane sam-router mcp-client "$INSTALL_DIR/" 2>/dev/null || true
+ sudo mv "${INSTALLED_BINS[@]}" "$INSTALL_DIR/"
fi
# Cleanup
diff --git a/tests/e2e/canary_manifests.bats b/tests/e2e/canary_manifests.bats
index c7cb43f5..d9100138 100644
--- a/tests/e2e/canary_manifests.bats
+++ b/tests/e2e/canary_manifests.bats
@@ -111,7 +111,7 @@ unservable() {
local declared resolver
declared=$(grep -A2 'resolv.conf: |' .github/k8s/sam-box-canary-template.yaml \
| grep nameserver | awk '{print $2}')
- resolver=$(grep -oE 'tunIP[[:space:]]*=[[:space:]]*"[0-9.]+"' cmd/nano-init/main.go \
+ resolver=$(grep -oE 'resolverIP[[:space:]]*=[[:space:]]*"[0-9.]+"' cmd/nano-init/main.go \
| grep -oE '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+')
echo "# canary declares: ${declared}" >&3
diff --git a/tests/e2e/microvm_sandbox.bats b/tests/e2e/microvm_sandbox.bats
index 6926e720..4fbe55d8 100644
--- a/tests/e2e/microvm_sandbox.bats
+++ b/tests/e2e/microvm_sandbox.bats
@@ -121,12 +121,12 @@ fc_put() {
kill "${boundary_pid}" 2>/dev/null
- # A SOCKS5 greeting, which is what nano-init opens with. Anything else means
- # something arrived but it was not the boundary protocol.
- run head -c 1 "${FC_DIR}/arrived"
+ # A CONNECT request line, which is what nano-init opens with. Anything else
+ # means something arrived but it was not the boundary protocol.
+ run head -c 7 "${FC_DIR}/arrived"
[[ "$status" -eq 0 ]]
- printf '%s' "$output" | od -An -tu1 | grep -qE '\<5\>' || {
- echo "first byte was not a SOCKS5 version marker:"
+ [[ "$output" == "CONNECT" ]] || {
+ echo "the first bytes were not a CONNECT request line:"
od -An -tx1 -N16 "${FC_DIR}/arrived"
false
}
diff --git a/tests/integration/agent_ingress_test.go b/tests/integration/agent_ingress_test.go
index d3a916e9..bd5be0f5 100644
--- a/tests/integration/agent_ingress_test.go
+++ b/tests/integration/agent_ingress_test.go
@@ -135,7 +135,7 @@ func startBoundaryServing(t *testing.T, agentSocket, nodeSocket, agentID string,
t.Fatalf("ListenSandboxSocket: %v", err)
}
- server := &sambox.SOCKS5Server{
+ server := &sambox.ConnectServer{
Dialer: &sambox.AgentDialer{
Router: &sambox.Router{Egress: egress},
SidecarSocket: nodeSocket,
diff --git a/tests/integration/sambox_test.go b/tests/integration/sambox_test.go
index cf72b932..df9a6712 100644
--- a/tests/integration/sambox_test.go
+++ b/tests/integration/sambox_test.go
@@ -160,7 +160,7 @@ func TestSandboxReachesOnlyWhatPolicyAllows(t *testing.T) {
t.Fatalf("ListenSandboxSocket: %v", err)
}
- boundary := &sambox.SOCKS5Server{
+ boundary := &sambox.ConnectServer{
Dialer: &sambox.AgentDialer{
Router: &sambox.Router{Egress: egress},
SidecarSocket: sidecarSocket,
diff --git a/tests/integration/sandbox_boundary_test.go b/tests/integration/sandbox_boundary_test.go
index 70a73476..8ad453ec 100644
--- a/tests/integration/sandbox_boundary_test.go
+++ b/tests/integration/sandbox_boundary_test.go
@@ -15,10 +15,14 @@
package integration_test
import (
+ "bufio"
"context"
+ "errors"
"io"
+ "net"
"net/http"
"net/http/httptest"
+ "net/url"
"os"
"path/filepath"
"strings"
@@ -26,17 +30,16 @@ import (
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
- "golang.org/x/net/proxy"
"github.com/google/sam/api"
"github.com/google/sam/internal/sambox"
)
// TestSandboxBoundaryCUJ drives the sandbox boundary the way an agent does:
-// a SOCKS5 client on a Unix socket, no credential of any kind, addressing
-// everything by name. Node A provides the services, node B is the node the
-// gateway consumes, and the agent must reach the mesh through the gateway
-// while never reaching node B's own API.
+// an HTTP CONNECT client on a Unix socket, no credential of any kind,
+// addressing everything by name. Node A provides the services, node B is the
+// node the gateway consumes, and the agent must reach the mesh through the
+// gateway while never reaching node B's own API.
//
// One mesh is set up for the whole test: the cases are cheap, the mesh is not.
func TestSandboxBoundaryCUJ(t *testing.T) {
@@ -115,7 +118,7 @@ func TestSandboxBoundaryCUJ(t *testing.T) {
t.Run("requests", func(t *testing.T) {
tests := []struct {
name string
- // A refused destination fails the SOCKS5 handshake, so the request
+ // A refused destination fails the CONNECT handshake, so the request
// errors instead of returning a status.
wantRefused bool
method string
@@ -269,7 +272,7 @@ func startBoundaryWith(t *testing.T, agentSocket, nodeSocket, agentID string, eg
t.Fatalf("ListenSandboxSocket: %v", err)
}
- server := &sambox.SOCKS5Server{
+ server := &sambox.ConnectServer{
Dialer: &sambox.AgentDialer{
Router: &sambox.Router{Egress: egress},
SidecarSocket: nodeSocket,
@@ -292,24 +295,48 @@ func startBoundaryWith(t *testing.T, agentSocket, nodeSocket, agentID string, eg
}
// boundaryClient is an ordinary HTTP client that happens to reach the network
-// through the sandbox socket, which is exactly what an agent's client is.
+// through the sandbox socket, which is exactly what an agent's client is. Each
+// flow opens as an authority-form CONNECT naming its destination, the same
+// wire shape tun2connect produces from inside a sandbox.
func boundaryClient(t *testing.T, agentSocket string) *http.Client {
t.Helper()
- dialer, err := proxy.SOCKS5("unix", agentSocket, nil, proxy.Direct)
- if err != nil {
- t.Fatalf("proxy.SOCKS5: %v", err)
- }
- contextDialer, ok := dialer.(proxy.ContextDialer)
- if !ok {
- t.Fatal("SOCKS5 dialer does not implement ContextDialer")
+ dialContext := func(ctx context.Context, _, addr string) (net.Conn, error) {
+ conn, err := (&net.Dialer{}).DialContext(ctx, "unix", agentSocket)
+ if err != nil {
+ return nil, err
+ }
+ req := &http.Request{Method: http.MethodConnect, URL: &url.URL{Host: addr}, Host: addr, Header: make(http.Header)}
+ if err := req.Write(conn); err != nil {
+ _ = conn.Close()
+ return nil, err
+ }
+ br := bufio.NewReader(conn)
+ resp, err := http.ReadResponse(br, req)
+ if err != nil {
+ _ = conn.Close()
+ return nil, err
+ }
+ if resp.StatusCode != http.StatusOK {
+ _ = conn.Close()
+ return nil, errors.New("boundary refused " + addr + ": " + resp.Status)
+ }
+ return &connectConn{Conn: conn, br: br}, nil
}
return &http.Client{
- Transport: &http.Transport{DialContext: contextDialer.DialContext},
+ Transport: &http.Transport{DialContext: dialContext},
Timeout: 20 * time.Second,
}
}
+// connectConn keeps bytes the response reader buffered past the header.
+type connectConn struct {
+ net.Conn
+ br *bufio.Reader
+}
+
+func (c *connectConn) Read(p []byte) (int, error) { return c.br.Read(p) }
+
func connectMCPThroughBoundary(t *testing.T, ctx context.Context, client *http.Client) *mcp.ClientSession {
t.Helper()
diff --git a/tests/integration/sandbox_namespaces_test.go b/tests/integration/sandbox_namespaces_test.go
index 9b8279e5..50d396c1 100644
--- a/tests/integration/sandbox_namespaces_test.go
+++ b/tests/integration/sandbox_namespaces_test.go
@@ -100,7 +100,7 @@ func TestSandboxCreatesItsOwnNamespaces(t *testing.T) {
t.Fatalf("ListenSandboxSocket: %v", err)
}
- boundary := &sambox.SOCKS5Server{
+ boundary := &sambox.ConnectServer{
Dialer: &sambox.AgentDialer{
Router: &sambox.Router{Egress: egress},
DialContext: func(ctx context.Context, network, address string) (net.Conn, error) {
@@ -157,7 +157,7 @@ func TestSandboxCreatesItsOwnNamespaces(t *testing.T) {
if !strings.Contains(got, "links=lo,tun0") {
t.Errorf("the agent did not get a namespace of its own; it reported:\n%s", got)
}
- if !strings.Contains(got, "resolv=nameserver 169.254.1.1") {
+ if !strings.Contains(got, "resolv=nameserver 100.127.255.253") {
t.Errorf("the agent kept the outer resolv.conf, so a pod's DNS would have been repointed:\n%s", got)
}
diff --git a/tests/scale/load-fleet.sh b/tests/scale/load-fleet.sh
index c6c730fa..91cc70b7 100755
--- a/tests/scale/load-fleet.sh
+++ b/tests/scale/load-fleet.sh
@@ -27,10 +27,10 @@
# exercised the way it would be in practice. Pointing a single load generator at
# a single boundary would measure a socket, not a mesh.
#
-# Load is driven from the host into the boundary's SOCKS5 socket. That is the
-# same entry point the guest uses over vsock, but it skips the in-guest netstack
-# and the vsock hop, so these numbers bound the mesh datapath and not the
-# sandbox's own overhead.
+# Load is driven from the host into the boundary's Unix socket, one CONNECT
+# tunnel per flow. That is the same entry point the guest uses over vsock, but
+# it skips the in-guest netstack and the vsock hop, so these numbers bound the
+# mesh datapath and not the sandbox's own overhead.
#
# Usage:
# tests/scale/load-fleet.sh --agents 200 --requests 200 --out /var/log/load
diff --git a/tests/scale/run-density.sh b/tests/scale/run-density.sh
index 871638cb..c48a9f01 100755
--- a/tests/scale/run-density.sh
+++ b/tests/scale/run-density.sh
@@ -214,7 +214,7 @@ for step in ${STEPS//,/ }; do
#
# Twice, because reusing a connection and opening one are different
# questions. A kept-alive flow is admitted once and carries every request
- # after that for free; a new flow per request pays the SOCKS5 handshake and
+ # after that for free; a new flow per request pays the CONNECT handshake and
# the policy decision every time. Only the second measures what enforcement
# costs, and only the first describes how an agent normally behaves.
for condition in reused-flow new-flow-per-request; do