Repository navigation
Description
Tracker in OpenHuman: tinyhumansai/openhuman#7328 · Policy side: tinyhumansai/tinysecurity#1
Goal
tinybox focuses purely on sandboxing. It owns isolation and confinement of code the host does not trust: what a box can touch (filesystem, network, processes, resources) and the backends that enforce it. It owns no policy, approval, audit-decision, redaction or command-classification logic. The new tinysecurity module decides what may run and emits a SandboxPlan; the host maps the plan onto a tinybox BoxSpec/Placement; tinybox enforces it or refuses with Unsupported.
Audit: how OpenHuman uses tinybox today (pin 392a1f0, ~v0.1.15)
Used:
tinybox-jail: re-exported ascwd_jail(crates/openhuman-core/src/sandbox/mod.rs:16);default_backend,spawn_with,Jail,NoopBackend(sandbox/ops.rs).tinybox-docker:OneShot/DockerCli(sandbox/docker.rs).tinybox_core::shell::{classify,scan,env_guard,executor}(security/policy/command_checks.rs): this is policy, not sandboxing; see Phase 5.- The app's optional
gatewaysfeature:DockerSandbox,LocalHost,SshHost(openhuman-app/src/gateway/provision.rs).
Never used: tinybox-linux (bwrap namespaces), tinybox-microvm, tinybox-sync, BoxSpec/Resources/NetworkPolicy/SandboxCapabilities, snapshot/fork, and tinybox-module (bus contract exposes only Describe).
Code that spawns untrusted work with no tinybox isolation (policy only): cron shell jobs (cron/scheduler/shell_job.rs), tinymcp stdio servers, tinyruntime pools/pyserver, tinyagents command hooks, the tinyflows script runner, agent/host_runtime.rs native shells, install_tool, browser/tinycomputer helper processes.
Duplication/drift: agent/host_runtime.rs:181 hand-builds docker run instead of OneShot; config accepts Firejail/Bubblewrap with no backend behind them; agent/platform_shell.rs is a separate shell builder.
Silent Noop: with no usable OS jail, commands run unconfined and report Inactive (sandbox/ops.rs ~200–240). Untrusted tiers must fail closed instead.
Housekeeping: workspace manifest says 0.1.5 while tags are ~0.1.15.
Step-by-step plan
Phase 1: Capability honesty and fail-closed preflight
- Every backend (
jailLandlock/Seatbelt/AppContainer/Noop,docker,namespace,microvm) declares inSandboxCapabilitiesexactly which limits it enforces: filesystem allow/deny, network (none/egress/allowlist), pids, cpu, memory, disk, subprocess spawn. - Add
Sandbox::plan_check(&BoxSpec) -> Result<Enforcement, Unsupported>that reports per requested constraintEnforced | BestEffort | Unsupported.require(&spec)refuses when any hard constraint isUnsupported. ANoopbackend isIsolationLevel::Noneandis_suitable_for_untrusted_code() == false; callers can detect it without string matching onUNSUPPORTED_BACKEND_NAME. - Tests: each backend × each constraint table-driven; refusal is a typed
Error::Unsupported{backend, constraint}.
Phase 2: Jail resource limits and parity
- Linux: cgroup v2 (cpu/memory/pids) where delegated;
setrlimitfallback; clear error when neither is available. - Windows: Job Objects for memory/cpu/process count and kill-on-close; AppContainer capability set minimized (no network capability unless requested); registry and named-pipe access denied.
- macOS: Seatbelt profile generation with deny-default;
setrlimit; documented gaps (no cgroups). - Landlock ABI detection and graceful path: when the kernel lacks needed ABI (e.g. network rules, <6.7), report
BestEffortand recommend the namespace backend instead of silently dropping. - Tests per OS (see matrix): allowed read/write works; denied read/write fails; subprocess denial; limits actually trip (allocation bomb, fork bomb, CPU spin) and emit
LimitHit.
Phase 3: Network policy v2
- Extend
NetworkPolicywithAllowlist{hosts, ports}(keepDenied,Egress,Open;Open/host-network is flagged as the highest-risk setting). - Linux: network namespace + nftables rules, or an in-box egress proxy with SNI/host matching; document DNS handling (resolve outside, pin inside).
- macOS: Seatbelt
network-outboundrules by host/port; where Seatbelt cannot express a host allowlist, route via a local proxy and say so in capabilities. - Windows: AppContainer network capabilities + Windows Filtering Platform rules (or proxy fallback);
BestEffortwhere unsupported, never silent. - Docker: user-defined network + egress proxy sidecar or iptables, per platform (Docker Desktop on macOS/Windows behaves differently from native Linux; test both).
- Tests: allowed host reachable, other host blocked, DNS rebinding case, loopback/metadata (
169.254.169.254) blocked.
Phase 4: Namespace and microvm backends
tinybox-linux: add a seccomp allowlist, Landlock inside bwrap, and the persistent-namespace mode (ROADMAP "Deferred").tinybox-microvm: KVM availability probe (/dev/kvm, permissions) surfaced through capabilities; an artifact export path (guest writes currently never come back); document and measure cold-start; evaluate a warm-pool daemon behind a feature.- Make bwrap discoverable: capability reports whether
bwrapexists and whether unprivileged user namespaces are enabled (Ubuntu 24.04 AppArmor restriction!), with an actionable error. - Tests on Linux runners: namespace isolation (pid/net/mount), seccomp blocks a forbidden syscall, microvm job on a KVM-capable runner (or reported skip).
Phase 5: Scope cleanup: remove policy from tinybox
tinybox_core::shell::{classify, scan, env_guard}is command policy. Move it totinysecurity-policy(Build tinysecurity: one bus module for policy, approvals, auto-approve, audit, redaction and sandbox planning tinysecurity#1, Phase 2/T2). Here: deprecate with a thin re-export for one release, then delete.- Document the boundary in
AGENTS.md/README: tinybox accepts a plan, enforces it, reports events; it never decides what is allowed.
Phase 6: Structured events
SandboxEvent { Started, Denied{kind,target}, LimitHit{limit}, Exited{status} }via a callback/stream onspawn/exec. No policy; purely observational so the caller can audit (tinysecurity-audit gets them from the host).- Denial attribution where the OS allows it (Landlock/Seatbelt log, AppContainer ETW or access-denied mapping);
BestEffortotherwise.
Phase 7: Bus contract
- Extend
tinybox-busbeyondDescribe:Capabilities,Plan/Check,Create,Exec,Destroy(+ event stream). Contract version bump,MODULE.md, host bind rule. - Decide and document who executes: OpenHuman host spawns child processes in-process through
tinybox-jail/dockertoday. The module contract must support both paths without sharing dependencies with the host.
Phase 8: Release hygiene
Cut a release so tags and workspace version agree; publish checksum.toml; per-host archives for the full release matrix.
OpenHuman adoption (tracked in tinyhumansai/openhuman#7328)
SandboxPlan → BoxSpec adapter; replace agent/host_runtime.rs DockerRuntime with OneShot; wire the namespace backend so Firejail/Bubblewrap config values work or are removed; route cron shell, tinymcp stdio, tinyruntime pools, command hooks and the tinyflows script runner through the jail at minimum; route untrusted sources (MCP-installed servers, downloaded skills) to microvm where KVM exists; fail closed on Noop for untrusted tiers; OPENHUMAN_SANDBOX=off never applies under SaaS.
Cross-OS end-to-end tests (required)
Real backends on real runners, no mocks of OS isolation. Matrix: ubuntu-24.04, ubuntu-22.04, macos-15/macos-26, windows-2025/windows-11-arm, plus a KVM-capable Linux job for microvm. Every skip is listed per OS with a reason; a skip is never silent.
| Area | Linux | macOS | Windows |
|---|---|---|---|
| Jail fs | Landlock allow/deny; old-ABI fallback to bwrap | Seatbelt allow/deny; /private symlinks; case-insensitive APFS |
AppContainer allow/deny; UNC, \\?\, 8.3 names, reserved names |
| Jail process | no-subprocess; fork bomb trips pids |
no-subprocess; setrlimit trips |
Job Object kill-on-close; process-count limit |
| Resource limits | cgroup v2 mem/cpu/pids; rlimit fallback | rlimit; documented gaps surfaced in capabilities | Job Object mem/cpu |
| Network | netns + allowlist; metadata IP blocked; DNS rebinding | Seatbelt/proxy allowlist | AppContainer/WFP/proxy allowlist; IPv6 |
| Namespace | bwrap pid/net/mount, seccomp, AppArmor userns restriction on 24.04 | clean Unsupported |
clean Unsupported |
| MicroVM | Firecracker boot, exec, artifact export (KVM job) | clean Unsupported |
clean Unsupported |
| Docker | native Docker limits | Docker Desktop / Colima | Docker Desktop (Linux containers); path translation |
| Noop / fail-closed | untrusted tier refused when no jail | same | same (no AppContainer ⇒ refuse) |
| Events | Denied/LimitHit observed |
same, with documented gaps | same, with documented gaps |
Definition of done
- Capability table is truthful and tested per OS; untrusted-tier requests never silently run unconfined.
- No policy, approval, audit-decision or classification code remains in tinybox.
- Three-OS e2e green in CI; release published with
checksum.toml. - OpenHuman consumes
BoxSpec/NetworkPolicy/Resources, and its duplicate Docker wrapper is gone.
Activity
senamakel commentedon Oct 15, 2026
Host tracking: PR #85 (network allowlist policy, sandbox events, contract 1.19) is released in tinybox 0.1.34, pinned by tinyhumansai/openhuman#7331. Host sandbox-plan migration (phase 5 of tinyhumansai/openhuman#7328) is not yet done.
senamakel commentedon Oct 24, 2026
OpenHuman epic #7328 acceptance update (2026-10-24)
The following AppContainer acceptance changes have merged to
senamakel/tinybox:epic/7328-security-bus:e9c7d369b617ceb04a5873625e316bdfe5ef6410: denies an outside-file read through a Windows\\?\verbatim path.dd0107e67ae068b5af790adc754579a1e353405f: denies parent traversal to a sibling secret.975df572ab61be3944ffd5c7a4321b91fa8fdffb: runs the required filesystem, network, process and memory AppContainer probes on Windows 11 ARM64, and confirms CPU stays Unsupported. Each PR passed all 20 hosted checks.PR #58 is open at
85af375520d7ef32064def33a2288754bf096ea2. It adds a live 8.3 short-name alias denial proof on Server 2025 x64 and Windows 11 ARM64. The dedicated x64 AppContainer and full ARM64 acceptance lanes passed. The first full run had one unrelatedtinybox-sshtiming test exceed its 10-second bound on Server 2025; attempt 2 is rerunning that lane. The broader issue remains open for network/resource/event/bus and release acceptance. Windows CPU remains Unsupported.senamakel commentedon Oct 24, 2026
OpenHuman epic #7328 acceptance update (2026-10-24)
TinyBox fork-epic PR #58 merged at
bab4731aa49659171c26765b076ed760a271d9f5from exact head85af375520d7ef32064def33a2288754bf096ea2. Its live AppContainer test proves an outside secret is unreadable through its Windows 8.3 short-name alias. It runs on Windows Server 2025 x64 and Windows 11 ARM64; all 20 hosted checks passed on run 40071995370, attempt 2. Attempt 1's failure was an unrelated 10-second SSH timing test and passed on rerun.This joins PRs #55 (verbatim DOS path), #56 (parent traversal), and #57 (Windows 11 ARM64 AppContainer acceptance), all merged to the fork epic. TinyBox #27 remains open for broader network, resource/event, bus-contract and release acceptance. Windows CPU enforcement remains typed
Unsupported.M3gA-Mind commentedon Nov 11, 2026
The contract types for every phase are on main: capability honesty (#28), network policy + events (#85), deny_read (#87) and resource limits + contract 2.3 (#140).
What's left is host adoption. OpenHuman still sends
resources: None(sandbox/native_jail.rs:96) and doesn't consume sandbox events, and that belongs in a separate OpenHuman issue.Two phases aren't enforced in tinybox yet either: no backend enforces
NetworkPolicy::Allowlist, and nothing emitsSandboxEvent::Denied. Suggest narrowing this tracker to those (plus bwrap limits) rather than closing it.Enforce Docker network allowlists where the host can, and say why not
M3gA-Mind commentedon Nov 12, 2026
Closing: the tinybox side of this tracker is on main.
disk_bytesis optional (Make a resource budget's disk limit optional (contract 2.6) #159, contract 2.6). Seatbelt and Landlock hold no resource limits and refuse hard ones.Deniedis reserved and documented as never sent (Report memory and pid limit hits from the scope, and say Denied is never sent #168).Two items of the definition of done are not finished and continue outside this issue:
checksum.toml, but main is well past it (contract 2.6 against 2.4 in that release). The next release from main carries the work above.BoxSpec/NetworkPolicy/Resourcesand dropping its Docker wrapper is host-side work. The tracker named in this issue, openhuman#7328, is closed, so that item needs a new OpenHuman issue.