Sandbox Contract
link-sandbox-contract: the sandbox's policy, independent of its
implementation. It reads a sandbox's spec, resolves its permissions,
and checks addresses and names on the network, with no parser,
backend or proxy, for every side that edits or enforces a policy.
Each command's arguments
Each lnk sandbox command's runtime arguments are a type here,
generated from actions.toml, with argv() writing the line that
gives them and from_argv() reading one back. The program parses its
command line into the same types, and the checks actions.toml names
(checks.rs) run on them. So the sandbox building its own proxy's line
(SandboxProxyArgs), and reading that line back to hand it its
secrets, uses the declaration, never a flag typed out.
The spec
Spec is a sandbox's spec, a TOML file whose sections are its only
grants (Sandbox Spec):
Files, Network (its NetworkMode), Internet, Lan, Localhost
(its Port), Tools, Browser and Commands, each with an Os
table. It's here, in its own contract, since more than the sandbox
module keeps one: an agent's file, a harness's grants.
What it leaves to others
What a spec opens on a machine is the confinement resolver's, and its
refusals that need the machine itself are the sandbox module's: another
module has a spec checked by running lnk sandbox.
Its parts
spec::grants is the grant algebra policy editors share (union),
spec::resolve the OS overrides and authored paths, and
spec::schema the schema and documentation made from the type
(Section), which lnk sandbox permission list
lists and lnk spec show sandbox --json prints.
Addresses and names on the network
net holds the address and name rules shared by the sandbox proxy and
other network callers. forbidden and this_machine identify addresses
refused by public-internet policy: private and loopback ranges, cloud
metadata and this machine's own addresses. Explicit LAN and localhost
grants use their own restricted connection paths; host-network mode
has separate limits. check_host, check_lan and check_endpoint
validate their respective name patterns. Upstream selects direct
connections, SOCKS or a local HTTP proxy.
The programs a sandbox may run
Programs is Only these, by path: a file, or a folder of them; none,
nothing. A spec always names them, toolchains expanded into their
programs and build folders. Any is Link's own, for lnk sandbox learn
and check's probes, never a spec's. Its
requirement_policy names the effective command policy, unrestricted
or restricted.
Folders every sandbox hides
hidden_dirs gives the folders every sandbox hides, whatever it's
allowed, but for what it names in them: ~/Link/Agents (agents_dir,
a folder per agent, hidden from every sandbox but an agent's own),
~/Link/Teams (teams_dir, hidden but for what a member is granted of
it) and ~/Link/Archive (archive_dir, what Link keeps a while of
what's gone).
A folder no sandbox may write
unsafe_files says why no sandbox may write a folder, when it mustn't:
where writing is a way out of a sandbox (programs and settings that run
or are read outside it) or holds the user's keys.
Variables a caller can't give
check_given_variable refuses a variable a caller can't give a
sandboxed program: those lnk sandbox run keeps or sets itself, the
dynamic loader's (LD_*, DYLD_*) and a proxy's. Startup hooks and
interpreter search paths are refused too: an environment grant must not
install code before the requested command starts.
What Linux shows of the machine
system::LINUX_READS is what Linux's sandbox shows a program of the
machine outside its own folders, read only, those that exist: the
system's programs and libraries, and selected public settings from
/etc. Anything kept in them, whatever its mode, a sandboxed program
running as its owner can read; /run, /tmp and the homes it gives
fresh.
A box's users
box_users is what the box module writes of a box's users (lnk box user) and every other side reads: where root keeps them, the line that
lets a key in, and the one way into a user's sandbox, for an SSH session
and a run alike.
Where root keeps them
In /etc/lnk/users/<name>/, where neither they nor anything they run
writes: user.toml (BoxUser, their folder and key), <name>.toml
(their sandbox's spec, its paths absolute) and authorized_keys, which
sshd reads for them in place of their own, for the group lnk-users
(GROUP).
The line that lets a key in
line gives it, restrict,pty,command="..." entering the sandbox:
restrict turns off port, agent and X11 forwarding and ~/.ssh/rc,
each a way around the sandbox, and pty gives back a terminal. Their
login shell is /bin/sh, which reads no file of theirs before the
command, and the programs are root's copies in /usr/local/lib/lnk.
Tests
LNK_TEST_BOX_ROOT (TEST_ROOT) puts a test's folder in place of /,
for tests of a stand-in box; only a debug build reads it.
An ordinary box's workers
box_workers is the root launcher of an ordinary box: its settings in
/etc/lnk/workers.json (CONFIG), ordinary with its Controller
(uid, gid, groups) or packed, and the program it runs,
/usr/local/lib/lnk/lnk-sandbox (PROGRAM). Packed boxes use their
slot users; computers keep the person's explicit keeper fallback.
privileged
The root-owned helper: only an already authorized controller can ask sudo, and no sudo rule is given to a worker. It keeps explicitly inherited descriptors (the proxy's namespace handshake), and the child's given environment.
Client and Route Interfaces
Client Interface explains how callers ask for confinement while retaining ownership of the program and environment they run. Routes defines proxy mounts and bridge calls for models, secrets, and outside tools.
Model and Secret Routing
Models and Secrets explains placeholder replacement, credential boundaries, and how each service bridge handles an allowed call without exposing the stored credential.