feat(seccomp): ExtraHandler — user-supplied syscall handlers

[dzerik]

Summary

Adds a public extension point for downstream crates that need to register their own seccomp-notification handlers alongside sandlock's builtin chroot/cow/procfs/network/port_remap logic.

Motivation. Downstream crates that want to intercept additional syscalls in the same supervisor task as sandlock's builtins have no clean way to do it today — one SECCOMP_FILTER_FLAG_NEW_LISTENER per process means a single listener, so a second supervisor cannot run alongside. The only alternative is forking sandlock or patching notif::supervisor wholesale.

API.

• New type dispatch::ExtraHandler { syscall_nr, handler }.
• New entry Sandbox::run_with_extra_handlers(policy, cmd, extras).
• Existing Sandbox::run() delegates to it with empty extras — zero behaviour change for current callers.

Ordering contract (documented + tested).

• Builtins register first (chroot path normalization, COW, procfs, …).
• Extras appended last, in the Vec order.
• Chain stops at first non-Continue — user handlers cannot subvert builtin confinement.

Docs.

• docs/extension-handlers.md: design rationale, security boundary, panics policy, non-goals, downstream sketch.
• crates/sandlock-core/examples/openat_audit.rs: runnable example.

Minor bump 0.6 → 0.7 suggested.

Test plan

• 4 new unit tests in dispatch::extra_handler_tests (ctor, insertion order, append-after-builtin, empty-extras nop) — passing
• All 215 unit tests pass
• Example openat_audit.rs runs against a python3 -c guest

[congwang-mk]

Thanks for the PR!

Two main issues:

1. The mechanism (split builtins-first, extras-after; security boundary preserved) is the right shape.
   What's missing is the plumbing through to the BPF filter so that extras can actually intercept the
   syscalls they're written for. Without that, the API ships a footgun: registers handlers that silently
   never fire, with no error to tell the user why.

2. Tests that actually exercise dispatch. The current tests verify Vec::push, not the security contract.
   At minimum, an integration test that registers an extra returning NotifAction::Errno(libc::EACCES) and
   confirms the child sees EACCES.

[dzerik]

You were right on both counts — the missing BPF plumbing was the
load-bearing gap, and the original tests were verifying Vec::push
rather than the security contract. Reworked in 431c207, details below.

1. BPF plumbing

• Sandbox::do_spawn collects the syscall numbers from the
  Vec<ExtraHandler> before fork and threads them into the child via a
  new context::ChildSpawnArgs.extra_syscalls field.
• The child merges them into notif_syscalls(policy) before
  bpf::assemble_filter, with sort_unstable + dedup so a syscall
  registered by both a builtin and an extra produces a single JEQ.

While wiring this up I noticed an adjacent footgun: the cBPF program emits
notif JEQs before deny JEQs, so an extra registered on a syscall in
DEFAULT_DENY_SYSCALLS (e.g. mount) would convert a kernel-deny into a
user-supervised path and let a Continue from the handler bypass deny via
SECCOMP_USER_NOTIF_FLAG_CONTINUE. Sandbox::run_with_extra_handlers
now validates extras against the policy's deny list at registration time
and returns SandboxError::Child naming the offending syscall —
surfacing the "no error to tell the user why" gap you flagged.
Documented in §3.0.1.

2. Tests that actually exercise dispatch

The unit-level Vec::push checks remain (cheap regression cover); on top
there are now seven integration tests that drive the full kernel path:

• extra_handler_intercepts_syscall_outside_builtin_set — the case you
  asked for: SYS_uname (not in any builtin's notif list under default
  policy), handler returns Errno(EACCES), the guest observes EACCES.
• extra_handler_continue_lets_syscall_proceed — Continue becomes
  SECCOMP_USER_NOTIF_FLAG_CONTINUE and the kernel resumes the syscall.
• extra_handler_runs_after_builtin_returns_continue — SYS_openat
  with the always-on /proc-virt builtin returning Continue for
  non-/proc paths, extra observes those openats.
• builtin_non_continue_blocks_extra — symmetric half: openat on
  /proc/1/cmdline is rejected by the procfs builtin and is never
  observed by the extra, while a peer openat on /etc/hostname is.
  Handler reads the path via process_vm_readv so the assertion is
  structural rather than counter-based.
• chain_of_extras_runs_in_insertion_order — two extras on SYS_uname,
  first returns Continue, second Errno(EACCES); counters increment
  in lock step (c1 == c2) and the guest sees the EACCES.
• extra_handler_on_default_deny_syscall_is_rejected — SYS_mount
  registration is refused up-front with a descriptive error.
• empty_extras_preserves_default_behaviour — backwards compatibility.

Cosmetic

confine_child had grown to seven positional parameters; packed into
ChildSpawnArgs so the call site stays readable.

Deliberately deferred

• HandlerFn is still Box<dyn Fn ...> + Send + Sync rather than a
  trait Handler { async fn ... }; happy to convert if you'd prefer
  the trait shape, but it's an API-shape change that probably wants
  its own discussion.
• HandlerPriority::Before (audit handlers seeing pre-builtin
  arguments) remains in ## 4 Non-goals in the doc — orthogonal,
  add when there's a concrete use case.
• Panic isolation around user handlers stays the responsibility of
  the downstream crate (documented in §3.4 with a catch_unwind
  example) — wrapping every dispatch in catch_unwind by default
  would mask bugs.

Diff stat: 8 files, ~1046 / -9. All 215 unit tests pass; integration
suite passes modulo the same pre-existing 54-test failure set observed
on origin/main (kernel/capability env, unrelated to this change).
Latest head: 431c207.