{"row":{"id":"ADR-095","title":"exec verb security architecture · layered defense-in-depth (permits = declaration, 3 layers enforce)","file":"adr-095-exec-security-architecture.md","status":"accepted","date":"2026-06-12","cites":7,"supersedes":[],"superseded_by":[],"layers":["L0.5","L1","L2","L3"],"tags":["security","exec","injection","sandbox"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-095 · exec verb security architecture","id":"adr-095--exec-verb-security-architecture"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The "},{"k":"code","text":"exec"},{"k":"text","text":" verb is the most dangerous of the 4 verbs: it runs OS processes\nwhose arguments are CEL-interpolated from upstream task outputs — including\n"},{"k":"code","text":"infer"},{"k":"text","text":"/"},{"k":"code","text":"agent"},{"k":"text","text":" (LLM) outputs, which are attacker-influenceable by\nconstruction (indirect prompt injection · arXiv 2302.12173). A deep audit\n(2026-06-12) plus two primary-source research sweeps (arXiv agent-security\nliterature + 2026 competitor practice) found one active vulnerability and\nseveral missing SOTA layers."}]},{"k":"h","depth":3,"text":"The audit findings","id":"the-audit-findings"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Finding · Severity · Was"}],[{"k":"text","text":"**Array form silently shell-joined** · P0 · The spec (02-verbs §exec) sells `command: [\"prog\", \"{{ v }}\"]` as \"the STRUCTURAL fix for command injection\". But the runtime joined the rendered argv with spaces and ran it through the OS shell (`ExecInput` carried only a `String`), so the *safe* form was injection-VULNERABLE while looking safe."}],[{"k":"text","text":"No OS sandbox · P1 · The verb summary reads \"exec: Shell command **with sandboxing**\"; none existed. The child ran with the engine's full privileges/network/filesystem/env."}],[{"k":"text","text":"Blocklist = denylist · P1 · A string-matching denylist that both leaks (∞ bypass variants) AND false-positives legit CI (`timeout`/`env`/`nice`/`printenv` blocked), re-scanning a flattened argv line that has no shell to parse."}],[{"k":"text","text":"Env inherited wholesale · P1 · The child inherited the engine's full environment — the env-var-injection class (`LD_PRELOAD`/`BASH_ENV`/`GIT_SSH_COMMAND` …) and secret leakage."}],[{"k":"text","text":"Grandchildren leak · P2 · `kill_on_drop` killed only the direct child; a backgrounded grandchild orphaned on timeout."}],[{"k":"text","text":"`permits:` not enforced at exec · P1 · `Permits {fs,net,exec,tool}` is fully modeled and spec-mandated (\"the engine MUST enforce on both surfaces\" · NIKA-SEC-004), but the runtime sink never consulted it."}]]},{"k":"h","depth":3,"text":"Research convergence (theory + practice agree — high signal)","id":"research-convergence-theory--practice-agree--high-signal"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Control/data-plane separation"},{"k":"text","text":" (CaMeL/DeepMind 2503.18813, design-patterns 2506.08837, Fides/MS 2505.23643): the workflow YAML is the "},{"k":"em","text":"trusted control plane"},{"k":"text","text":"; interpolated values are "},{"k":"em","text":"untrusted data"},{"k":"text","text":" that may fill declared slots but never select the program, flags, or DAG edges. A declarative DAG + "},{"k":"code","text":"permits:"},{"k":"text","text":" give this almost for free."}],[{"k":"strong","text":"Array-not-shell"},{"k":"text","text":" (GitHub Actions script-injection: 24,905 issues / 50 repos, arXiv 2208.03837; CVE-2025-30066): string-templating untrusted values into a shell is THE workflow-engine injection class."}],[{"k":"strong","text":"Default-deny symbolic policy"},{"k":"text","text":" (Progent 2504.11703, AgentSpec 2503.18666, AgentBound 2510.21236): an allowlist over binary + argv, deterministic, default-deny = "},{"k":"code","text":"permits.exec"},{"k":"text","text":"."}],[{"k":"strong","text":"OS sandbox floor"},{"k":"text","text":" (RedCode 2411.07781, SandboxEval 2504.00018; Claude Code / Codex / Cursor 2026): \"assume the command is hostile\" is uncontested; every coding-agent CLI ships an OS-level safe-by-default sandbox, all 100% local/OSS (sovereignty-aligned). Workflow engines (n8n/Airflow/Temporal) ship exec unsandboxed — Nika's chance to lead."}],[{"k":"strong","text":"Argument-injection canon"},{"k":"text","text":" (GTFOArgs, SonarSource/CAPEC-6): even without a shell, an argv value injects via flags ("},{"k":"code","text":"ssh -o ProxyCommand"},{"k":"text","text":", "},{"k":"code","text":"tar --checkpoint-action"},{"k":"text","text":", "},{"k":"code","text":"git -c core.sshCommand"},{"k":"text","text":", "},{"k":"code","text":"curl -K"},{"k":"text","text":", "},{"k":"code","text":"find -exec"},{"k":"text","text":"). The "},{"k":"code","text":"--"},{"k":"text","text":" end-of-options discipline + a per-binary flag denylist."}],[{"k":"strong","text":"Detection ⇒ telemetry only"},{"k":"text","text":" (2503.00061: 8/8 published detector defenses bypassed >50% under adaptive attack): a string-matching detector must never be the sole boundary."}]]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"code","text":"permits:"},{"k":"text","text":" is the "},{"k":"strong","text":"declaration"},{"k":"text","text":" (the trusted control plane, author-written,\nin-file · spec 01 §permits). Three layers "},{"k":"strong","text":"enforce"},{"k":"text","text":" it; the blocklist\ndemotes from \"the wall\" to a shell-mode tripwire."}]},{"k":"code","lang":"text","text":"  permits: { fs, net, exec, tool }      DECLARATION · trusted · spec 01 §permits\n        |  enforced at 3 layers\n  L2 nika-verb-exec  — ExecCommand::{ Shell(String) | Argv(Vec<String>) }\n     • argv = the structural injection fix (execve, no shell)        [LAYER 1]\n     • env scrub (deny LD_PRELOAD/BASH_ENV/… · reset PATH)           [LAYER 3]\n  L3 nika-runtime    — dispatch the array form as a vector (no join)\n     • permits.exec allowlist on the resolved program (NIKA-SEC-004) [LAYER 2]\n  L0 nika-schema     — one-obvious-way/008 steers string→array; the\n     arg-injection rule-pack flags dangerous flags from interpolation [LAYER 2b]\n  L1 nika-exec-runner — shell-mode blocklist tripwire · argv program-floor\n     • process-group kill (reap grandchildren) · output cap · timeout [LAYER 4/5]\n  L1 nika-sandbox    — Landlock+seccomp (Linux) / Seatbelt (macOS):\n     net-deny + FS-confine from permits.fs/net + rlimits             [LAYER 6]"},{"k":"p","inline":[{"k":"text","text":"The inversion: "},{"k":"strong","text":"array (structural) + sandbox (OS) are the walls; the\n`permits.exec` allowlist is the intent gate; the blocklist is the shell-mode\ntripwire"},{"k":"text","text":" — not the sole, leaky, false-positive denylist it was."}]},{"k":"h","depth":2,"text":"The layers","id":"the-layers"},{"k":"h","depth":3,"text":"Layer 1 — Array execution, no shell (L2 + L3 · SHIPPED)","id":"layer-1--array-execution-no-shell-l2--l3--shipped"},{"k":"p","inline":[{"k":"code","text":"ExecInput.command"},{"k":"text","text":" is now "},{"k":"code","text":"ExecCommand { Shell(String) | Argv(Vec<String>) }"},{"k":"text","text":".\nThe array form maps to "},{"k":"code","text":"execve"},{"k":"text","text":" with the shell flag OFF; every element is one\nliteral argv token — an interpolated value can never break out of its argument\nbecause there is no shell to parse it. The runtime renders each array element\nand passes a vector (no join). The string form keeps the OS shell for genuine\npipelines. This closes the P0 and is the structural fix the spec mandates."}]},{"k":"h","depth":3,"text":"Layer 2 — permits.exec allowlist (L3 · SHIPPED)","id":"layer-2--permitsexec-allowlist-l3--shipped"},{"k":"p","inline":[{"k":"text","text":"The runtime threads the workflow's "},{"k":"code","text":"Permits"},{"k":"text","text":" to the exec sink. "},{"k":"code","text":"exec: false"},{"k":"text","text":"\n(or omitted under a declared boundary) refuses any process; a program\nallowlist must contain the resolved leading token (argv[0], or the first word\nof a shell line) — matching the static "},{"k":"code","text":"nika check"},{"k":"text","text":" (permits_fit) so a\nworkflow that passes the check never fails at runtime for a different reason.\nThe static check owns statically-detectable escapes; the runtime owns the\ninterpolated programs static analysis defers. A "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" future\npermit form fails CLOSED."}]},{"k":"h","depth":3,"text":"Layer 2b — Discoverability + arg-injection lints (L0 nika-schema)","id":"layer-2b--discoverability--arg-injection-lints-l0-nika-schema"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"one-obvious-way/008"},{"k":"text","text":" (SHIPPED) warns when an interpolated value lands in a\nstring command that needs no shell, pointing to the injection-safe array\nform — fires only when the literal parts carry no shell metacharacter (a\ngenuine pipeline keeps the string form · low-false-positive)."}],[{"k":"strong","text":"arg-injection rule-pack"},{"k":"text","text":" (DESIGNED · the differentiator) — a clean-room\ncatalog (from the public GTFOArgs + SonarSource/CAPEC-6 facts) of dangerous\nflags per binary; flags an interpolated value landing in a flag slot / a\nleading-dash value for a known binary, and recommends the "},{"k":"code","text":"--"},{"k":"text","text":" end-of-options\nseparator. No competing engine ships this."}]]},{"k":"h","depth":3,"text":"Layer 3 — Env hygiene (L1 + L2 · SHIPPED · three sub-layers)","id":"layer-3--env-hygiene-l1--l2--shipped--three-sub-layers"},{"k":"p","inline":[{"k":"text","text":"Three sub-layers, weakest-to-strongest, each independent of the OS sandbox:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"POSIX-name validation (L2 · `nika-verb-exec`)."},{"k":"text","text":" An "},{"k":"code","text":"env:"},{"k":"text","text":" key must match\n"},{"k":"code","text":"[A-Za-z_][A-Za-z0-9_]*"},{"k":"text","text":" — this refuses the dynamic-name carrier class,\nchiefly the exported-shell-function form "},{"k":"code","text":"BASH_FUNC_x%%"},{"k":"text","text":" that a bash "},{"k":"code","text":"sh -c"},{"k":"text","text":"\nchild imports and runs (the payload never appears in the scanned command\nstring). Empty / "},{"k":"code","text":"="},{"k":"text","text":" / NUL keys still fail (a strict narrowing)."}],[{"k":"strong","text":"Dangerous-env denylist (L1 · `nika-exec-runner`)."},{"k":"text","text":" The runner ALWAYS\nstrips the injection vectors that grant code/library injection with no\ndangerous flag: "},{"k":"code","text":"LD_PRELOAD"},{"k":"text","text":", "},{"k":"code","text":"DYLD_INSERT_LIBRARIES"},{"k":"text","text":", "},{"k":"code","text":"BASH_ENV"},{"k":"text","text":",\n"},{"k":"code","text":"GIT_SSH_COMMAND"},{"k":"text","text":", "},{"k":"code","text":"PYTHONSTARTUP"},{"k":"text","text":", "},{"k":"code","text":"NODE_OPTIONS"},{"k":"text","text":", "},{"k":"code","text":"IFS"},{"k":"text","text":", plus\n"},{"k":"code","text":"HOSTALIASES"},{"k":"text","text":" / "},{"k":"code","text":"TERMINFO(_DIRS)"},{"k":"text","text":" / "},{"k":"code","text":"TERMCAP"},{"k":"text","text":" (file-read / crafted-entry\nload) — independent of "},{"k":"code","text":"pre_validated"},{"k":"text","text":" (the floor wins over an explicit set)."}],[{"k":"strong","text":"Ambient-secret scrub (L1 · `nika-exec-runner` ← composed by `nika-cli`)."},{"k":"text","text":"\nThe engine loads provider API keys from ITS env ("},{"k":"code","text":"config_from_env"},{"k":"text","text":") for its\nOWN inference calls; an exec child inherits them by ambient default and an\nuntrusted command could exfiltrate them ("},{"k":"code","text":"printenv"},{"k":"text","text":", "},{"k":"code","text":"cat /proc/self/environ"},{"k":"text","text":").\nThe composition root injects the provider-key NAMES (from the catalog) into\n"},{"k":"code","text":"TokioShell"},{"k":"text","text":", which strips each from every child UNLESS the workflow set it\nEXPLICITLY in "},{"k":"code","text":"env:"},{"k":"text","text":" (explicit intent wins · only the ambient copy is\nremoved). Least-privilege by default; empty scrub set = legacy behavior."}]]},{"k":"p","inline":[{"k":"text","text":"The stronger "},{"k":"em","text":"full"},{"k":"text","text":" clean-slate posture (drop ALL inherited env + a curated\n"},{"k":"code","text":"PATH"},{"k":"text","text":") still ships with the sandbox (Layer 6), which knows the confined\nworkflow's complete declared env needs; sub-layer 3 is the targeted\nsecret-scrub floor that holds before the sandbox is composed in."}]},{"k":"h","depth":3,"text":"Layer 4/5 — Process lifecycle (L1 · SHIPPED partial)","id":"layer-45--process-lifecycle-l1--shipped-partial"},{"k":"p","inline":[{"k":"text","text":"The child spawns in its own process group (the safe std "},{"k":"code","text":"process_group(0)"},{"k":"text","text":", no\nunsafe "},{"k":"code","text":"pre_exec"},{"k":"text","text":"); on timeout/cancel the whole group is signalled (SIGTERM →\ngrace → SIGKILL via "},{"k":"code","text":"nix::killpg"},{"k":"text","text":") so detached grandchildren die. Output is\ncapped (64 MiB/stream) and the timeout hard-kills. Resource rlimits\n(RLIMIT_CPU/FSIZE/NPROC + no-core-dump) need a child-side "},{"k":"code","text":"pre_exec"},{"k":"text","text":" (unsafe),\nso they move to "},{"k":"code","text":"nika-sandbox"},{"k":"text","text":" (which owns the low-level confinement)."}]},{"k":"h","depth":3,"text":"Layer 6 — OS sandbox (PER-PLATFORM L1 crates · macOS SHIPPED + verified)","id":"layer-6--os-sandbox-per-platform-l1-crates--macos-shipped--verified"},{"k":"p","inline":[{"k":"strong","text":"Reconciliation (2026-06-13)."},{"k":"text","text":" The kernel already RESERVES a capability\n"},{"k":"code","text":"Sandbox"},{"k":"text","text":" ("},{"k":"code","text":"plugin::sandbox"},{"k":"text","text":" · WASM/MCP · the "},{"k":"code","text":"enter()"},{"k":"text","text":" self-restriction model\n· v0.100), whose doc names the future impl crates "},{"k":"code","text":"nika-sandbox-landlock"},{"k":"text","text":"\n(Linux) and "},{"k":"code","text":"nika-sandbox-seatbelt"},{"k":"text","text":" (macOS). Confining the "},{"k":"code","text":"exec"},{"k":"text","text":" verb's CHILD\nprocess is a DISTINCT operation — \"transform the command into its confined\nform\" — so it rides a NEW additive kernel seam, NOT the reserved trait, and\nships as the per-platform crates the reservation already names (operator-locked\n2026-06-13: per-platform crates + a new trait · supersedes the original single\n"},{"k":"code","text":"nika-sandbox"},{"k":"text","text":" framing of this ADR)."}]},{"k":"p","inline":[{"k":"strong","text":"The seam (L0.5 · `nika-kernel-core/src/io/command_sandbox.rs` · SHIPPED)."},{"k":"text","text":"\nA new "},{"k":"code","text":"CommandSandbox"},{"k":"text","text":" trait — sync, object-safe, "},{"k":"code","text":"confine(spec, ShellCommand) -> ShellCommand"},{"k":"text","text":" — plus "},{"k":"code","text":"SandboxSpec"},{"k":"text","text":" ("},{"k":"code","text":"fs_read"},{"k":"text","text":"/"},{"k":"code","text":"fs_write"},{"k":"text","text":" prefixes ·\n"},{"k":"code","text":"allow_network"},{"k":"text","text":" · derived from "},{"k":"code","text":"permits.fs/net"},{"k":"text","text":"), "},{"k":"code","text":"CommandSandboxError"},{"k":"text","text":"\n("},{"k":"code","text":"Unavailable"},{"k":"text","text":"/"},{"k":"code","text":"Profile"},{"k":"text","text":" · fail-closed), and a "},{"k":"code","text":"NoopSandbox"},{"k":"text","text":" (the explicit,\nauditable \"unconfined\" choice). Add a "},{"k":"code","text":"ShellCommand.sandbox"},{"k":"text","text":" field. The\n"},{"k":"strong","text":"wrapper model"},{"k":"text","text":" (no "},{"k":"code","text":"unsafe"},{"k":"text","text":", no FFI · the seam returns a TRANSFORMED command,\nnot a "},{"k":"code","text":"pre_exec"},{"k":"text","text":" closure) replaces the original "},{"k":"code","text":"Confinement"},{"k":"text","text":"-closure design —\nit keeps the crates at "},{"k":"code","text":"unsafe_code = forbid"},{"k":"text","text":" and is what every coding-agent CLI\nuses."}]},{"k":"p","inline":[{"k":"strong","text":"macOS — `nika-sandbox-seatbelt` (SHIPPED · adversarially verified)."},{"k":"text","text":" Wraps a\ncommand in the OS-shipped "},{"k":"code","text":"sandbox-exec"},{"k":"text","text":" launcher with a deny-default SBPL\nprofile generated from the spec: network denied unless granted; writes only\nunder declared "},{"k":"code","text":"fs_write"},{"k":"text","text":" + scratch; reads of the system paths every binary\nneeds, plus declared "},{"k":"code","text":"fs_read"},{"k":"text","text":" — so sensitive home paths ("},{"k":"code","text":"~/.ssh"},{"k":"text","text":", "},{"k":"code","text":"~/.aws"},{"k":"text","text":")\nare denied. Profile-injection via a malicious path is closed (control-char\nrefusal + quote-escaping). An adversarial jail suite RUNS "},{"k":"code","text":"sandbox-exec"},{"k":"text","text":" on\ndarwin and proves: a home-secret read is denied, a declared path is readable, a\nwrite outside the allowlist is denied, an ordinary command still runs. Wired\ninto "},{"k":"code","text":"TokioShell::with_sandbox"},{"k":"text","text":" (applied after the blocklist · fail-closed)."}]},{"k":"p","inline":[{"k":"strong","text":"Linux — `nika-sandbox-landlock` (CI-GATED)."},{"k":"text","text":" The sibling crate: "},{"k":"code","text":"landlock"},{"k":"text","text":"\n(FS allowlist) + "},{"k":"code","text":"extrasafe"},{"k":"text","text":"/seccomp (block ptrace/unshare/AF_UNIX) + net-deny"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"rlimits, via "},{"k":"code","text":"bwrap"},{"k":"text","text":" or a Landlock helper. Only partly verifiable off a Linux\nbox → a focused CI-backed arc. Same "},{"k":"code","text":"CommandSandbox"},{"k":"text","text":" seam."}]]},{"k":"p","inline":[{"k":"strong","text":"Follow-on plumbing."},{"k":"text","text":" Runtime derivation ("},{"k":"code","text":"permits.fs/net"},{"k":"text","text":" → "},{"k":"code","text":"SandboxSpec"},{"k":"text","text":" →\n"},{"k":"code","text":"ExecInput.sandbox"},{"k":"text","text":") and composer injection (select + inject the platform\nbackend into "},{"k":"code","text":"TokioShell"},{"k":"text","text":") connect a workflow's "},{"k":"code","text":"permits:"},{"k":"text","text":" to confinement\nend-to-end; the composer is the "},{"k":"code","text":"nika-cli"},{"k":"text","text":"/engine surface (in flight)."}]},{"k":"p","inline":[{"k":"text","text":"Honest limits (documented in the crate): glob→subpath is a coarsening (path-\nprefix, not per-file); network is allow-all-or-deny (host-granular needs a\nproxy); resource rlimits + the SandboxEval egress suite are part of the\nlandlock arc. Full 12-gate admission (Linux backend · mutation ≥90% · review\nswarm) is the CI completion."}]},{"k":"h","depth":3,"text":"Layer 7 — Blocklist demoted to a tripwire (L1 · SHIPPED)","id":"layer-7--blocklist-demoted-to-a-tripwire-l1--shipped"},{"k":"p","inline":[{"k":"text","text":"The string-matching blocklist is no longer the wall. Shell mode keeps the full\nbattle-tested blocklist + the expansion-char refusal (the tripwire for the\ngenuinely-dangerous string path). Array mode gets an exact-basename\n"},{"k":"code","text":"check_program"},{"k":"text","text":" against a small dangerous-program set (privilege escalation +\nsystem control) — no fake-shell scan, which removes the "},{"k":"code","text":"timeout"},{"k":"text","text":"/"},{"k":"code","text":"env"},{"k":"text","text":"/"},{"k":"code","text":"nice"},{"k":"text","text":"/\n"},{"k":"code","text":"printenv"},{"k":"text","text":" false-positives. Per the adaptive-attack evidence, the blocklist is\ndefense-in-depth, never the primary boundary."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"p","inline":[{"k":"strong","text":"Positive."},{"k":"text","text":" The structural injection hole is closed; the safe form is the\ndefault and discoverable; the capability boundary is enforced; the env / process\nclasses are shut; the sandbox (when shipped) makes \"even if the blocklist\nmisses it, it can't hurt you\" true. The architecture matches the converging\nSOTA and stays 100% local/OSS (sovereignty). The "},{"k":"code","text":"permits:"},{"k":"text","text":" declaration unifies\nall enforcement (the file is the security boundary)."}]},{"k":"p","inline":[{"k":"strong","text":"Negative / interim gaps (logged, not silent)."}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The argv program-floor no longer blocks a directly-authored dangerous command\n(e.g. a destructive "},{"k":"code","text":"rm"},{"k":"text","text":" on root) — that is gated by "},{"k":"code","text":"permits.exec"},{"k":"text","text":" + the\nsandbox, not the floor. Acceptable: the floor is identity-based; intent is\npolicy + sandbox."}],[{"k":"text","text":"The OS sandbox (Layer 6) is the big remaining lift, cross-platform and only\npartly verifiable off a Linux box — a focused CI-backed admission arc."}],[{"k":"text","text":"Runtime taint propagation (which resolved values are interpolation-derived)\nis deferred — the arg-injection guard ships as a static lint; runtime\ntaint-enforcement lands when the binding layer carries taint (shadow zone\n"},{"k":"code","text":"l1-taint-runtime"},{"k":"text","text":")."}],[{"k":"text","text":"Operator/host policy + token budgets remain "},{"k":"code","text":"nika-policy"},{"k":"text","text":"'s job (gated on the\nkernel migration); the runtime "},{"k":"code","text":"permits"},{"k":"text","text":" enforcement is the interim."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Blocklist-only (status quo)."},{"k":"text","text":" Rejected: both leaks and false-positives;\nthe adaptive-attack literature refutes detector-as-boundary."}],[{"k":"strong","text":"Container/microVM per exec"},{"k":"text","text":" (e2b, Firecracker). Rejected as the default:\nnon-sovereign (hosted) or heavy startup latency; the agent-CLI OS-sandbox\nmodel fits a local-first engine better."}],[{"k":"strong","text":"Sandbox as a module in nika-exec-runner."},{"k":"text","text":" Rejected: heavy platform deps +\nunsafe "},{"k":"code","text":"pre_exec"},{"k":"text","text":" + independent adversarial testing → its own L1 crate behind\na kernel seam is the Diamond-coherent shape."}]]},{"k":"h","depth":2,"text":"Implementation status","id":"implementation-status"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Layer · Crate(s) · Status"}],[{"k":"text","text":"1 array execution · nika-verb-exec · nika-runtime · ✅ shipped"}],[{"k":"text","text":"2 permits.exec · nika-runtime · ✅ shipped"}],[{"k":"text","text":"2b /008 steer · nika-schema · ✅ shipped"}],[{"k":"text","text":"2b arg-injection pack · nika-schema · ✅ shipped (arg-injection/001)"}],[{"k":"text","text":"3 env POSIX-name validation · nika-verb-exec · ✅ shipped (kills `BASH_FUNC_x%%` carrier)"}],[{"k":"text","text":"3 env dangerous-denylist · nika-exec-runner · ✅ shipped (+HOSTALIASES/TERMINFO/TERMCAP)"}],[{"k":"text","text":"3 env ambient-secret scrub · nika-exec-runner ← nika-cli · ✅ shipped (provider keys · explicit `env:` wins)"}],[{"k":"text","text":"3 env full clean-slate · nika-sandbox · 🔜 → L6 (drop-all + curated PATH)"}],[{"k":"text","text":"4/5 process group · nika-exec-runner · ✅ shipped · rlimits → L6"}],[{"k":"text","text":"6 sandbox seam · nika-kernel-core (CommandSandbox) · ✅ shipped"}],[{"k":"text","text":"6 sandbox macOS · nika-sandbox-seatbelt · ✅ shipped · adversarially verified"}],[{"k":"text","text":"6 sandbox wiring · nika-exec-runner (with_sandbox) · ✅ shipped"}],[{"k":"text","text":"6 sandbox Linux · nika-sandbox-landlock · ✅ shipped · CI-gated (bwrap in the tests leg · 4 jail proofs)"}],[{"k":"text","text":"6 permits→spec + composer inject · nika-runtime · engine · ✅ shipped (v0.105.x · dispatch derives the spec from `permits:` · the composer wires seatbelt/landlock · noop note when no backend)"}],[{"k":"text","text":"7 blocklist tripwire · nika-exec-runner · ✅ shipped (mode-split)"}]]},{"k":"h","depth":2,"text":"References","id":"references"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Spec: "},{"k":"code","text":"nika-spec spec/02-verbs.md §exec"},{"k":"text","text":" · "},{"k":"code","text":"spec/01-envelope.md §permits"},{"k":"text","text":" · "},{"k":"code","text":"spec/05-errors.md"},{"k":"text","text":" (NIKA-EXEC-001/002 · NIKA-SEC-001/004)."}],[{"k":"text","text":"arXiv: 2302.12173 · 2208.03837 · 2503.18813 (CaMeL) · 2506.08837 · 2505.23643 (Fides) · 2504.11703 (Progent) · 2503.18666 (AgentSpec) · 2510.21236 (AgentBound) · 2411.07781 (RedCode) · 2504.00018 (SandboxEval) · 2503.00061 (adaptive attacks)."}],[{"k":"text","text":"Catalogs: GTFOArgs · SonarSource argument-injection-vectors (CAPEC-6) · CVE-2024-24576 (BatBadBut · Windows guard)."}],[{"k":"text","text":"Crates: "},{"k":"code","text":"landlock"},{"k":"text","text":" 0.4.5 · "},{"k":"code","text":"extrasafe"},{"k":"text","text":" · "},{"k":"code","text":"nix"},{"k":"text","text":" 0.30 · std "},{"k":"code","text":"CommandExt::process_group"},{"k":"text","text":"."}],[{"k":"text","text":"Related: ADR-001 (CRAFT) · ADR-003 (12-gate) · ADR-016 (cancellation) · ADR-080 (mcp-stdio sandbox) · ADR-081 (L1 guard contract)."}]]}]

ADR-095

exec verb security architecture · layered defense-in-depth (permits = declaration, 3 layers enforce)

accepted · 2026-06-12 · L0.5 L1 L2 L3 · cites 7

ADR-095 · exec verb security architecture #

Context #

The exec verb is the most dangerous of the 4 verbs: it runs OS processes whose arguments are CEL-interpolated from upstream task outputs — including infer/agent (LLM) outputs, which are attacker-influenceable by construction (indirect prompt injection · arXiv 2302.12173). A deep audit (2026-06-12) plus two primary-source research sweeps (arXiv agent-security literature + 2026 competitor practice) found one active vulnerability and several missing SOTA layers.

The audit findings #

Finding · Severity · Was
**Array form silently shell-joined** · P0 · The spec (02-verbs §exec) sells `command: ["prog", "{{ v }}"]` as "the STRUCTURAL fix for command injection". But the runtime joined the rendered argv with spaces and ran it through the OS shell (`ExecInput` carried only a `String`), so the *safe* form was injection-VULNERABLE while looking safe.
No OS sandbox · P1 · The verb summary reads "exec: Shell command **with sandboxing**"; none existed. The child ran with the engine's full privileges/network/filesystem/env.
Blocklist = denylist · P1 · A string-matching denylist that both leaks (∞ bypass variants) AND false-positives legit CI (`timeout`/`env`/`nice`/`printenv` blocked), re-scanning a flattened argv line that has no shell to parse.
Env inherited wholesale · P1 · The child inherited the engine's full environment — the env-var-injection class (`LD_PRELOAD`/`BASH_ENV`/`GIT_SSH_COMMAND` …) and secret leakage.
Grandchildren leak · P2 · `kill_on_drop` killed only the direct child; a backgrounded grandchild orphaned on timeout.
`permits:` not enforced at exec · P1 · `Permits {fs,net,exec,tool}` is fully modeled and spec-mandated ("the engine MUST enforce on both surfaces" · NIKA-SEC-004), but the runtime sink never consulted it.

Research convergence (theory + practice agree — high signal) #

Control/data-plane separation (CaMeL/DeepMind 2503.18813, design-patterns 2506.08837, Fides/MS 2505.23643): the workflow YAML is the trusted control plane; interpolated values are untrusted data that may fill declared slots but never select the program, flags, or DAG edges. A declarative DAG + permits: give this almost for free.
Array-not-shell (GitHub Actions script-injection: 24,905 issues / 50 repos, arXiv 2208.03837; CVE-2025-30066): string-templating untrusted values into a shell is THE workflow-engine injection class.
Default-deny symbolic policy (Progent 2504.11703, AgentSpec 2503.18666, AgentBound 2510.21236): an allowlist over binary + argv, deterministic, default-deny = permits.exec.
OS sandbox floor (RedCode 2411.07781, SandboxEval 2504.00018; Claude Code / Codex / Cursor 2026): "assume the command is hostile" is uncontested; every coding-agent CLI ships an OS-level safe-by-default sandbox, all 100% local/OSS (sovereignty-aligned). Workflow engines (n8n/Airflow/Temporal) ship exec unsandboxed — Nika's chance to lead.
Argument-injection canon (GTFOArgs, SonarSource/CAPEC-6): even without a shell, an argv value injects via flags (ssh -o ProxyCommand, tar --checkpoint-action, git -c core.sshCommand, curl -K, find -exec). The -- end-of-options discipline + a per-binary flag denylist.
Detection ⇒ telemetry only (2503.00061: 8/8 published detector defenses bypassed >50% under adaptive attack): a string-matching detector must never be the sole boundary.

Decision #

permits: is the declaration (the trusted control plane, author-written, in-file · spec 01 §permits). Three layers enforce it; the blocklist demotes from "the wall" to a shell-mode tripwire.

text

1  ⛨permits: { fs, net, exec, tool }      DECLARATION · trusted · spec 01 §permits2        |  enforced at 3 layers3  L2 nika-verb-exec  — ExecCommand::{ Shell(String) | Argv(Vec<String>) }4     • argv = the structural injection fix (execve, no shell)        [LAYER 1]5     • env scrub (deny LD_PRELOAD/BASH_ENV/… · reset PATH)           [LAYER 3]6  L3 nika-runtime    — dispatch the array form as a vector (no join)7     • permits.exec allowlist on the resolved program (NIKA-SEC-004) [LAYER 2]8  L0 nika-schema     — one-obvious-way/008 steers string→array; the9     arg-injection rule-pack flags dangerous flags from interpolation [LAYER 2b]10  L1 nika-exec-runner — shell-mode blocklist tripwire · argv program-floor11     • process-group kill (reap grandchildren) · output cap · timeout [LAYER 4/5]12  L1 nika-sandbox    — Landlock+seccomp (Linux) / Seatbelt (macOS):13     net-deny + FS-confine from permits.fs/net + rlimits             [LAYER 6]

The inversion: array (structural) + sandbox (OS) are the walls; the `permits.exec` allowlist is the intent gate; the blocklist is the shell-mode tripwire — not the sole, leaky, false-positive denylist it was.

The layers #

Layer 1 — Array execution, no shell (L2 + L3 · SHIPPED) #

ExecInput.command is now ExecCommand { Shell(String) | Argv(Vec<String>) }. The array form maps to execve with the shell flag OFF; every element is one literal argv token — an interpolated value can never break out of its argument because there is no shell to parse it. The runtime renders each array element and passes a vector (no join). The string form keeps the OS shell for genuine pipelines. This closes the P0 and is the structural fix the spec mandates.

Layer 2 — permits.exec allowlist (L3 · SHIPPED) #

The runtime threads the workflow's Permits to the exec sink. exec: false (or omitted under a declared boundary) refuses any process; a program allowlist must contain the resolved leading token (argv[0], or the first word of a shell line) — matching the static nika check (permits_fit) so a workflow that passes the check never fails at runtime for a different reason. The static check owns statically-detectable escapes; the runtime owns the interpolated programs static analysis defers. A #[non_exhaustive] future permit form fails CLOSED.

Layer 2b — Discoverability + arg-injection lints (L0 nika-schema) #

one-obvious-way/008 (SHIPPED) warns when an interpolated value lands in a string command that needs no shell, pointing to the injection-safe array form — fires only when the literal parts carry no shell metacharacter (a genuine pipeline keeps the string form · low-false-positive).
arg-injection rule-pack (DESIGNED · the differentiator) — a clean-room catalog (from the public GTFOArgs + SonarSource/CAPEC-6 facts) of dangerous flags per binary; flags an interpolated value landing in a flag slot / a leading-dash value for a known binary, and recommends the -- end-of-options separator. No competing engine ships this.

Layer 3 — Env hygiene (L1 + L2 · SHIPPED · three sub-layers) #

Three sub-layers, weakest-to-strongest, each independent of the OS sandbox:

POSIX-name validation (L2 · `nika-verb-exec`). An env: key must match [A-Za-z_][A-Za-z0-9_]* — this refuses the dynamic-name carrier class, chiefly the exported-shell-function form BASH_FUNC_x%% that a bash sh -c child imports and runs (the payload never appears in the scanned command string). Empty / = / NUL keys still fail (a strict narrowing).
Dangerous-env denylist (L1 · `nika-exec-runner`). The runner ALWAYS strips the injection vectors that grant code/library injection with no dangerous flag: LD_PRELOAD, DYLD_INSERT_LIBRARIES, BASH_ENV, GIT_SSH_COMMAND, PYTHONSTARTUP, NODE_OPTIONS, IFS, plus HOSTALIASES / TERMINFO(_DIRS) / TERMCAP (file-read / crafted-entry load) — independent of pre_validated (the floor wins over an explicit set).
Ambient-secret scrub (L1 · `nika-exec-runner` ← composed by `nika-cli`). The engine loads provider API keys from ITS env (config_from_env) for its OWN inference calls; an exec child inherits them by ambient default and an untrusted command could exfiltrate them (printenv, cat /proc/self/environ). The composition root injects the provider-key NAMES (from the catalog) into TokioShell, which strips each from every child UNLESS the workflow set it EXPLICITLY in env: (explicit intent wins · only the ambient copy is removed). Least-privilege by default; empty scrub set = legacy behavior.

The stronger full clean-slate posture (drop ALL inherited env + a curated PATH) still ships with the sandbox (Layer 6), which knows the confined workflow's complete declared env needs; sub-layer 3 is the targeted secret-scrub floor that holds before the sandbox is composed in.

Layer 4/5 — Process lifecycle (L1 · SHIPPED partial) #

The child spawns in its own process group (the safe std process_group(0), no unsafe pre_exec); on timeout/cancel the whole group is signalled (SIGTERM → grace → SIGKILL via nix::killpg) so detached grandchildren die. Output is capped (64 MiB/stream) and the timeout hard-kills. Resource rlimits (RLIMIT_CPU/FSIZE/NPROC + no-core-dump) need a child-side pre_exec (unsafe), so they move to nika-sandbox (which owns the low-level confinement).

Layer 6 — OS sandbox (PER-PLATFORM L1 crates · macOS SHIPPED + verified) #

Reconciliation (2026-06-13). The kernel already RESERVES a capability Sandbox (plugin::sandbox · WASM/MCP · the enter() self-restriction model · v0.100), whose doc names the future impl crates nika-sandbox-landlock (Linux) and nika-sandbox-seatbelt (macOS). Confining the exec verb's CHILD process is a DISTINCT operation — "transform the command into its confined form" — so it rides a NEW additive kernel seam, NOT the reserved trait, and ships as the per-platform crates the reservation already names (operator-locked 2026-06-13: per-platform crates + a new trait · supersedes the original single nika-sandbox framing of this ADR).

The seam (L0.5 · `nika-kernel-core/src/io/command_sandbox.rs` · SHIPPED). A new CommandSandbox trait — sync, object-safe, confine(spec, ShellCommand) -> ShellCommand — plus SandboxSpec (fs_read/fs_write prefixes · allow_network · derived from permits.fs/net), CommandSandboxError (Unavailable/Profile · fail-closed), and a NoopSandbox (the explicit, auditable "unconfined" choice). Add a ShellCommand.sandbox field. The wrapper model (no unsafe, no FFI · the seam returns a TRANSFORMED command, not a pre_exec closure) replaces the original Confinement-closure design — it keeps the crates at unsafe_code = forbid and is what every coding-agent CLI uses.

macOS — `nika-sandbox-seatbelt` (SHIPPED · adversarially verified). Wraps a command in the OS-shipped sandbox-exec launcher with a deny-default SBPL profile generated from the spec: network denied unless granted; writes only under declared fs_write + scratch; reads of the system paths every binary needs, plus declared fs_read — so sensitive home paths (~/.ssh, ~/.aws) are denied. Profile-injection via a malicious path is closed (control-char refusal + quote-escaping). An adversarial jail suite RUNS sandbox-exec on darwin and proves: a home-secret read is denied, a declared path is readable, a write outside the allowlist is denied, an ordinary command still runs. Wired into TokioShell::with_sandbox (applied after the blocklist · fail-closed).

Linux — `nika-sandbox-landlock` (CI-GATED). The sibling crate: landlock (FS allowlist) + extrasafe/seccomp (block ptrace/unshare/AF_UNIX) + net-deny

rlimits, via bwrap or a Landlock helper. Only partly verifiable off a Linux box → a focused CI-backed arc. Same CommandSandbox seam.

Follow-on plumbing. Runtime derivation (permits.fs/net → SandboxSpec → ExecInput.sandbox) and composer injection (select + inject the platform backend into TokioShell) connect a workflow's permits: to confinement end-to-end; the composer is the nika-cli/engine surface (in flight).

Honest limits (documented in the crate): glob→subpath is a coarsening (path- prefix, not per-file); network is allow-all-or-deny (host-granular needs a proxy); resource rlimits + the SandboxEval egress suite are part of the landlock arc. Full 12-gate admission (Linux backend · mutation ≥90% · review swarm) is the CI completion.

Layer 7 — Blocklist demoted to a tripwire (L1 · SHIPPED) #

The string-matching blocklist is no longer the wall. Shell mode keeps the full battle-tested blocklist + the expansion-char refusal (the tripwire for the genuinely-dangerous string path). Array mode gets an exact-basename check_program against a small dangerous-program set (privilege escalation + system control) — no fake-shell scan, which removes the timeout/env/nice/ printenv false-positives. Per the adaptive-attack evidence, the blocklist is defense-in-depth, never the primary boundary.

Consequences #

Positive. The structural injection hole is closed; the safe form is the default and discoverable; the capability boundary is enforced; the env / process classes are shut; the sandbox (when shipped) makes "even if the blocklist misses it, it can't hurt you" true. The architecture matches the converging SOTA and stays 100% local/OSS (sovereignty). The permits: declaration unifies all enforcement (the file is the security boundary).

Negative / interim gaps (logged, not silent).

The argv program-floor no longer blocks a directly-authored dangerous command (e.g. a destructive rm on root) — that is gated by permits.exec + the sandbox, not the floor. Acceptable: the floor is identity-based; intent is policy + sandbox.
The OS sandbox (Layer 6) is the big remaining lift, cross-platform and only partly verifiable off a Linux box — a focused CI-backed admission arc.
Runtime taint propagation (which resolved values are interpolation-derived) is deferred — the arg-injection guard ships as a static lint; runtime taint-enforcement lands when the binding layer carries taint (shadow zone l1-taint-runtime).
Operator/host policy + token budgets remain nika-policy's job (gated on the kernel migration); the runtime permits enforcement is the interim.

Alternatives considered #

Blocklist-only (status quo). Rejected: both leaks and false-positives; the adaptive-attack literature refutes detector-as-boundary.
Container/microVM per exec (e2b, Firecracker). Rejected as the default: non-sovereign (hosted) or heavy startup latency; the agent-CLI OS-sandbox model fits a local-first engine better.
Sandbox as a module in nika-exec-runner. Rejected: heavy platform deps + unsafe pre_exec + independent adversarial testing → its own L1 crate behind a kernel seam is the Diamond-coherent shape.

Implementation status #

Layer · Crate(s) · Status
1 array execution · nika-verb-exec · nika-runtime · ✅ shipped
2 permits.exec · nika-runtime · ✅ shipped
2b /008 steer · nika-schema · ✅ shipped
2b arg-injection pack · nika-schema · ✅ shipped (arg-injection/001)
3 env POSIX-name validation · nika-verb-exec · ✅ shipped (kills `BASH_FUNC_x%%` carrier)
3 env dangerous-denylist · nika-exec-runner · ✅ shipped (+HOSTALIASES/TERMINFO/TERMCAP)
3 env ambient-secret scrub · nika-exec-runner ← nika-cli · ✅ shipped (provider keys · explicit `env:` wins)
3 env full clean-slate · nika-sandbox · 🔜 → L6 (drop-all + curated PATH)
4/5 process group · nika-exec-runner · ✅ shipped · rlimits → L6
6 sandbox seam · nika-kernel-core (CommandSandbox) · ✅ shipped
6 sandbox macOS · nika-sandbox-seatbelt · ✅ shipped · adversarially verified
6 sandbox wiring · nika-exec-runner (with_sandbox) · ✅ shipped
6 sandbox Linux · nika-sandbox-landlock · ✅ shipped · CI-gated (bwrap in the tests leg · 4 jail proofs)
6 permits→spec + composer inject · nika-runtime · engine · ✅ shipped (v0.105.x · dispatch derives the spec from `permits:` · the composer wires seatbelt/landlock · noop note when no backend)
7 blocklist tripwire · nika-exec-runner · ✅ shipped (mode-split)

References #

Spec: nika-spec spec/02-verbs.md §exec · spec/01-envelope.md §permits · spec/05-errors.md (NIKA-EXEC-001/002 · NIKA-SEC-001/004).
arXiv: 2302.12173 · 2208.03837 · 2503.18813 (CaMeL) · 2506.08837 · 2505.23643 (Fides) · 2504.11703 (Progent) · 2503.18666 (AgentSpec) · 2510.21236 (AgentBound) · 2411.07781 (RedCode) · 2504.00018 (SandboxEval) · 2503.00061 (adaptive attacks).
Catalogs: GTFOArgs · SonarSource argument-injection-vectors (CAPEC-6) · CVE-2024-24576 (BatBadBut · Windows guard).
Crates: landlock 0.4.5 · extrasafe · nix 0.30 · std CommandExt::process_group.
Related: ADR-001 (CRAFT) · ADR-003 (12-gate) · ADR-016 (cancellation) · ADR-080 (mcp-stdio sandbox) · ADR-081 (L1 guard contract).

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo