Skip to content

Commit a649807

Browse files
committed
feat(oci-engine): qualify bounded rootless resource controls
Co-authored-by: OpenCode Agent <[email protected]>
1 parent ce4aa08 commit a649807

6 files changed

Lines changed: 906 additions & 13 deletions

File tree

‎integrations/isolation/acq-kits/oci-engine/README.md‎

Lines changed: 77 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -141,8 +141,8 @@ the device grant and storage re-evaluation for that boot. Quickstart reports a
141141
failing startup command as a warning and continues; it never treats it as an
142142
escalation. `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
146146
the legacy downgrade by tampering with a guest probe. When staging a read-only
147147
file fails on the host, the consumer falls back to a guest copy for that file and
148148
leaves 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
210210
acq's kit translation. Behavioral parity: the guest ends up with a working
211211
rootless 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
219226
kit drops resolves and routes to podman.
220227

@@ -260,3 +267,69 @@ VERIFY_OCI_IMAGE=docker.io/library/ubuntu:24.04 \
260267

261268
The 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.
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Decision: separate guest-local resource qualification from storage verification
2+
3+
**Status:** experimental
4+
5+
## Context
6+
7+
A working installation, storage layer mount, non-root agent UID, or configured
8+
marker does not establish resource enforcement. Rootless Podman may operate with
9+
missing cgroup delegation. The legacy `scripts/verify` combines installation and
10+
storage checks with two-state reporting and a UID fallback when the rootless
11+
field is absent. Retrofitting that script would obscure this narrower contract.
12+
13+
## Decision
14+
15+
Add [scripts/verify-resources](../../scripts/verify-resources) and its isolated
16+
Python standard-library helper as an explicit **guest-local** operation. The
17+
wrapper uses `python3 -I -B`. The operator selects the intended guest, trusted
18+
installed Podman executable, and preloaded digest-qualified image; the script
19+
does not select a backend or contact an image registry. `--guest` acknowledges
20+
placement but cannot attest that a Linux machine is a guest.
21+
22+
Use an allowlisted environment and `--remote=false` rather than honoring inherited
23+
Docker/Podman remote settings. Require explicit JSON rootless boolean true,
24+
cgroup v2, and memory/cpu/pids delegation before creating a probe. Do not mutate
25+
cgroups, install dependencies, request root, or degrade into an unlimited run.
26+
27+
Create separately from start to obtain ownership of a full container ID before
28+
image execution. Override the entrypoint; constrain the probe to network none,
29+
non-root user, dropped capabilities, no-new-privileges, memory 128 MiB, CPU quota
30+
one CPU, and 32 PIDs. Ignore image volumes and disable healthchecks and logging.
31+
No bind mounts are supplied. A 120-second sleep leaves a finite observation
32+
window without a resource-exhaustion workload. CLI calls are individually bounded
33+
to 10 seconds and 64 KiB combined output, with no retries and bounded CLI reap.
34+
Step traces identify the active operation and exact owned ID without echoing
35+
engine stderr or the environment.
36+
37+
Inspect requested configuration only for identity and probe-policy checks.
38+
Resource qualification comes from the guest kernel: join the live inspected PID's
39+
unified membership to the guest reader's cgroup2 mount root, then read leaf
40+
`memory.max`, `cpu.max`, and `pids.max`. Reject traversal, unmapped/ambiguous
41+
mounts, symlinks, missing or malformed evidence. Verify live UID/capability/NNP
42+
evidence and repeat process start-time, membership, and engine PID checks.
43+
44+
The verdict is a function of the coverage record, following
45+
[the shared reporter](../../../verify-report.sh): 0 measured success, 1 measured
46+
failure, 3 incomplete evidence without a measured failure. `finally` removes only
47+
the exact returned full ID and checks absence. Lost create identity, cleanup
48+
failure, transport failure or interruption can never pass. Signals are recorded;
49+
subsequent probe operations stop while bounded cleanup remains available.
50+
51+
## Limits and follow-up evidence
52+
53+
- This is a point-in-time qualification of this guest/user/store/image. It trusts
54+
the installed executable, guest kernel, and operator-selected image; it is not
55+
an attestation against a compromised guest or hostile engine.
56+
- Only the documented Podman JSON schema is accepted. Unsupported schemas and
57+
restricted `/proc` or cgroup visibility are unverified, not rootless inferred
58+
from UID and not successful on the strength of a marker.
59+
- Kernel leaf limits must match exactly. Ancestors may impose tighter limits;
60+
the result is not a performance guarantee or outer sandbox resource claim.
61+
- Path/identity rechecks reduce races but are not an atomic snapshot. A concurrent
62+
privileged guest process can still invalidate evidence. Reads assume functioning
63+
local procfs/cgroupfs; uninterruptible kernel I/O cannot be bounded in user space.
64+
- A create response lost before a valid ID leaves ownership unknown. Report this
65+
and require operator reconciliation rather than deleting by name or sweeping
66+
unrelated containers. SIGKILL, guest failure, and lost cleanup transport can
67+
leave artifacts even though the probe command has a finite lifetime.
68+
- [Offline tests](../../../../../../scripts/tests/test_oci_resource_verifier.py)
69+
exercise injected transport, kernel schemas, malformed/degraded results,
70+
deadlines, output bounds and signals. They prove verifier behavior, not actual
71+
engine enforcement. Live qualification remains a separately authorized guest
72+
run with the selected preloaded image.
73+
74+
See the [kit README](../../README.md#resource-qualification-guest-only-experimental)
75+
for invocation and the [storage decision](port-oci-engine-failsoft-and-vfs-fallback.md)
76+
for the independent installation/storage lifecycle.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/sh
2+
# Guest-only resource qualification; see ../docs/decisions/resource-qualification.md.
3+
set -eu
4+
PATH=/usr/bin:/bin
5+
export PATH
6+
if ! command -v python3 >/dev/null 2>&1; then
7+
printf '%s\n' 'UNVERIFIED: Python 3 is unavailable' >&2
8+
exit 3
9+
fi
10+
exec python3 -I -B "$(dirname "$0")/verify_resources.py" "$@"

0 commit comments

Comments
 (0)