Feat/control socket introspection

[sachin2605]

Summary

Replaces the /dev/shm network_registry with a per-sandbox control socket architecture under /dev/shm/sandlock-$UID/<name>/. Every sandbox (CLI, Python SDK, embedded) gets its own runtime directory with a pid file and a Unix stream socket for introspection. Adds two new CLI subcommands (sandlock ps, sandlock config) and hardens sandlock kill against race conditions.

RFC: #68

Changes

New: per-sandbox runtime directory & control socket (control.rs)

• Atomic pid file (.pid.tmp → rename → pid) with dual-line format: child_pid\nsupervisor_pid\n
• Name collision detection: kill(supervisor_pid, 0) before overwriting an existing sandbox dir → ErrorKind::AlreadyExists
• 2-second minimum-age guard in list_live_sandboxes to prevent pruning a sandbox that's still starting up
• Server-side 64 KB response cap in write_response — oversized payloads return an error rather than being truncated silently
• Wire protocol: 4-byte BE length prefix + UTF-8 JSON, one client at a time per socket
• cleanup_runtime_dir best-effort teardown (called from Drop paths, never panics)

New CLI subcommands

• sandlock ps — lists all running sandboxes with NAME, PID, UPTIME, and CMD. Uptime is computed from /proc/<pid>/stat starttime vs /proc/uptime. CMD is read from /proc/<pid>/cmdline, truncated to 60 chars.
• sandlock config <name> — fetches the effective Sandbox policy from a running sandbox via control socket. Supports --toml for TOML output (round-trips through ProfileInput).

sandlock kill hardening

• Reads both PIDs from the dual-line pid file (child + supervisor)
• Liveness check via kill(supervisor_pid, 0) before attempting to kill
• killpg(child_pid, SIGKILL) + direct kill(supervisor_pid, SIGKILL) to cover the case where supervisor is in a different process group
• Backward-compatible: falls back to child_pid if pid file is old single-line format

control_socket opt-out knob

• New control_socket: bool field on Sandbox (default true, #[serde(skip)]) and SandboxBuilder
• When false, no runtime dir, pid file, or control-socket task is created — the sandbox is invisible to sandlock ps / sandlock config
• no_supervisor sandboxes create a control socket only when control_socket=true

network_registry removal

• Deleted network_registry.rs (146 lines) — the old /dev/shm/sandlock-$UID/network.json shared file with flock-based synchronization
• Removed port_remap registration path from main.rs (~60 lines of spawn+register+unregister logic)
• Moved format_net_rule and format_ports from main.rs into sandlock-core as public free functions so sandlock config can serialize NetRules to TOML/JSON without duplicating rendering logic
• sandlock_cli_test.rs: ported all tests to use sandlock_core::format_net_rule
• Name auto-generation moved from network_registry::next_name() into sandlock-core (sandbox_ prefix + PID + counter in sandbox.rs do_create_stdio/no_supervisor path)

Integration tests (10 new control socket tests)

• test_control_setup_and_cleanup — runtime dir created with pid file and socket, cleaned up on shutdown
• test_control_config_verb — control socket serves effective policy as JSON
• test_control_config_verb_toml — control socket serves effective policy as TOML
• test_control_unknown_verb — unknown verb returns error response
• test_control_list_live — list_live_sandboxes discovers running sandboxes
• test_control_name_collision — duplicate name with live supervisor returns AlreadyExists
• test_control_prunes_stale_dirs — dead supervisor dirs are removed
• test_control_prunes_stale_dirs_via_cli — CLI path also prunes dead dirs
• test_control_no_supervisor — no_supervisor sandboxes still get a control socket
• test_control_socket_disabled — control_socket: false skips runtime dir entirely

Documentation

• README.md — sandlock list replaced with sandlock ps and sandlock config examples
• docs/sandbox-reference.md — no_supervisor added to Python synopsis, TOML profile example, and [program] field table; control_socket added to Runtime kwargs table

Files changed

15 files, +1,787 / −290

File	Δ
crates/sandlock-core/src/control.rs	+583 (new)
crates/sandlock-core/src/profile.rs	+204
crates/sandlock-core/src/sandbox.rs	+109
crates/sandlock-core/src/sandbox/builder.rs	+77/−10
crates/sandlock-core/src/seccomp/state.rs	+12
crates/sandlock-core/src/lib.rs	+3/−3
crates/sandlock-core/tests/integration/test_control.rs	+328 (new)
crates/sandlock-core/tests/integration.rs	+3
crates/sandlock-cli/src/main.rs	+304/−240
crates/sandlock-cli/src/network_registry.rs	−146 (deleted)
crates/sandlock-cli/tests/cli_test.rs	+270
crates/sandlock-cli/Cargo.toml	+1
Cargo.lock	+1
README.md	+29/−9
docs/sandbox-reference.md	+4

Test plan

• Core lib unit tests: 51/51 pass
• Core integration tests: 302/302 pass (includes 10 control socket tests)
• CLI integration tests: 28/30 pass (2 pre-existing UID mapping failures, unrelated)
• Profile integration tests: 6/6 pass

Design decisions

1. Dual PIDs — pid file stores both child and supervisor PIDs so sandlock ps can read /proc/<child_pid>/stat for uptime while sandlock kill can target the supervisor (which owns the socket)
2. Atomic pid file — temp+rename prevents list_live_sandboxes from seeing a partially-written pid file during sandbox startup
3. Name collision detection — kill(supervisor_pid, 0) before overwriting prevents accidentally reusing a name that's still running
4. 2-second pruning guard — prevents list_live_sandboxes from pruning a sandbox that was created microseconds ago
5. 64 KB response cap — server-side cap prevents accidental large payloads from blowing up buffer allocations
6. control_socket: bool opt-out — gives callers who don't want introspection overhead a clean escape hatch

[congwang-mk]

Thanks for the PR!

Just design-level review. Layering looks right: control.rs holding the dir helpers, server loop, and client helper means the CLI has no duplicated wire logic. Dedicated tokio task instead of folding accept() into the notify loop is the correct answer to RFC open question 2. Snapshot + read-dynamic-denies-at-request-time correctly avoids the stale-file problem the RFC calls out.

Five things worth resolving before merge:

1. pid file and socket refer to different processes. setup_runtime_dir(name, pid) gets the forked child pid, but the socket is served by the supervisor. ps liveness, kill, UPTIME, and CMD all key off the child; config keys off the supervisor. If the supervisor dies while the child lives, the sandbox still lists but config fails with a raw connect error. Write both pids, or pick one and document which.

2. Name collision silently destroys a live sandbox. setup_runtime_dir does an unconditional remove_dir_all. Two sandboxes named web: the second wipes the first's pid file and socket, the first disappears from ps, kill web hits the second, and the second's Drop removes the dir while the first is still running. Needs a liveness check and a hard error on collision.

3. Pruning races startup. list_live_sandboxes deletes any dir without a parseable pid file. setup_runtime_dir creates the dir, then writes pid, then binds. A concurrent sandlock ps in that window deletes the runtime dir of a sandbox that is coming up fine. Fix with temp+rename for the pid file, or only prune dirs past a minimum age.

4. The 64 KB cap is client-side only. send_control_request rejects responses over 65536 bytes; the server never caps what it writes. A policy with many fs rules produces a config that is sent successfully and cannot be read. Cap both ends or neither.

5. No opt-out. Every Sandbox, including embedded users who never asked for introspection, now creates a /dev/shm dir and a tokio task, with best-effort failures going to stderr. Worth a builder knob, particularly for nested-sandbox and library contexts where that warning is pure noise.

[congwang-mk]

Thanks for the rework. Points 1, 3, 4, 5 from my previous review are properly addressed (two-line pid file with supervisor liveness, temp+rename plus the 2s grace, server-side cap, control_socket knob), and the tests cover them. Three things still need to change before merge:

1. Removing network_registry loses port discovery entirely (blocking). The remapped port is only knowable at runtime, so the old virtual -> real column in list was the only way for a user to find which host port to connect to. ps now shows no PORTS at all, which breaks the port-remap workflow. Please add a ports verb on the control socket answering from Sandbox::port_mappings() at request time (more accurate than the registry, which only refreshed on on_bind and went stale on SIGKILL), and have ps restore the PORTS column by querying each live sandbox's socket, printing - when the socket is missing. Dropping the allowed-hosts column is fine since that is static config visible via sandlock config.

2. The name-collision fix misses the no_supervisor path. setup_runtime_dir now checks liveness and returns AlreadyExists, good. But the if no_supervisor && self.control_socket block in do_spawn still does an unconditional remove_dir_all with no liveness check, then sets control_dir so its own Drop removes the dir: a --no-supervisor sandbox named the same as a live sandbox wipes the live one's pid file, which is exactly the scenario from my earlier comment, just moved to one path. Share the setup_runtime_dir logic (minus the socket) instead of duplicating it; that also fixes the missing 0700 chmod there. Relatedly, in the supervisor path please hard-fail the spawn on ErrorKind::AlreadyExists specifically; best-effort-and-warn is right for restricted /dev/shm, but a collision should not leave a second sandbox running invisible to ps.

3. proc_cmdline can panic. &joined[..57] slices at a byte offset, so a multi-byte UTF-8 character spanning byte 57 makes sandlock ps panic. Truncate on a char boundary.

Smaller items, fine as part of this PR or a fast follow-up:

• #[serde(skip)] on control_socket deserializes to false. All current paths go through the builder so nothing breaks today, but any future serde round-trip of Sandbox silently disables introspection. Use skip_serializing plus default = "..." returning true, or drop the skip.
• sandlock kill SIGKILLs the supervisor, so cleanup never runs and the runtime dir lingers until the next ps prunes it. Call cleanup_runtime_dir from the kill command.
• send_control_request has no connect/read timeouts; a wedged supervisor blocks the CLI forever.