Isolate AI‑written code at the kernel, and tell the agent why it failed.
SentinelBox isolates execution with Linux namespaces, OverlayFS, seccomp USER_NOTIF and cgroup v2. Every blocked syscall is turned by a Rust monitor into feedback the agent can act on, and exposed over the Model Context Protocol.
- Model Context Protocol
- Rootless · Linux 5.15+
- C · Rust · TypeScript
$ bash scripts/run.sh -- /bin/sh -c "nc -w1 example.com 80"
[sentinelbox] profile=strict rootfs=./rootfs/busybox
[sentinelbox] clone child: user·pid·mnt·net·uts·ipc·cgroup
[monitor] policy loaded rules=28 db=WAL
[sentinelbox] seccomp listener ready → notify_fd via SCM_RIGHTS
socket(AF_INET, SOCK_STREAM, 0) ⟶ USER_NOTIF
[SEMANTIC] 安全違規:嘗試在 profile「strict」內建立 socket(family=2)。
HINT → 改用沙盒外預先準備好的資料;本 profile 禁止任何網路連線。
nc: socket: Operation not permitted
[monitor] summary: mem_peak=… KiB cpu_total=… ms
- namespaces from a single clone()
- 7
- namespaces from a single clone()
- seccomp actions: ALLOW · ERRNO · NOTIFY · KILL
- 4
- seccomp actions: ALLOW · ERRNO · NOTIFY · KILL
- cgroup v2 sampling interval
- 100 ms
- cgroup v2 sampling interval
- dangerous capabilities dropped, incl. bounding set
- 13
- dangerous capabilities dropped, incl. bounding set
01
A plain sandbox returns an error code. The agent is left guessing.
“Operation not permitted” or “Killed” tells an LLM almost nothing: a bug, a missing permission, or a policy decision? SentinelBox knows the exact syscall and rule at the moment of interception, so it can answer why and what to change, closing the execute → fail → feedback → repair loop.
- NOTIFY
socket(AF_INET, …)nc: socket: Operation not permitted
Security Violation: Attempt to create a socket (family=2) under profile 'strict'.
HINT Use data prepared outside the sandbox; this profile forbids any network connection.
- KILL
mount("proc", …)Killed exit 137
Action Denied: Filesystem/namespace mutation (mount) is forbidden.
HINT The sandbox rootfs is a read-only overlay; remounting is neither needed nor allowed.
- KILL
memory.max exceededKilled exit 137
Resource exhausted: the process exceeded its memory limit and was killed by the kernel (cgroup memory.max violation).
HINT Check for memory leaks, or raise memory.max in the profile.
02
Four processes, each guarding one layer in the language that suits it.
C handles kernel-facing isolation, Rust makes security decisions and keeps the audit trail, TypeScript hands results to the AI, and the web tier provides observability. Hover or select a component, or play through one complete run.
← Swipe to see the whole diagram →
03
One run, from clone() to rmdir.
The order is part of the security design: uid_map is written before the child continues, privileges drop before seccomp is installed, and execvp comes last. Each step maps to an actual call in the source.
01Setup
Parent
Load the profile, create the sentinelbox.<pid> cgroup and write memory.max, cpu.max and pids.max.
Parent → Monitor
Create a socketpair and fork-exec the monitor; the socket is dup2’d to fd 3, cgroup path and profile go in env vars.
Parent → Child
clone() creates the user, pid, mount, net, uts, ipc and cgroup namespaces in one call.
Parent → Kernel
The parent writes setgroups=deny, uid_map and gid_map, then adds the child to cgroup.procs.
Parent → Child
Send the child’s host PID over the sync pipe, releasing the child.
02Isolate
Child
Become uid 0 inside (an unprivileged user on the host) and disable core dumps.
Child → Kernel
Mount tmpfs and overlay, pivot_root and detach the old root, then mount /proc (rbind when nested).
Child
Set the hostname and PR_SET_NO_NEW_PRIVS, then drop 13 capabilities from effective, permitted, inheritable and bounding sets.
Child → Kernel
Install the profile’s seccomp filter and obtain the USER_NOTIF listener fd.
Child → Monitor
Pass notify_fd plus "PID:<pid>|CMD:<argv>" to the monitor with sendmsg(SCM_RIGHTS).
Child
execvp() the target; every later syscall goes through the filter.
03Supervise
Kernel → Monitor
A syscall matching a NOTIFY / KILL rule is parked and delivered to the monitor.
Monitor → Kernel
Reply per policy (CONTINUE or −EPERM, plus SIGKILL for KILL rules) and write the audit record.
Monitor
The telemetry thread reads memory.current and cpu.stat every 100 ms into resource_samples.
04Teardown
Kernel → Parent
The child exits; wait4() returns status and rusage together (the fallback when cgroup stats are unavailable).
Kernel → Monitor
notify_fd reports POLLHUP; the monitor records the end and checks memory.events for an OOM kill.
Parent
Wait for the monitor, print the resource summary and remove the cgroup.
04
The same syscall takes a different path under each profile.
Pick a profile and a syscall to see where it is decided, what the process actually receives and which feedback the AI gets. Rules and wording come straight from profiles/*.json and mappings/syscall_feedback.json.
Dots show the action under this profile: ALLOWERRNONOTIFYKILL
socket()strictNOTIFYlisted in the profile’s syscall_rules
policy.lookup("socket") → NOTIFY; written to syscall_events (signal_name = EPERM).Semantic feedback for the AI
[SEMANTIC] Security Violation: Attempt to create a socket (family=2) under profile 'strict'.
HINT → Use data prepared outside the sandbox; this profile forbids any network connection.
The monitor prints the Chinese message and hint; the English text here comes from the mapping’s en field and a translated hint.
Rules and messages are read from the main branch of mcp-sentinel-box on GitHub (refreshed hourly). profiles/ · syscall_feedback.json
05
Six stacked layers, so no single failure opens the box.
Isolation never relies on one mechanism. Even if a syscall rule is missing, the process is still inside its own namespaces, a read-only root, stripped capabilities and cgroup limits.
- L1
Namespaces
- user, pid, mount, net, uts, ipc and cgroup from one clone()
- uid 0 inside is an unprivileged host user (rootless)
- setgroups=deny is written before gid_map
core/src/sandbox.c
- L2
Filesystem
- OverlayFS: read-only busybox lower + tmpfs upper; writes vanish with the sandbox
- pivot_root + MNT_DETACH instead of chroot, so there is no way back out
- Root propagation set to private so mounts never leak to the host
core/src/overlayfs.c
- L3
Privileges
- PR_SET_NO_NEW_PRIVS: setuid binaries cannot gain privileges
- 13 dangerous capabilities dropped, including the bounding set
- PR_SET_DUMPABLE = 0 so no core dump can leak memory
core/src/capability.c
- L4
Syscalls
- seccomp-BPF with SECCOMP_RET_USER_NOTIF instead of ptrace
- ALLOW rules are added first so hot syscalls pass early
- KILL compiles to NOTIFY: record first, then terminate
core/src/seccomp.c
- L5
Resources
- cgroup v2: memory.max, cpu.max, pids.max (stops fork bombs)
- A dedicated cgroup per run, removed when it ends
- oom_kill in memory.events becomes a semantic OOM event
core/src/cgroup.c
- L6
Audit
- Every interception is stored in SQLite with the errno symbol and semantic text
- WAL + synchronous=NORMAL + 5 s busy_timeout
- Executions, events and samples, all timestamped in ms
monitor/src/db.rs
Three built-in profiles
A profile is one JSON file shared by the C core and the Rust monitor: the core installs the seccomp filter and cgroup limits from it, the monitor makes decisions from it.
strict
defaultDefault. Blocks network calls and kernel-sensitive syscalls; every violation is reported to the monitor.
- memory.max
- 128 MiB
- cpu.max
- 0.5 CPU
- pids.max
- 32
profiles/strict.json · default_action: ALLOW
datascience
More memory and CPU; connect / bind are intercepted while local sockets stay usable.
- memory.max
- 1 GiB
- cpu.max
- 2 CPU
- pids.max
- 128
profiles/datascience.json · default_action: ALLOW
web
For web agents: outbound sockets allowed by policy; inbound bind / listen / accept are intercepted.
- memory.max
- 256 MiB
- cpu.max
- 1 CPU
- pids.max
- 64
profiles/web.json · default_action: ALLOW
Rules and messages are read from the main branch of mcp-sentinel-box on GitHub (refreshed hourly). profiles/ · syscall_feedback.json
06
Every interception and resource curve is left as a queryable record.
The audit store is SQLite in WAL mode, so the monitor can keep writing while the bridge, dashboard and MCP side read concurrently. Values are stored raw with millisecond timestamps; conversion happens at the edge.
syscall_events
One row per NOTIFY / KILL interception
- exec_idFK
- tsms
- syscall_nrx86_64
- syscall_name
- actionNOTIFY | KILL
- errno
- signal_nameEPERM | SIGKILL
- semantic_msg
- remediationhint
executions
One row per sandbox run
- idPK
- profile
- pidhost
- commandargv
- start_tsms
- end_tsNULL = running
- status
resource_samples
One row every 100 ms
- exec_idFK
- tsms
- mem_bytesmemory.current
- cpu_useccpu.stat
- cpu_pctΔ / interval
- 100 ms
- The sampler keeps memory.current and cpu.stat open and seeks back each tick instead of reopening.
- cpu_pct
- Computed from the usage_usec delta over the real elapsed time; can exceed 100% on several cores.
- fallback
- Without cgroup delegation it reads /proc/stat and /proc/meminfo; the core also fills totals from wait4() rusage.
- OOM
- At exit it reads oom_kill from memory.events and records a semantic event if the kernel OOM-killed the run.
Last five intercepted syscalls
SELECT datetime(e.ts / 1000, 'unixepoch') AS at,
x.profile, e.syscall_name, e.action,
e.signal_name, e.semantic_msg
FROM syscall_events e
JOIN executions x ON x.id = e.exec_id
ORDER BY e.id DESC
LIMIT 5;PRAGMAs: journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000. The monitor and sampler share one connection behind Arc<Mutex> so writers never contend.
07
Plug into any agent that speaks MCP.
The MCP server runs over stdio and exposes two tools. After a failed run the agent calls them for the cause and a repair direction, rewrites its code and retries, without a human in the loop.
translate_error
Turns low-level signals (signal / errno / syscall / path) into an explanation an AI can use.
- signal?
- errno?
- syscall?
- path?
- details?
suggest_repair
Suggests how to change the code, given the blocked syscall and the active profile.
- syscall
- original_code
- profile?
claude_desktop_config.json
{
"mcpServers": {
"sentinelbox": {
"command": "node",
"args": ["/path/to/mcp-sentinel-box/mcp-server/dist/index.js"]
}
}
}→ tools/call translate_error{ "errno": "EPERM", "syscall": "socket" }← Security Violation: Operation not permitted. You are tryingto access a restricted resource. The violation occurredduring the `socket` system call.→ tools/call suggest_repair{ "syscall": "connect", "profile": "strict","original_code": "requests.get(url)" }← Based on the blocked syscall 'connect', here is the repairstrategy: The code attempts to access the network. In the'strict' profile, networking is disabled.Repair Suggestion: Replace network requests with local mockdata or read from a pre-mounted dataset in the workspace.…
08
Why it is built this way, and not the obvious way.
Each trade-off below is documented in the source comments, and together they are what separates SentinelBox from “just wrap it in Docker”.
SECCOMP_RET_USER_NOTIF
over ptrace / SECCOMP_RET_TRACENo tracer sits on every syscall: ALLOW is decided inside the kernel’s BPF program and only matching calls reach the monitor through a single fd.
core/src/seccomp.c
clone(CLONE_NEW* …)
over unshare()The child is born inside every namespace: one fewer transition and no window where it runs before isolation.
core/src/sandbox.c
pivot_root + MNT_DETACH
over chrootchroot can be escaped; pivot_root swaps the whole root and detaches the old one, so no path back to the host exists.
core/src/overlayfs.c
tmpfs upper layer
over disk-backed writesAll writes land in memory; resetting the sandbox means discarding the tmpfs, with no persistent cleanup.
core/src/overlayfs.c
wait4()
over waitpid()Exit status and rusage (CPU time, max RSS) in one call: cheapest for short-lived AI code runs.
core/src/sandbox.c
poll() → NOTIF_RECV
over blocking ioctlIf the sandbox exits without ever triggering NOTIFY, a blocking RECV may never wake; polling first lets POLLHUP end the loop cleanly.
monitor/src/main.rs
sendmsg left unfiltered
over blocking every socket callnotify_fd itself is sent with sendmsg(SCM_RIGHTS); filtering it would deadlock the child on its own filter. Blocking socket() / connect() already cuts the network.
profiles/strict.json
C core + Rust monitor
over one processKernel-facing setup is most direct in C; the decision loop that handles raw fds and ioctls gets Rust’s borrow checker. They share only inherited fds and env vars.
monitor/Cargo.toml
09
Three commands to run it on your own Linux box.
Inside Docker, VS Code Dev Containers or some WSL2 setups, cgroups cannot be delegated and telemetry degrades to host-wide sampling; the sandbox still runs. For exact per-sandbox limits, run scripts/setup_cgroup.sh on native Linux.
- 1
Clone and provision
Installs dependencies, builds the C core and Rust monitor, and creates the busybox rootfs.
git clone https://github.com/Ming874/mcp-sentinel-box.git cd mcp-sentinel-box bash scripts/provision.sh - 2
Start the dashboard
The bridge listens on 3001 and the dashboard on 3000, attached to sentinelbox.db.
./scripts/start_monitoring.sh # open http://localhost:3000 - 3
Run code in the sandbox
In another terminal; switch profiles with an environment variable.
bash scripts/run.sh -- /bin/sh -c "echo hello from sandbox" bash scripts/run.sh -- /bin/sh -c "nc -w1 example.com 80" SENTINELBOX_PROFILE=datascience bash scripts/run.sh -- /bin/sh -c "free -m"
See it run
From blocking a network call to live resource charts and an agent correcting itself.
Status & roadmap
- Phase 1 · Container primitives: namespaces, pivot_root, OverlayFS, cgroup v2, libcap
- Phase 2 · Security sentinel: Rust, seccomp USER_NOTIF, SCM_RIGHTS
- Phase 3 · Telemetry & database: cgroup v2 sampling, SQLite WAL audit
- Phase 4 · MCP integration: TypeScript SDK, self-repair loop
- Phase 5 · Management UI: React, Tailwind, Socket.io
- eBPF probes (aya, execve tracepoint, cgroup_skb); monitor/src/ebpf is a placeholder today
- veth plus an egress allow-list so the web / datascience network policy takes effect
- Read path arguments via /proc/<pid>/mem to fill syscall_events.path
- MCP tools that query the audit database and share syscall_feedback.json
- Syscall tables beyond x86_64 (aarch64)