Drop image subcommand from the CLI

The dispatcher existed solely to route to a single subcommand, forcing
every invocation, doc, and test script to spell "kbox image" for no
disambiguation value. Collapse the wrapper and let kbox [OPTIONS] --
COMMAND run directly. Also fix a latent issue where a positional
command after -- would override -c, and add unit tests for the
positional and -c+extras paths.

Change-Id: I3a927bb58163fc7528973e791b810ce6dc426fc2

Author: jserv

README.md

@@ -180,16 +180,16 @@ Run a guest binary:
 
 ```bash
 # Interactive shell with recommended mounts + root identity
-./kbox image -S alpine.ext4 -- /bin/sh -i
+./kbox -S alpine.ext4 -- /bin/sh -i
 
 # Run a specific command
-./kbox image -S alpine.ext4 -- /bin/ls -la /
+./kbox -S alpine.ext4 -- /bin/ls -la /
 
 # Raw mount only (no /proc, /sys, /dev), for targeted commands
-./kbox image -r alpine.ext4 -- /bin/cat /etc/os-release
+./kbox -r alpine.ext4 -- /bin/cat /etc/os-release
 
 # Custom kernel cmdline, bind mount, explicit identity
-./kbox image -r alpine.ext4 -k "mem=2048M loglevel=7" \
+./kbox -r alpine.ext4 -k "mem=2048M loglevel=7" \
     -b /home/user/data:/mnt/data --change-id 1000:1000 -- /bin/sh -i
 ```
 
@@ -202,19 +202,19 @@ interactive mode regardless of terminal detection.
 
 ```bash
 # Auto (default): rewrite/trap for direct binaries, seccomp for shells
-./kbox image -S alpine.ext4 -- /bin/ls /
+./kbox -S alpine.ext4 -- /bin/ls /
 
 # Force seccomp (most compatible, handles fork+exec)
-./kbox image -S alpine.ext4 --syscall-mode=seccomp -- /bin/sh -i
+./kbox -S alpine.ext4 --syscall-mode=seccomp -- /bin/sh -i
 
 # Force trap (single-exec commands, SIGSYS dispatch)
-./kbox image -r alpine.ext4 --syscall-mode=trap -- /bin/cat /etc/hostname
+./kbox -r alpine.ext4 --syscall-mode=trap -- /bin/cat /etc/hostname
 
 # Force rewrite (patched syscall sites, fastest stat path)
-./kbox image -r alpine.ext4 --syscall-mode=rewrite -- /opt/tests/bench-test 200
+./kbox -r alpine.ext4 --syscall-mode=rewrite -- /opt/tests/bench-test 200
 ```
 
-Run `./kbox image --help` for the full option list.
+Run `./kbox --help` for the full option list.
 
 ## Documentation
 

docs/gdb-workflow.md

@@ -24,7 +24,7 @@ gdb ./kbox
 (gdb) add-symbol-file /path/to/lkl/vmlinux
 (gdb) source scripts/gdb/kbox-gdb.py
 (gdb) kbox-lkl-load /path/to/lkl
-(gdb) set args image -S rootfs.ext4 -- /bin/sh
+(gdb) set args -S rootfs.ext4 -- /bin/sh
 (gdb) run
 ```
 
@@ -201,7 +201,7 @@ kbox forks a child (the tracee). GDB must follow the parent:
 When running under GDB with ASAN, disable LSAN (incompatible with ptrace):
 
 ```bash
-ASAN_OPTIONS=detect_leaks=0 gdb --args ./kbox image -S alpine.ext4 -c /bin/sh
+ASAN_OPTIONS=detect_leaks=0 gdb --args ./kbox -S alpine.ext4 -c /bin/sh
 ```
 
 ## Coordinated Syscall Tracing

docs/security-model.md

@@ -28,7 +28,7 @@ Three deployment tiers, in ascending isolation strength:
 
 | Tier | Threat model | Setup |
 |------|-------------|-------|
-| kbox alone | Trusted/semi-trusted code: build tools, test suites, static analysis, research, teaching | `./kbox image -S rootfs.ext4 -- /bin/sh -i` |
+| kbox alone | Trusted/semi-trusted code: build tools, test suites, static analysis, research, teaching | `./kbox -S rootfs.ext4 -- /bin/sh -i` |
 | kbox + namespace/LSM | Agent tool execution with defense-in-depth: CI runners, automated code review | Wrap with `bwrap`, Landlock, or cgroup limits (adds containment and resource controls, not hardware isolation) |
 | outer sandbox + kbox | Untrusted code, multi-tenant: hostile payloads, student submissions, public-facing agent APIs | Run kbox inside a microVM (Firecracker, Cloud Hypervisor) for hardware-enforced isolation, or inside gVisor for userspace-kernel isolation |
 

docs/web-observatory.md

@@ -29,13 +29,13 @@ process.
 make KBOX_HAS_WEB=1 BUILD=release
 
 # Launch with observatory on default port 8080
-./kbox image -S alpine.ext4 --web -- /bin/sh -i
+./kbox -S alpine.ext4 --web -- /bin/sh -i
 
 # Custom port and bind address (e.g., access from outside a VM)
-./kbox image -S alpine.ext4 --web=9090 --web-bind 0.0.0.0 -- /bin/sh -i
+./kbox -S alpine.ext4 --web=9090 --web-bind 0.0.0.0 -- /bin/sh -i
 
 # JSON trace to stderr without HTTP server
-./kbox image -S alpine.ext4 --trace-format json -- /bin/ls /
+./kbox -S alpine.ext4 --trace-format json -- /bin/ls /
 ```
 
 Open `http://127.0.0.1:8080/` in a browser. The dashboard shows:

include/kbox/cli.h

@@ -11,10 +11,6 @@
 #define KBOX_MAX_BIND_MOUNTS 32
 #define KBOX_MAX_MOUNT_OPTS 16
 
-enum kbox_mode {
-    KBOX_MODE_IMAGE,
-};
-
 enum kbox_syscall_mode {
     KBOX_SYSCALL_MODE_SECCOMP,
     KBOX_SYSCALL_MODE_TRAP,
@@ -51,17 +47,10 @@ struct kbox_image_args {
     int extra_argc;                /* count of extra_args */
 };
 
-struct kbox_args {
-    enum kbox_mode mode;
-    union {
-        struct kbox_image_args image;
-    };
-};
-
 /* Parse command-line arguments.
  * Returns 0 on success, -1 on error (message printed to stderr).
  */
-int kbox_parse_args(int argc, char *argv[], struct kbox_args *out);
+int kbox_parse_args(int argc, char *argv[], struct kbox_image_args *out);
 
 /* Print usage to stderr. */
 void kbox_usage(const char *argv0);

scripts/run-stress.sh

@@ -44,7 +44,7 @@ run_stress_test()
     printf "  %-40s " "$name"
 
     # Check if the test binary exists in the rootfs.
-    if ! "$KBOX" image -S "$ROOTFS" -- /bin/sh -c "test -x '$guest_path'" 2> /dev/null; then
+    if ! "$KBOX" -S "$ROOTFS" -- /bin/sh -c "test -x '$guest_path'" 2> /dev/null; then
         printf "${YELLOW}SKIP${NC} (not in rootfs)\n"
         SKIP=$((SKIP + 1))
         return
@@ -54,13 +54,13 @@ run_stress_test()
 
     RC=0
     if [ -n "$TIMEOUT_CMD" ]; then
-        if "$TIMEOUT_CMD" "$TIMEOUT" "$KBOX" image -S "$ROOTFS" -- "$guest_path" $guest_args > "$OUTPUT" 2>&1; then
+        if "$TIMEOUT_CMD" "$TIMEOUT" "$KBOX" -S "$ROOTFS" -- "$guest_path" $guest_args > "$OUTPUT" 2>&1; then
             RC=0
         else
             RC=$?
         fi
     else
-        if "$KBOX" image -S "$ROOTFS" -- "$guest_path" $guest_args > "$OUTPUT" 2>&1; then
+        if "$KBOX" -S "$ROOTFS" -- "$guest_path" $guest_args > "$OUTPUT" 2>&1; then
             RC=0
         else
             RC=$?