fix(cli): emit audit events for box + image lifecycle (operability audit #5) (#131)

* fix(cli): emit audit events for box lifecycle (operability audit #5, core lifecycle)

The audit log (reader + 'a3s-box audit' command + AuditLog writer) was fully
built, defaults to enabled, but NO production code ever emitted an event — so the
trail an operator relies on for forensics/compliance was always empty, silently.
The AuditSink doc even claimed 'the runtime calls record whenever a
security-relevant action occurs', which was false.

Add a best-effort cli::audit helper (record/record_to) and wire it into the core
box-lifecycle commands: create -> BoxCreate, stop -> BoxStop, rm -> BoxDestroy.
Emission is best-effort (a failed audit write never fails the operation) and
no-ops when AuditConfig.enabled is false. So 'a3s-box audit' now surfaces who
created/stopped/removed boxes. run->BoxStart, exec->ExecCommand, and pull->
ImagePull have more complex multi-path flows and are a tracked follow-up.

Tests: record_to_appends_a_readable_event (writer -> reader round-trip),
record_to_is_silent_when_disabled.

* fix(cli): also audit run->BoxStart and pull->ImagePull (operability audit #5)

Extends the box-lifecycle audit wiring with the box-start and image-pull events
— the other key forensic actions an operator audits. exec->ExecCommand (fg/pty
multi-path) remains a tracked follow-up.

* fix(cli): also audit exec->ExecCommand (operability audit #5)

Wire the non-pty exec path so 'who exec'd into a box' is captured in the audit
trail (recorded after the exec is delivered, before the container exit-code may
std::process::exit). The pty exec path remains a tracked follow-up.

* fix(cli): also audit the pty (exec -it) path -> ExecCommand (operability audit #5)

Completes the exec audit: an interactive shell session (exec -it) now also emits
an ExecCommand event, recorded once the pty request is delivered. The full audit
trail is now create/run/stop/rm/pull/exec (both non-pty and pty).

---------

Co-authored-by: Roy Lin <roylin@a3s.box>

Author: ZhiXiao-Lin

src/cli/src/audit.rs

@@ -0,0 +1,84 @@
+//! Best-effort audit-trail emission for box lifecycle events.
+//!
+//! The audit log (read with `a3s-box audit`) records security-relevant actions —
+//! who created/started/stopped/removed a box, and what was exec'd or pulled. The
+//! reader + CLI command and the `AuditLog` writer were fully built, but no
+//! production code ever emitted an event, so the trail was always empty. These
+//! helpers wire the writer into the lifecycle commands.
+//!
+//! Emission is **best-effort**: a failure to record the audit trail must never
+//! fail the operation it describes. Auditing is on by default
+//! (`AuditConfig::default().enabled == true`); `AuditLog::log` no-ops when it is
+//! disabled.
+
+use a3s_box_core::audit::{AuditAction, AuditEvent, AuditOutcome};
+use a3s_box_runtime::AuditLog;
+
+/// Emit one audit event to `log`, best-effort. Separated from [`record`] so the
+/// emission can be unit-tested against a temporary log.
+pub(crate) fn record_to(
+    log: &AuditLog,
+    action: AuditAction,
+    outcome: AuditOutcome,
+    box_id: &str,
+    message: &str,
+) {
+    let event = AuditEvent::new(action, outcome)
+        .with_box_id(box_id)
+        .with_message(message);
+    let _ = log.log(&event);
+}
+
+/// Emit one audit event to the default audit log (`~/.a3s/audit/audit.jsonl`),
+/// best-effort. A log that can't be opened is silently skipped.
+pub(crate) fn record(action: AuditAction, outcome: AuditOutcome, box_id: &str, message: &str) {
+    if let Ok(log) = AuditLog::default_path() {
+        record_to(&log, action, outcome, box_id, message);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use a3s_box_core::audit::AuditConfig;
+    use a3s_box_runtime::{read_audit_log, AuditQuery};
+
+    #[test]
+    fn record_to_appends_a_readable_event() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("audit.jsonl");
+        let log = AuditLog::new(&path, AuditConfig::default()).unwrap();
+
+        record_to(
+            &log,
+            AuditAction::BoxStop,
+            AuditOutcome::Success,
+            "box-123",
+            "stopped via a3s-box stop",
+        );
+
+        // The reader (a3s-box audit) must now surface the event — previously the
+        // writer was never called so this list was always empty.
+        let events = read_audit_log(&path, &AuditQuery::default()).unwrap();
+        assert_eq!(events.len(), 1);
+        assert_eq!(events[0].box_id.as_deref(), Some("box-123"));
+        assert!(matches!(events[0].action, AuditAction::BoxStop));
+    }
+
+    #[test]
+    fn record_to_is_silent_when_disabled() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("audit.jsonl");
+        let disabled = AuditConfig {
+            enabled: false,
+            ..AuditConfig::default()
+        };
+        let log = AuditLog::new(&path, disabled).unwrap();
+
+        record_to(&log, AuditAction::BoxStart, AuditOutcome::Success, "b", "x");
+
+        // Disabled: nothing is written (no file, or an empty read).
+        let events = read_audit_log(&path, &AuditQuery::default()).unwrap_or_default();
+        assert!(events.is_empty());
+    }
+}

src/cli/src/commands/create.rs

@@ -185,6 +185,12 @@ pub async fn execute(args: CreateArgs) -> Result<(), Box<dyn std::error::Error>>
         return Err(error);
     }
 
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::BoxCreate,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &box_id,
+        &format!("created box {name}"),
+    );
     println!("{box_id}");
     Ok(())
 }

src/cli/src/commands/exec.rs

@@ -151,6 +151,15 @@ pub async fn execute(args: ExecArgs) -> Result<(), Box<dyn std::error::Error>> {
     };
 
     let output = client.exec_command(&request).await?;
+    // Record that an exec happened (best-effort) before the exit-code branch
+    // below may std::process::exit. The container command's own exit code is
+    // separate from whether the exec was delivered.
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::ExecCommand,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &record.id,
+        &format!("exec command in box {}", record.name),
+    );
 
     if !output.stdout.is_empty() {
         let stdout = String::from_utf8_lossy(&output.stdout);
@@ -203,6 +212,14 @@ async fn execute_pty(
         rows,
     };
     client.send_request(&request).await?;
+    // Record the interactive (pty) exec once the request is delivered — opening
+    // a shell in a box is a key forensic event.
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::ExecCommand,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &record.id,
+        &format!("exec (pty) in box {}", record.name),
+    );
 
     // Split the PTY client stream for concurrent read/write
     let (read_half, write_half) = client.into_split();

src/cli/src/commands/pull.rs

@@ -89,6 +89,12 @@ pub async fn execute(args: PullArgs) -> Result<(), Box<dyn std::error::Error>> {
         }));
     }
     let image = puller.pull(&args.image).await?;
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::ImagePull,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &args.image,
+        &format!("pulled image {}", args.image),
+    );
 
     if args.quiet {
         println!("{}", image.root_dir().display());

src/cli/src/commands/rm.rs

@@ -71,6 +71,12 @@ fn rm_one(
     // in-memory handle consistent without a second persisting write.
     StateFile::remove_record(&box_id)?;
     state.forget(&box_id);
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::BoxDestroy,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &box_id,
+        &format!("removed box {name}"),
+    );
     println!("{name}");
 
     Ok(())

src/cli/src/commands/run.rs

@@ -91,6 +91,12 @@ pub async fn execute(args: RunArgs) -> Result<(), Box<dyn std::error::Error>> {
         .map_err(|e| -> Box<dyn std::error::Error> { e.into() })?;
 
     let ctx = setup_and_boot(&args).await?;
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::BoxStart,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &ctx.box_id,
+        &format!("started box from image {}", args.common.image),
+    );
     if args.detach {
         println!("{}", ctx.box_id);
         return Ok(());

src/cli/src/commands/stop.rs

@@ -102,6 +102,12 @@ async fn stop_one(
         }
         Ok::<(), std::io::Error>(())
     })?;
+    crate::audit::record(
+        a3s_box_core::audit::AuditAction::BoxStop,
+        a3s_box_core::audit::AuditOutcome::Success,
+        &box_id,
+        &format!("stopped box {name}"),
+    );
     println!("{name}");
 
     Ok(())

src/cli/src/lib.rs

@@ -1,5 +1,6 @@
 //! A3S Box CLI - Docker-like MicroVM runtime.
 
+pub mod audit;
 pub mod boot;
 pub mod cleanup;
 pub mod commands;