Repository navigation
Leash and Security
leash is shoal's capability and policy engine — permission over the semantic call
(name → hash → grant), not over "who can read the filesystem." It's implemented as
shoal-leash, a real crate with a real Linux Landlock backend and a real macOS Seatbelt backend —
not stubs behind a TODO. This page covers the effect model, the plan → apply flow, and the
enforcement tiers, and is honest about exactly which tier is active on which platform today.
Every action shoal can take is one of a closed set of effect instances (shoal-leash::Effect):
pub enum Effect {
FsRead { paths: Vec<PathBuf> },
FsWrite { paths: Vec<PathBuf> },
FsDelete { paths: Vec<PathBuf> },
ProcSpawn { bin_hash: String, argv0: String },
NetConnect { host: String, port: u16 },
NetListen { port: u16 },
EnvRead { names: Vec<String> },
EnvWrite { names: Vec<String> },
SecretUse { names: Vec<String> },
SessionWrite,
JournalRead,
Time,
Opaque, // T0 / sh{} — the call's effects can't be statically known
}Builtins declare their effects exactly; adapters declare them parametrically (fs.delete($paths),
net.connect($remote) — see the adapter examples in Ecosystem-and-Tooling); T0 calls (no
adapter — an arbitrary external binary) and sh { } blocks declare Opaque (⊤) because their
effects genuinely cannot be known without running them.
A Policy (~/.config/shoal/leash.toml) maps principal → grants, one section per principal:
[principal.agent]
fs.read = ["/work/**", "/usr/**"]
fs.write = ["/work/generated/**"]
fs.delete = ["/work/generated/tmp/**"]
net_connect = ["github.com:443", "*.docs.rs:443"]
net_listen = [8080]
proc_spawn = ["cargo", "deadbeef"] # binary name OR pinned content hash
env_read = ["PATH", "HOME"]
secret_use = []
session_write = true
journal_read = true
time = true
auto_apply = "reversible" # "reversible" | "in-grant" | "never" (default)
opaque = "ask" # "deny" (default) | "ask" | "allow"Path grants are glob patterns matched against a normalized path (. and .. resolved before
matching, so /work/generated/../src/a correctly does not match a /work/generated/** grant —
covered directly by a unit test). Network grants are host-glob:port-or-* pairs. Spawn grants are
declared as either a binary content hash or a name/argv0 basename, and shoal-leash's own
Policy/Verdict evaluator can check either form when handed a real ProcSpawn{bin_hash, argv0} effect — but, corrected from a previous revision of this page: the real command-spawn
path does not hand it one today. See §4's "Spawn hash pinning" note below for the precise,
verified gap — this is not yet "reef's name → version → hash chain meeting policy at the last
link" in the live system, only in the unit-tested evaluator function considered on its own.
Evaluating one effect yields a Verdict: Allow, Deny, or ApprovalRequired. Evaluating a whole
Plan (a batch of effects) walks every effect and lets denial dominate — any single denied
effect denies the entire plan, regardless of how many other effects were fine — with
ApprovalRequired dominating a plain Allow otherwise. auto_apply then decides whether an
already-allowed plan may proceed unattended: never (default) always asks first;
reversible auto-applies only when the plan's own reversibility verdict says so;
in-grant auto-applies anything the policy already covers.
A Plan is derived by evaluating a call's pure prefix — argument coercion, glob expansion,
adapter binding — and stopping before spawn:
pub struct Plan {
pub plan_ref: String, // "plan:<blake3-derived hex16>" — stable across identical plans
pub effects: Vec<Effect>,
pub reversibility: Reversibility, // Reversible | Irreversible | Unknown
pub estimates: Estimates, // bytes, items
}plan_ref is derived from a canonical hash of the plan's own contents, so re-deriving the identical
plan twice yields the identical ref — verified directly by a unit test
(plan_ref_is_stable_and_auto_apply_respects_reversibility). Over the wire (see Agent-Surface),
this is exactly shoal_plan → inspect effects/reversibility → shoal_apply {plan_ref}, or, if
the verdict came back approval_pending, shoal_cap_request to escalate. At the kernel RPC layer
this is exec {mode:"plan"} → cap.request → plan.apply, all real, all implemented today (see
Kernel-and-Agents §3).
leash makes a hard promise: it never claims enforcement it hasn't actually installed.
EnforcementStatus::detect() reports the strongest tier plausible on the host, and separately
reports whether anything is actually active right now:
pub enum EnforcementTier { A, B, C, D }
pub struct EnforcementStatus {
pub available_tier: EnforcementTier,
pub active_tier: Option<EnforcementTier>, // None until a backend is actually applied
pub enforced: bool,
pub detail: String, // human-readable, tier-specific, honest
pub filesystem_enforced: bool,
pub spawn_exec_enforced: bool,
pub network_enforced: bool,
...
}| Tier | Platform | Mechanism |
|---|---|---|
| A | Linux ≥ 5.13 | Landlock + seccomp + netns proxy; BPF-LSM content-hash spawn pinning |
| B | Older Linux | Namespaces + bind-mounts, inode checks |
| C | macOS | Seatbelt profiles |
| D | Anything else | Advisory only — caps.enforced: false surfaced at attach |
A unit test (enforcement_is_honest) pins this contract directly: detect() alone never reports
enforced: true; it only describes what's available. Actual enforcement requires calling
apply_landlock/apply_macos_sandbox explicitly, and each returns its own truthful
EnforcementStatus reflecting exactly what was applied — filesystem enforced, but spawn and
network still not, for instance, in both backends today. shoal doctor runs detect() and reports
the result as an ok/warn check, so "is my sandbox actually real right now" is one command, not
a guess.
pub fn apply_landlock(grants: &FsSandbox) -> Result<EnforcementStatus, String>A real landlock crate integration: builds a ruleset from the grant's read/write/delete path sets
using AccessFs::from_read/from_all plus the RemoveDir | RemoveFile bits for delete, calls
restrict_self(), and only reports filesystem_enforced: true if the kernel actually confirms
RulesetStatus::FullyEnforced — a partially-enforced Landlock ruleset (older kernel, missing ABI
feature) is reported as a hard error, never silently accepted as "good enough."
macOS is not a stub here. shoal-leash generates a real, deterministic, deny-by-default Seatbelt
profile and applies it via the actual sandbox_init(3) syscall:
pub fn seatbelt_profile(grants: &FsSandbox) -> Result<String, String> // "(version 1)\n(deny default)\n..."
pub fn apply_macos_sandbox(grants: &FsSandbox) -> Result<EnforcementStatus, String>(version 1)
(deny default)
(allow process*)
(allow signal (target self))
(allow file-read* (subpath "/work/src"))
(allow file-read* file-write* (subpath "/work/generated"))
(allow file-read-metadata file-write-unlink (subpath "/work/generated/tmp"))
Every grant path is canonicalized before it's written into the profile (so a symlink or a
lexical .. can't silently broaden what a grant covers), sorted and deduplicated, and
Seatbelt-escaped (rejecting control characters, escaping "/\) — all covered directly by unit
tests (seatbelt_profile_is_canonical_sorted_and_escaped). Applying the profile calls the real
sandbox_init C function via FFI and only reports filesystem_enforced: true on a genuine zero
return; a nonzero return surfaces the OS's own error string. This is the same class of concrete
enforcement as Linux's tier A, just backed by the platform's own primitive instead of Landlock —
Seatbelt is a first-class enforcement backend in this codebase, not a documented-but-unimplemented
placeholder.
pub fn preflight_spawn(binary: &Path, allowlist: &[String]) -> std::io::Result<SpawnPreflight>This function is real, unit-tested, and does exactly what it claims in isolation: hashes the
binary's full contents with blake3 and checks it (by hash or by name) against an allowlist. The
assurance field on its result is honest about its own remaining limit even when it is called:
"content hashed before exec; TOCTOU remains until exec-time BPF-LSM pinning."
Corrected from a previous revision of this page — verified directly against source, not just the
unit tests: nothing in the actual command-execution path calls preflight_spawn or constructs a
ProcSpawn effect with a real hash. crates/shoal-eval/src/plan_derive.rs hardcodes
Effect::ProcSpawn { bin_hash: String::new(), .. } — the hash is always empty — and the real spawn
path (run_argv → resolve_sandbox in crates/shoal-eval/src/command.rs) only resolves an
OS-level SandboxPolicy (the Landlock/Seatbelt filesystem enforcement described above, which is
real and active); it never calls shoal-leash's effect evaluator at all, so a policy's proc_spawn
hash/name grants are never actually consulted on a live spawn today. Practical consequence: a
policy author who writes proc_spawn = ["<hash>"] believing an unrecognized binary will be blocked
gets no such protection from this mechanism right now — filesystem/network confinement (Landlock/
Seatbelt) is the real, active enforcement; spawn-identity pinning is designed, implemented as an
isolated function, and unit-tested, but not yet connected to a live spawn. Track this as a
docs/ROADMAP.md item, not a shipped guarantee, until plan_derive.rs threads a real hash through
and the spawn path actually calls the evaluator with it.
shoal-secret's SecretStore holds secret material on disk and returns it wrapped in Zeroizing
— it's scrubbed from memory the moment it goes out of scope. A secret value in the language
(TDD §4.1) renders as secret(NAME), is a type error to interpolate into a str, and is injected
directly into a spawned child's argv/env by the kernel — the journal records only the name
(§4 in Kernel-and-Agents), never the material. .feeding a secret is a dedicated feed_error,
not a generic type error, specifically to carry the "secrets are injected at spawn time, not fed as
data" hint.
shoal-auth's TokenStore mints and validates bearer tokens (shoal token create --caps <leash-profile>), each carrying a principal name, a capability list, and a policy profile.
session.attach resolves a presented token into that identity — same-uid local clients (the human
TUI) skip tokens entirely via SO_PEERCRED; remote/agent principals present one. Tokens can be
listed and revoked (TokenStore::list/revoke).
- Reef — the content-hash chain leash's spawn pinning is designed to consume (see both pages' "not yet wired" notes for the current, honest state of that specific link).
-
Kernel-and-Agents — where
exec's policy verdict (Deny/ApprovalRequired/Allow) is actually consulted, before anything runs. -
Agent-Surface —
shoal_plan/shoal_apply/shoal_cap_request, the wire front end onto everything on this page. -
docs/TDD.md§8 — the normative spec this page implements.