docs(readme): document new operator-facing env vars (decompression caps, seccomp root, snapshot/mirror) (#147)

* docs(readme): document the new operator-facing env vars

The env-var reference was missing several operator-facing knobs added by the
recent operability + security hardening:

- A3S_BOX_MAX_LAYER_BYTES / A3S_BOX_MAX_BUILD_EXTRACT_BYTES — decompression-bomb
  caps on layer pull and build ADD/COPY auto-extract (defaults 16 GiB / 4 GiB).
- A3S_BOX_SECCOMP_PROFILE_ROOT — root the CRI localhostProfile seccomp path is
  confined to (default /var/lib/kubelet/seccomp).
- A3S_BOX_MAX_SNAPSHOTS / A3S_BOX_MAX_SNAPSHOT_BYTES — snapshot auto-prune caps
  (were documented in prose but absent from the reference table).
- A3S_REGISTRY_MIRRORS — registry mirror map.

Docs-only; no behavior change.

* docs(changelog): record post-2.3.0 security/concurrency/operability hardening

Fill the empty [Unreleased] section with the three post-2.3.0 audits merged to
main (#131-#146): untrusted-input security (CRITICAL digest path-traversal,
whiteout host-delete, decompression bombs, CRI seccomp confinement), daemonless
lifecycle concurrency races, and 24 operability findings. Docs-only.

---------

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

Author: ZhiXiao-Lin

CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to A3S Box will be documented in this file.
 
 ## [Unreleased]
 
+Post-2.3.0 hardening: three adversarial audits — production-operability (24
+findings), untrusted-input security (4), and concurrency/atomicity (4) — all
+fixed and validated on real microVMs. No breaking API changes.
+
+### Security
+
+Image extraction runs **host-side before the microVM boots**, so a malicious
+image's reach here bypasses VM isolation:
+
+- **Arbitrary host file write via registry digest path-traversal (CRITICAL).** The
+  manifest digest (`Docker-Content-Digest`, returned verbatim by the registry)
+  flowed into `Path::join` unvalidated, so `sha256:../../../../<path>` wrote the
+  attacker-shaped manifest to an arbitrary host path on `pull` in the default
+  config (signature policy is Skip by default; the box runtime often runs as
+  root). Digests are now validated as canonical `sha256:<64-hex>` at the trust
+  boundary before any path use.
+- **Arbitrary host file/dir deletion via whiteout symlink escape.** A layer
+  whiteout whose parent was an absolute symlink (e.g. `esc -> /etc`) deleted host
+  files/dirs through it. Whiteout parents are now confined within the extraction
+  target.
+- **Host disk exhaustion via decompression bomb.** Layer pull and build
+  `ADD`/`COPY` auto-extract streamed gzip/zstd/bzip2/xz with no decompressed-size
+  cap. Bounded by `A3S_BOX_MAX_LAYER_BYTES` (16 GiB) and
+  `A3S_BOX_MAX_BUILD_EXTRACT_BYTES` (4 GiB), env-overridable.
+- **CRI seccomp `localhostProfile` path confinement.** The attacker-set pod field
+  was read off disk unconfined (an arbitrary host-file open oracle); it is now
+  confined to `A3S_BOX_SECCOMP_PROFILE_ROOT` (default `/var/lib/kubelet/seccomp`),
+  rejecting `..` and out-of-root paths.
+
+### Fixed
+
+- **Daemonless lifecycle concurrency races** (the `monitor` daemon, CLI
+  processes, and CRI server coordinate via a per-write flock that does not span an
+  `await`):
+  - The monitor no longer resurrects a box the user `stop`ped during its
+    up-to-10s health-restart window.
+  - A user `restart` and the monitor's auto-restart can no longer both boot the
+    same box (now serialized by a per-box boot lock); previously the second record
+    write overwrote the first's PID, orphaning an untracked VM.
+  - `kill`'s host-signal fallback re-checks PID start-time identity before
+    signalling, so a reused PID is never signalled.
+  - The warm pool no longer leaks a VM pushed into the idle set during shutdown
+    drain.
+- **Operability (24 findings)** across crash-recovery, upgrade-compat,
+  disk-pressure, concurrency, network-lifecycle, and config-validation — e.g.
+  PID-reuse liveness via start-time identity, corrupt-store quarantine instead of
+  a hard fail, durable (fsync'd) state writes, bounded snapshot / build-cache /
+  CRI-log growth, atomic CRI network attach, stable bridge IPs across stop/start,
+  and fail-closed `--cpus` / `--memory-swap` validation.
+
+### Changed
+
+- New operator-tunable caps (generous defaults, env-overridable), documented in
+  the Environment variables table: `A3S_BOX_MAX_LAYER_BYTES`,
+  `A3S_BOX_MAX_BUILD_EXTRACT_BYTES`, `A3S_BOX_SECCOMP_PROFILE_ROOT`,
+  `A3S_BOX_MAX_SNAPSHOTS` / `A3S_BOX_MAX_SNAPSHOT_BYTES`.
+
 ## [2.3.0] — 2026-06-16
 
 A security and hardening release closing a 35-finding adversarial audit (plus

README.md

@@ -437,6 +437,12 @@ matrix, and CRI smoke procedures.
 | `A3S_BOX_HOST_SMOKE_TIMEOUT_SECS` | Boot timeout override for ignored host smoke tests. |
 | `A3S_BOX_UNSAFE_HOST_RUN` | Opt into unsafe macOS host execution for Dockerfile `RUN` experiments. |
 | `A3S_BOX_BUILDCACHE_MAX_BYTES` | Cap on the total size of cached build layers at `~/.a3s/buildcache` (oldest evicted first). Default: 2 GiB. |
+| `A3S_BOX_MAX_LAYER_BYTES` | Cap on total decompressed bytes per OCI image layer during `pull` (decompression-bomb guard). Default: 16 GiB. |
+| `A3S_BOX_MAX_BUILD_EXTRACT_BYTES` | Cap on total decompressed bytes when a build `ADD`/`COPY` auto-extracts a local tar archive (decompression-bomb guard). Default: 4 GiB. |
+| `A3S_BOX_MAX_SNAPSHOTS` | Auto-prune on every `snapshot create` to keep at most N newest snapshots per box (unset = unbounded). |
+| `A3S_BOX_MAX_SNAPSHOT_BYTES` | Auto-prune on every `snapshot create` to keep snapshots under a total byte cap (unset = unbounded). |
+| `A3S_BOX_SECCOMP_PROFILE_ROOT` | Root directory a CRI `localhostProfile` seccomp path is confined to (paths outside it, or containing `..`, are rejected). Default: `/var/lib/kubelet/seccomp`. |
+| `A3S_REGISTRY_MIRRORS` | Registry mirror map (`host=mirror,host=mirror`); pulls fetch layers/manifests from the mirror while keeping the canonical image reference. |
 | `KRUN_SNAPSHOT_MEM_FILE` | Path the booted template writes its file-backed guest RAM to when capturing a snapshot-fork template. |
 | `KRUN_SNAPSHOT_SOCK` | Control socket the template listens on for the `snapshot <path>` command (Linux `/dev/kvm` only). |
 | `KRUN_RESTORE_FROM` | Path to a snapshot the microVM restores from as a Copy-on-Write fork instead of cold booting. |