@@ -141,8 +141,8 @@ the device grant and storage re-evaluation for that boot. Quickstart reports a
141141failing startup command as a warning and continues; it never treats it as an
142142escalation. ` scripts/verify ` fails in that state.
143143
144- Pairing with Quickstart: GSA-TTS/agentic-coding-quickstart # 637 makes the
145- decision to use the read-only mount a host-side record, so a guest cannot force
144+ Pairing with Quickstart: the consumer keeps the
145+ decision to use the read-only mount in a host-side record, so a guest cannot force
146146the legacy downgrade by tampering with a guest probe. When staging a read-only
147147file fails on the host, the consumer falls back to a guest copy for that file and
148148leaves its ` /home/agent ` token in argv. If both files fall back, that is the
@@ -210,11 +210,18 @@ both apply the identical file-drop + install + device-grant sequence through
210210acq's kit translation. Behavioral parity: the guest ends up with a working
211211rootless podman (and ` docker ` aliased to it) either way.
212212
213- ## Verifying (host-side live check)
213+ ## Installation and storage verification (legacy host-side live check)
214+
215+ ` scripts/verify ` is the existing installation/storage check, not resource
216+ qualification. It retains its legacy two-state verdict: exit 0 means that nothing
217+ it counted failed, not that all evidence was available. In particular, its
218+ missing-rootless-field fallback checks only the agent UID. Neither that fallback,
219+ the installation marker, nor a successful storage build proves that memory, CPU,
220+ and PID limits are effective. See the [ shared verdict contract] ( ../README.md#what-a-scriptsverify-exit-code-means ) .
214221
215222` scripts/verify ` creates a throwaway ** msb** sandbox with this kit applied
216223** through acq** (` acq --backend msb create shell … --kit … ` ) and confirms rootless
217- podman actually works: podman reports ` rootless=true ` , a real ` podman build ` from
224+ installation/storage behavior: it requests ` rootless=true ` , a real ` podman build ` from
218225` scratch ` mounts a layer as the agent, and the ` docker ` -> ` podman ` wrapper this
219226kit drops resolves and routes to podman.
220227
@@ -260,3 +267,69 @@ VERIFY_OCI_IMAGE=docker.io/library/ubuntu:24.04 \
260267
261268The backend-agnostic gate (schema + cross-field rules) is
262269` integrations/isolation/acq-kits/validate-kits.py ` (` make validate-kits ` ).
270+
271+ ## Resource qualification (guest-only, experimental)
272+
273+ Run ` scripts/verify-resources ` ** inside the intended Linux guest** , as its
274+ non-root agent. It needs Python 3 (standard library only), an explicitly selected
275+ absolute installed Podman executable, and a trusted image already loaded in that
276+ agent's local store. The image must have ` /bin/sh ` and ` sleep ` , and its reference
277+ must be a fully qualified registry/repository plus ` @sha256: ` and 64 lowercase
278+ hex digits. There is no default image and no pull, install, root fallback, or
279+ cgroup repair. Copy the wrapper and adjacent ` verify_resources.py ` into the guest
280+ through the operator's normal trusted delivery path; the kit does not autorun it.
281+
282+ ``` sh
283+ # In the guest; substitute the actual preloaded digest-qualified reference.
284+ sh scripts/verify-resources --guest --podman /usr/bin/podman \
285+ --image " $PRELOADED_DIGEST_REF "
286+ ```
287+
288+ ` --guest ` is an operator acknowledgment, ** not guest detection or attestation** .
289+ Linux and non-root checks cannot distinguish a Linux host from a guest. Never
290+ invoke it on the host, through a remote Podman client, or with the Docker wrapper.
291+ The environment is allowlisted, with the local user's home/runtime directory and
292+ a fixed ` /usr/bin:/bin ` path; every engine call uses ` --remote=false ` .
293+
294+ The gate requires an explicit JSON boolean ` host.security.rootless=true ` , cgroup
295+ v2, and reported delegation of ` memory ` , ` cpu ` , and ` pids ` before creation. It
296+ creates then starts one probe, overriding its entrypoint with ` /bin/sh ` , with
297+ network ` none ` , user ` 65534:65534 ` , all capabilities dropped, no-new-privileges,
298+ 128 MiB memory, one CPU, and 32 PIDs. It supplies no mounts, ignores image-declared
299+ volumes, disables healthchecks/logging, and uses a read-only root filesystem.
300+ The command is ` exec sleep 120 ` ; it is a bounded observation window, not a stress
301+ test. Each CLI call has a 10-second deadline and 64 KiB combined-output cap.
302+
303+ The verifier maps the live inspected guest PID's ` /proc/PID/cgroup ` membership
304+ through ` /proc/self/mountinfo ` to the cgroup2 mount, rejecting traversal,
305+ ambiguous mappings, and symlink resolution. It reads ** kernel** ` memory.max ` ,
306+ ` cpu.max ` , and ` pids.max ` , not just requested inspect limits. It also checks live
307+ UIDs, effective capabilities and no-new-privileges, and rechecks PID start time,
308+ membership, and the engine's running PID. It requires exact leaf limits;
309+ stricter ancestor limits may further restrict the probe. No throughput, OOM,
310+ fork-exhaustion, hostile-image containment, or outer-VM limit claim follows.
311+
312+ | Exit | Resource verifier result |
313+ | ---| ---|
314+ | ` 0 ` | Measured prerequisites, live kernel limits and exact-ID cleanup passed |
315+ | ` 1 ` | An observed rootful engine or wrong effective policy/limit failed |
316+ | ` 3 ` | Missing tools/image/controllers/evidence, malformed data, interrupted transport, or unverified cleanup; no measured failure |
317+
318+ This follows the coverage semantics of [ verify-report.sh] ( ../verify-report.sh ) :
319+ a measured failure retains exit 1 even if another check is unverified. Cleanup
320+ runs in ` finally ` against only the full returned container ID and requires
321+ ` container exists ` to report absence. A lost/malformed create response cannot
322+ identify an owned container and therefore reports cleanup ** UNVERIFIED** , never
323+ a pass. The operator must reconcile that guest's container store; there is no
324+ name-based or broad cleanup. Uncatchable termination cannot guarantee cleanup.
325+
326+ Offline tests use fake executables/injected transport and synthetic kernel
327+ evidence; they never invoke a real engine:
328+
329+ ``` sh
330+ python3 -I -B scripts/tests/test_oci_resource_verifier.py
331+ ```
332+
333+ See [ resource qualification decision] ( docs/decisions/resource-qualification.md )
334+ for the trust boundary and limitations. Storage success and resource success are
335+ separate evidence; neither substitutes for the other.
0 commit comments