sockfilter

package
v0.7.42 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package sockfilter is the per-run filter between a run's MCP gateway and the docker daemon.

The gateway launches the tool and MCP server containers, so it needs the daemon's API; handed the daemon's own socket, a compromised gateway commands every container on the host, which is what would stop runs sharing a sandbox host. The filter serves a socket of its own in the run's directory, which the gateway mounts in place of the daemon's, and forwards a request only when it touches this run's objects in a way that stays inside the run:

  • every container, network and volume created through it carries the run's label, whatever the request said;
  • a request naming a container, network, volume or exec must name one carrying that label (the gateway's shared relay networks excepted, by name); lists and the event stream show only the run's objects;
  • a create body is decoded the way the daemon decodes it (field names in any case), refused if it holds a field the filter does not know, checked, and forwarded as the filter re-encoded it, so the daemon receives exactly what was checked (create.go);
  • a folder the run keeps from the gateway (a connection's token, the hosts' sign-ins, the browser's secrets, the share) is bound only by the container that needs it, whose image, command and every bind are the catalog entry's; nothing execs into or copies to or from a container that binds one, and no create carries a health check, which would run a command inside it (create.go);
  • the network that leaves the host takes only the gateway's relays, pinned by digest, and nothing may exec into or write to a relay;
  • the daemon's version, info and ping, image inspects and pulls by reference pass as they are (images are not a run's objects);
  • an object that does not exist gets the daemon's 404;
  • everything else is refused with 403.

Every decision is written to the log, so a run shows what its gateway was denied; the count of refusals is Refused.

Index

Constants

View Source
const SidecarReady = "docker-filter: ready"

SidecarReady is the line the docker-filter role prints once its socket accepts connections; the engine starts the gateway only after it.

View Source
const ToolsLabel = "agentry.tools"

ToolsLabel is the label the filter puts on the run's tools server alone, with the run's id: the runner relays the Coding agent's published ports into the container that carries it.

Variables

This section is empty.

Functions

func BrowserSeccomp

func BrowserSeccomp() (string, error)

BrowserSeccomp is the profile, compacted, as a create's SecurityOpt carries it ("seccomp=<json>").

func CountRefused

func CountRefused(log io.Reader) int

CountRefused counts the refusals in a filter's decision log (Filter. Refused, for a filter running in another process).

func MarshalConfig

func MarshalConfig(c Config) ([]byte, error)

MarshalConfig is a filter's configuration as the docker-filter role reads it: every field but Listen, Upstream and Log, which belong to the container it runs in.

func ServerReadCapabilities

func ServerReadCapabilities() []string

func ServerWriteCapabilities

func ServerWriteCapabilities() []string

func ToolsCapabilities

func ToolsCapabilities() []string

ToolsCapabilities, ServerReadCapabilities and ServerWriteCapabilities are what the filter gives back to each class, for the receipt to name.

Types

type Config

type Config struct {
	// RunID is the run whose objects the gateway may touch.
	RunID string
	// Label is the key every run object carries RunID under (the runner's
	// sweeps find the gateway's objects by it); OwnerLabel the key only
	// objects created through the filter carry, which is what makes one
	// the gateway's to touch. The runner's own containers (the agent, the
	// model proxy, the gateway itself) carry Label and not OwnerLabel, so
	// the gateway cannot exec into, stop or join them.
	Label      string
	OwnerLabel string
	// Listen is the socket the filter serves; created 0666 (the gateway is
	// root without DAC_OVERRIDE, and not the socket's owner). Its directory
	// is the run's own, so no other account reaches it.
	Listen string
	// Upstream is the daemon's socket.
	Upstream string
	// BindRoots are the host directories a bind source may sit under,
	// read-only; WritableRoots those it may also write (the gateway's own
	// two lists, MCP_GATEWAY_DOCKER_BIND_ALLOWED_PATHS and …_WRITABLE_PATHS).
	BindRoots     []string
	WritableRoots []string
	// ToolsWritableRoots are roots, among WritableRoots, that only the
	// run's tools server may bind writable, and ToolsOnlyRoots roots that
	// only it may bind at all: a persistent agent's share folder, which the
	// tools server writes and an MCP server the person let see it reads
	// (only beside the Coding agent; elsewhere a server sees its mirror).
	ToolsWritableRoots []string
	ToolsOnlyRoots     []string
	// OfflineRoots are roots any container but the run's tools server may
	// bind only when it joins no network: a persistent agent's share
	// folder and its mirror, which an MCP server the person let see the
	// share reads, so nothing that reaches a host is given them.
	OfflineRoots []string
	// HeldRoots are paths, at or beneath BindRoots, that only the
	// containers each names may bind: the folders and files of the run's
	// configuration that one server needs and no other may bind (a
	// connection's token, the target hosts' sign-ins, the browser's
	// secrets, the share's verdicts and the text read out of its
	// documents). A bind of a folder that holds one of them, or of a path
	// beneath one, is held as that path is; so are the roots of the three
	// lists above.
	HeldRoots []HeldRoot
	// HeldVolumes are named volumes not the run's that only the containers
	// By name may mount: a persistent built-in's image server's own volume,
	// Root its name. Each must exist.
	HeldVolumes []HeldRoot
	// SharedNetworks are the networks the runner made for the gateway to
	// use without the owner label: the run's relay networks. They must
	// carry Label=RunID; the gateway may not create or remove them.
	SharedNetworks []string
	// EgressNetworks are shared networks with a way out of the host, each
	// with the image digests (repository@sha256:…) that may join it: the
	// relays' leg out takes the relays and nothing else a gateway launches.
	EgressNetworks map[string][]string
	// NetworkNames maps a network name the gateway uses to the network
	// the daemon holds for this run: the pinned gateway's two fixed relay
	// networks become the run's own. The
	// name is translated on the way in (paths, create bodies, endpoints)
	// and back in what the gateway reads, so it never sees the run's
	// names and never reaches another run's relays.
	NetworkNames map[string]string
	// WebNetwork, when set, is the run's own network with a way out of the
	// host for the built-in Drafter's web tools: the
	// tools server has no network allowlist of its own there (its tools
	// hold their own address rule), and the gateway asks for the daemon's
	// default network for it, which the filter never gives. A container of
	// WebImage asking for the default network joins WebNetwork instead, and
	// no container of another image joins WebNetwork at all. It must carry
	// Label=RunID; the gateway may not create or remove it.
	WebNetwork string
	// WebCmd is the one command the web tools' server runs with (the
	// runner image's tools role and its spec), and WebSpec the host path of
	// the run's rendered tools spec it must be given read-only at
	// WebSpecTarget: a container on the web network runs the run's own
	// tools server and nothing else, as a relay is its image and nothing
	// else.
	WebCmd        []string
	WebSpec       string
	WebSpecTarget string
	// WebResolvConf, when set, is the host path of the run's own
	// resolv.conf naming the policy's resolvers: the
	// filter binds it read-only at /etc/resolv.conf in the web tools'
	// server, in place of docker's, whose embedded DNS a sandboxed runtime
	// does not reach. The gateway may not name a resolv.conf or DNS
	// settings of its own for that server.
	WebResolvConf string
	// RelayResolvConf, when set, is the host path of the run's own
	// resolv.conf for the relays: the filter binds it
	// read-only at /etc/resolv.conf in each relay and creates the relay
	// under Runtime, since a relay resolves its declared host by name and
	// a sandboxed runtime does not reach docker's embedded DNS.
	// Empty leaves the relays on the daemon's default and docker's DNS.
	// The gateway still names no file, DNS setting or runtime for a relay.
	RelayResolvConf string
	// WebImage is the tools server's image, by reference; the filter
	// resolves it to the image id the check compares, once, when a check
	// first needs it, and refuses the web network while it cannot.
	WebImage string
	// RelayHosts are what a relay may be pointed at: the run's declared
	// servers' egress entries and the agent's own egress hosts on 443,
	// each "host" (ports 443 and 80), "host:port",
	// "*.domain" or "*". Empty admits no relay.
	RelayHosts []string
	// ToolsImage and ToolsCmd name the run's tools server: the image it
	// runs in, by reference (resolved to its id when first needed, as
	// WebImage is), and the one command it runs with. ToolsTmpfs is what
	// the filter mounts into that container and no other, target to
	// options: its /tmp and scratch folder as size-capped tmpfs,
	// since the gateway's catalog cannot ask for
	// one. A tools server whose request names anything at or beneath one
	// of those targets is refused. Empty adds nothing.
	ToolsImage string
	ToolsCmd   []string
	ToolsTmpfs map[string]string
	// ToolsShared are the binds the tools server may have beneath one of
	// its tmpfs targets, target to host folder: the host link's copy folder
	// at /scratch/hosts, which the run made. The request
	// must name exactly that folder at exactly that target; anything else
	// at or beneath a tmpfs target is still refused.
	ToolsShared map[string]string
	// ToolsVolumes are the named volumes not the run's that the tools
	// server may mount, by exact name: a persistent agent's data volume,
	// which outlives every run and so carries no run label. No other
	// container may mount one.
	ToolsVolumes []string
	// AppLinkVolume is the run's app link relay volume, made by the CLI
	// where the daemon runs in a VM: the app link's container, the one of
	// AppLinkImage (by id) that runs AppLinkCmd, may mount it by its exact
	// name, and no other container. Empty admits none.
	AppLinkVolume string
	AppLinkImage  string
	AppLinkCmd    []string
	// DesktopVolume is the run's desktop link relay volume, made by the
	// CLI for a run that uses applications on the person's computer: a
	// desktop link entry, a container of DesktopImage (by id) that runs one
	// of DesktopCmds, may mount it by its exact name, and no other
	// container. Such a container is held to its class (desktoplink.go):
	// no network, the user DesktopUser, that volume as its one mount, a
	// read-only root. Empty admits none.
	DesktopVolume string
	DesktopImage  string
	DesktopCmds   [][]string
	DesktopUser   string
	// DesktopRuntime is the runtime a desktop link entry is created with
	// in place of Runtime: the policy's gatewayRuntime, a gVisor
	// registration with --host-uds=open, since the entry opens the relay's
	// socket in the run's volume, a host socket to a sandbox. Empty leaves
	// the entry on the daemon's default, whatever Runtime is.
	DesktopRuntime string
	// BrowserImage names the run's browser server: the
	// image a create must be of, by id (resolved when first needed, as
	// ToolsImage is), to be held as the browser class: every capability
	// dropped, a read-only root, BrowserTmpfs mounted, its user
	// BrowserUser, and, with no Runtime, the seccomp profile that lets
	// Chromium's own sandbox run (browser.go). Empty: no browser.
	BrowserImage string
	// BrowserUser is the user the browser server must run as, uid:gid,
	// which owns its tmpfs home; empty is the image's own (10001:10001).
	BrowserUser string
	// BrowserTmpfs is what the filter mounts into the browser server, target
	// to options without the owner, which BrowserUser decides: its home and
	// its /tmp, where Chromium keeps its shared memory.
	BrowserTmpfs map[string]string
	// BrowserNetwork is the run's network for the browser server and the one
	// relay it reaches the browse proxy through, alone: where the gateway names
	// BrowserNetworkFor (the run's internal relay network) for either, the
	// filter gives it this one, so a page that took the browser over
	// reaches no other server's relay; no other container may join it, and
	// the browser server may join nothing after it is made. BrowseProxy is
	// the proxy's host name, the relay's PROXY_HOSTNAME.
	BrowserNetwork    string
	BrowserNetworkFor string
	BrowseProxy       string
	// RelayPins are run-time hosts the filter writes into the /etc/hosts of
	// a relay pointed at one, host to IPv4 address: the run's browse proxy,
	// a container of its own whose name a relay under a sandboxed runtime,
	// on the host's name servers, could not resolve.
	RelayPins map[string]string
	// Limits bound every container created through the filter: a request
	// asking for more is refused, one asking for none gets these.
	Limits Limits
	// Runtime is the OCI runtime (the policy's docker.runtime) every
	// container the gateway creates runs under, the relays excepted unless
	// RelayResolvConf is set: a relay resolves its declared host by name,
	// and a sandboxed runtime does not reach docker's embedded DNS,
	// so it runs under Runtime only with the host's name servers. For the same
	// reason a container under it reaches what it links to through
	// /etc/hosts entries the filter pins. Empty leaves the daemon's
	// default. The gateway never chooses a runtime itself.
	Runtime string
	// Podman says the upstream is podman's Docker-compatible API, which
	// differs from Docker Engine's in three ways the filter follows: a
	// link (HostConfig.Links, an endpoint's) is refused there, so each
	// becomes the /etc/hosts entries the filter pins under a runtime and
	// is cleared from the body; a rootless container keeps the kernel's
	// unprivileged-port floor, so a relay, which binds 443 as a plain
	// user, is given the sysctl that lowers it to 0 (Docker Engine sets it
	// in every container); and a create body's runtime is dropped, so with
	// Runtime set the upstream is an API service of the run's own whose
	// default runtime is Runtime, and every container created through it,
	// the relays included, runs under it.
	Podman bool
	// SELinuxUnconfined creates every container that runs under Runtime
	// with its SELinux label disabled: on podman on an SELinux host, gVisor
	// refuses to start a labelled container. The runtime's own isolation
	// stands in for the label's.
	SELinuxUnconfined bool
	// Verify, when set, is called after the upstream creates a container
	// that must run under a runtime, with the container's id, its class in
	// the receipt's words and the runtime it must be under, before the
	// gateway sees the answer: it reads the runtime back from the engine
	// natively and returns why the two differ, which refuses the create
	// to the gateway and is kept as RuntimeMismatch. Nil reads the runtime
	// through the daemon's own inspect instead (the filter container,
	// which has no engine CLI; Docker Engine's inspect answers truly).
	Verify func(ctx context.Context, id, class, runtime string) error `json:"-"`
	// Log receives one line per request.
	Log io.Writer `json:"-"`
}

Config says whose objects the filter serves, where, and within what.

func UnmarshalConfig

func UnmarshalConfig(b []byte) (Config, error)

UnmarshalConfig reads MarshalConfig's form, refusing a field it does not know: a configuration from another version is not half-applied.

type Filter

type Filter struct {
	// contains filtered or unexported fields
}

Filter is a running filter.

func Start

func Start(cfg Config) (*Filter, error)

Start serves the filter on cfg.Listen.

func (*Filter) Close

func (f *Filter) Close() error

Close stops serving and removes the socket.

func (*Filter) Refused

func (f *Filter) Refused() int

Refused is how many requests the filter has refused; the log names them.

func (*Filter) RuntimeMismatch

func (f *Filter) RuntimeMismatch() error

RuntimeMismatch is the first container the engine created under another runtime than the one it was asked for, as Verify reported it, or nil. The gateway's create was refused; the run reads this to stop rather than carry on with a receipt that would name a sandbox a container did not have.

func (*Filter) ServeHTTP

func (f *Filter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP decides each request.

type HeldRoot

type HeldRoot struct {
	Root string
	By   []Holder
}

HeldRoot is a path only the containers By name may bind (Config.HeldRoots).

type Holder

type Holder struct {
	Image string
	Cmd   []string
	// Binds are everything the container is given: a create that holds one
	// more, one fewer, or one with another source or target is not the
	// holder, so its command runs the code its entry names with the files
	// its entry names, and no other. A source that is not an absolute path
	// is a named volume.
	Binds []HolderBind
}

Holder is one container of the run's: the one of Image (by reference, compared by id) that runs Cmd by the image's own entrypoint, with exactly the folders and volumes Binds names. An empty Cmd is the image's own command.

type HolderBind

type HolderBind struct {
	Source, Target string
}

HolderBind is one bind of a holder: a host folder or file, or a named volume, at a path in the container.

type Limits

type Limits struct {
	MemoryBytes int64
	NanoCPUs    int64
	Pids        int64
}

Limits are the resource ceilings for the containers a gateway creates. Zero leaves a resource unbounded.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL