Crate kernex_sandbox 

kernex-sandbox

OS-level system protection for AI agent subprocesses.

Uses a blocklist approach: everything is allowed by default, then dangerous system directories and the runtime’s core data are blocked.

• macOS: Apple Seatbelt via sandbox-exec -p <profile> — denies reads and writes to {data_dir}/data/ (memory.db) and config.toml; denies writes to /System, /bin, /sbin, /usr/{bin,sbin,lib,libexec}, /private/etc, /Library.
• Linux: Landlock LSM via pre_exec hook (kernel 5.13+ minimum, 6.12+ for full ABI::V5 enforcement; older kernels apply best-effort protection using only the rights they support) — broad read-only on / with full access to $HOME, /tmp, /var/tmp, /opt, /srv, /run, /media, /mnt; restricted access to {data_dir}/data/ and config.toml.
• Other: Falls back to a plain command with a warning.

protected_command is best-effort and never fails: when the host cannot apply OS-level enforcement it returns an unsandboxed command after emitting a once-per-process stderr warning. For deployments where running unsandboxed is unacceptable, set SandboxProfile::require_os_enforcement = true (or export KERNEX_REQUIRE_SANDBOX=1, which applies process-wide without code changes) and call try_protected_command instead, which surfaces an std::io::Error when enforcement is unavailable. os_enforcement_available reports the host’s capability without building a command.

The fail-open fallback is the 0.x default; kernex 1.0 flips the library default to fail-closed (require_os_enforcement = true). Embedders that need today’s lenient behaviour at 1.0 will have to opt out explicitly.

Platform enforcement notes

• macOS: enforcement relies on /usr/bin/sandbox-exec, which Apple documents as deprecated but still ships and uses in its own tooling. There is no supported third-party replacement API. If a future macOS release removes it, os_enforcement_available returns false and the fail-mode policy above applies.
• Linux: Landlock enforcement depth depends on the kernel ABI (5.13 minimum; 6.7+ adds TCP restrictions; 6.12+ for ABI v5). On kernels between 5.13 and 6.11 some access rights cannot be enforced and the sandbox degrades to what the kernel supports; the ruleset status is logged at spawn time but is not observable programmatically by callers. os_enforcement_available reports Landlock presence, not enforcement depth.

Subprocess network policy

Sandboxed subprocesses are denied network access by default (SandboxProfile::allow_network = false); tools that genuinely need egress opt in explicitly. Coverage is asymmetric by platform:

• macOS Seatbelt: full — denies every socket operation (TCP, UDP, and local sockets; DNS resolution is consequently unavailable too).
• Linux Landlock: TCP bind/connect only, and only on kernels 6.7+ (ABI v4). Older kernels cannot restrict the network; the gap is logged at spawn time. UDP and non-TCP sockets are never restricted.

In-process HTTP performed by the runtime itself (e.g. a web_fetch tool implemented without a subprocess) is not subject to this policy; it has its own request-level validation.

Also provides is_write_blocked and is_read_blocked for code-level enforcement in tool executors (protects memory.db and config.toml on all platforms).

This crate is intentionally standalone with zero internal dependencies, making it usable outside the Kernex ecosystem.

Structs

SandboxProfile

Configuration for system sandbox restrictions.

Constants

BASE_ENV_ALLOWLIST

Environment variables preserved when hardening a spawned subprocess.

REQUIRE_SANDBOX_ENV

Environment variable that requires OS-level sandbox enforcement process-wide, equivalent to setting SandboxProfile::require_os_enforcement on every profile.

Functions

credential_read_deny_dirs

Credential directories/files under $HOME whose READS are denied to sandboxed subprocesses (the credential read-deny list).

enforcement_required

Returns true when OS-level sandbox enforcement is required, either by the profile flag or by the REQUIRE_SANDBOX_ENV environment variable.

hardened_env

Clear the inherited environment on cmd and re-apply only the minimal base allowlist (BASE_ENV_ALLOWLIST plus the LC_* family) from the parent process.

is_read_blocked

Check if a read from the given path should be blocked.

is_write_blocked

Check if a write to the given path should be blocked.

os_enforcement_available

Returns true when the current host can apply OS-level sandbox enforcement (Seatbelt on macOS or Landlock on Linux). Used by try_protected_command to honour require_os_enforcement.

protected_command

Build a Command with OS-level system protection (best-effort).

try_protected_command

Strict variant of protected_command.

write_allow_dirs

Directories whose WRITES are allowed under the default lockdown posture (writes are otherwise denied inside $HOME).