Skip to content

Leash and Security

Allie Coleman edited this page Jul 15, 2026 · 2 revisions

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.

1. Effects — the semantic vocabulary

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.

2. Policy — who may do what

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.

3. Plan → apply

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).

4. Enforcement tiers — reported honestly

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.

Linux — Landlock (tier A)

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 — Seatbelt (tier C), first-class

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.

Spawn hash pinning — real function, not yet wired into the real spawn path

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.

5. Secrets

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.

6. Agent authentication

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).

Cross-links

  • 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.