docker

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package docker implements the sandbox driver on the Docker CLI. It is the OSS default: self-hosted, own-team skills, and no infrastructure beyond a daemon that is already present. It is not sufficient isolation for untrusted code — containers share the host kernel — which is why sandbox.CheckPolicy refuses untrusted work here rather than this package deciding case by case.

The CLI is shelled out to rather than using the Docker SDK: the SDK adds a large dependency tree and an API-version negotiation problem, and every operation needed here is one command whose flags are worth reading in full.

Index

Constants

This section is empty.

Variables

View Source
var ErrDockerUnavailable = errors.New("docker: no usable docker binary")

ErrDockerUnavailable is returned when no usable docker binary was found.

View Source
var SweepMinAge = time.Minute

SweepMinAge is how long an orphaned whetstone-labeled container or network must have existed before Sweep will remove it. A var, not a const, solely so a test can shrink it — production code has no legitimate reason to change it.

The label alone cannot tell "an orphan left by a process that died" apart from "a network or proxy container another, currently-starting process is in the middle of creating": prepareAllowlist's own network-then-proxy sequence has a real window where the network exists with no endpoints yet, during which "docker network rm" would otherwise succeed against a concurrent process's not-yet-finished setup, and a freshly "docker run" container is trivially removable with "-f" regardless of who it belongs to. SweepMinAge is what keeps something that recent out of scope; anything that age or younger is left for a later Sweep call to pick up once it has actually gone stale. This is a secondary safety net, not the primary protection — see the pid check below for that.

Functions

func CreateArgv

func CreateArgv(rs sandbox.RunSpec, o Options, name, network string) ([]string, error)

CreateArgv assembles the "docker create" command line Run actually issues: every flag RunArgv would pass to "docker run", minus "--rm" — removal is always explicit (see Run), never left to a flag racing "docker wait" for the exit code it needs to read before the container is gone.

func NetworkArgv

func NetworkArgv(name string) []string

NetworkArgv creates the private network a run and its proxy share.

--internal is the enforcement mechanism, not a hardening extra: it removes the network's default route, so a container attached to it has no path off the host except through another container that is also attached to something else. The proxy environment variables a run receives are a convenience for a well-behaved client; this flag is what makes ignoring them futile.

func OwnerLabel

func OwnerLabel() string

OwnerLabel is the "key=value" docker label filter matching every container and network this process's Driver instances create — e.g. for "docker ps --filter label=<OwnerLabel()>". Exported so a caller (this package's own tests, notably) can scope a query to just this process's resources: two docker-tagged test binaries running concurrently against the same daemon get different values here, so counting by OwnerLabel() does not race the other binary's containers the way counting by a shared name prefix or the bare ownerLabelKey would.

func ProxyArgv

func ProxyArgv(network, name, baseTag string) []string

ProxyArgv starts the allowlist proxy on the internal network under the alias runs address it by, detached so prepareAllowlist can go on to configure it and give it egress. Its command blocks until the configuration described at prepareAllowlist has been delivered (by "docker cp", not by piping stdin into this command: a detached "docker run" discards anything piped to its own stdin, so the configuration is written into the container after it is already running rather than passed at startup).

The proxy runs as root with every capability dropped except SETUID/SETGID: tinyproxy's own rendered config (imagespec.ProxyConfig) drops the process from root to "nobody"/"nogroup" once it has bound its port, and that drop is a syscall that needs those two capabilities regardless of the starting UID. Every other capability a container gets by default is removed, so the one process whose entire job is to sit on the network boundary carries the minimum a working proxy needs and nothing more.

func RunArgv

func RunArgv(rs sandbox.RunSpec, o Options, name, network string) ([]string, error)

RunArgv assembles the full "docker run" command line — "docker create"'s argv (runArgs) with "run", "--rm" in front. Run itself no longer executes this; it is exported (and still fully tested by argv_test.go with no daemon) because it is the flags-only description of a run's security posture that a test can assert against, and CreateArgv (what Run actually issues) shares every flag runArgs builds.

Types

type Driver

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

Driver is the Docker sandbox driver.

func New

func New(o Options) (*Driver, error)

New resolves the docker binary and applies defaults.

func (*Driver) EnsureBase

func (d *Driver) EnsureBase(ctx context.Context, slim bool) error

EnsureBase builds the base image if its tag is absent. It is separate from Prepare because the base is shared across every skill and takes minutes, while a per-skill layer takes seconds.

func (*Driver) HardwareIsolated

func (d *Driver) HardwareIsolated() bool

HardwareIsolated reports false: runc shares the host kernel.

func (*Driver) Name

func (d *Driver) Name() string

Name identifies the driver in reports and diagnostics.

func (*Driver) Prepare

func (d *Driver) Prepare(ctx context.Context, e sandbox.EnvSpec) (sandbox.ImageRef, error)

Prepare builds the per-skill layer, or reuses it when its content-addressed tag already exists. The tag is the deps digest, so "already built" and "identical contents" are the same question.

func (*Driver) Run

Run executes one command. A non-zero exit is a result, not an error: a verifier that fails is the measurement. An error means the run could not be performed at all — including when ctx is cancelled out from under it.

This is "docker create" + "docker start -a" + "docker wait", not a single "docker run": "docker run" (and "docker start -a") report the container's own exit status as their *own* CLI process's exit status, in the same integer space docker itself uses to report that the client or daemon failed to do what was asked (125 for a CLI/daemon rejection, 126 "not executable", 127 "not found") — there is no way to tell "the verifier legitimately exited 127" apart from "docker couldn't find /verifier/test.sh because the mount failed" by inspecting that one number. "docker create" can only fail for a driver-side reason (bad image, bad mount, bad flag — no user command has run yet), and "docker wait" reports the container's exit code on its own channel, populated only once the container has actually run and exited: wait failing is always a driver problem, wait succeeding always means a container produced that number. "docker start -a"'s own process exit code is deliberately never read for this reason — it mirrors the same ambiguous number "docker run" would have — only its blocking-until-exit behavior (so rs.Stdout/rs.Stderr see the container's output) and its response to context cancellation are used.

The container is named and removed explicitly on the way out, from a single deferred cleanup registered once "docker create" has succeeded (the only point at which there is a container to remove). Relying on a --rm flag alone loses a container whose docker client was killed by the context — or races "docker wait" against the container's automatic removal — and sixty of those per eval is a full disk.

func (*Driver) Snapshot

Snapshot is a no-op. Docker has no checkpoint/restore path worth relying on, so a run rebuilds from the prepared layer, which is already cached.

func (*Driver) Sweep

func (d *Driver) Sweep(ctx context.Context)

Sweep removes containers and networks left behind by a run that never got to clean up after itself. docker.Driver.Run and prepareAllowlist only clean up under context cancellation — a process killed by something the context can't see (a SIGKILL, a host crash, or simply no signal handler installed at all, which whetstone did not have until this fix) leaves its run and proxy containers running and its private network in place. network.go's own comment names the consequence: a leaked network per run exhausts Docker's address pool inside one Deep tier. Nothing swept them before this.

Call it once per eval, before any run starts.

The invariant this guarantees: a live container or network belonging to another process is never removed. Every whetstone-created resource carries both ownerLabelKey (so Sweep never touches anything outside whetstone's own containers and networks) and pidLabelKey (the pid of the process that created it). Sweep only removes a labeled resource once both hold:

  1. pidAlive(that pid) is false — the creating process is confirmed gone, not merely old. This is what makes the guarantee a fact about the resource's owner rather than a guess from its age: a session that legitimately runs longer than SweepMinAge (any real agent session; the default SessionTimeout is twenty minutes) still has a live pid, so it is never touched, no matter how long it has been running or how many other whetstone processes are sweeping concurrently.
  2. the resource is older than SweepMinAge — a secondary guard against the narrow window (described above) where a resource has just been created and does not yet reflect its owner's final state, independent of pid liveness.

A resource with no parseable pid label (for instance one hand-labeled by a test, or one from a version of whetstone that predates the pid label) is treated as ownerless and falls back to the age check alone — the same behavior this function had before the pid check existed.

type Options

type Options struct {
	Binary    string
	BaseTag   string
	CPUs      string
	Memory    string
	PidsLimit int
	Logger    func(format string, args ...any)
}

Options configures the driver. The resource limits are per run: a 60-session tier at concurrency four must not be able to exhaust the host.

Jump to

Keyboard shortcuts

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