Skip to content

Commit 3743330

Browse files
committed
fix(kits): fail closed when a selected readonly mount file is missing
The oci-engine root startup fell back to the root-owned /usr/local/lib/acq/oci-engine copy when the backend had selected a path on the read-only mount but the file was missing. Those copies came from /home/agent at create time, so they are not host-authoritative across restarts. The grant script did the same for its storage helper. - Startup now classifies the two tokens together. Both on the mount: run them, or refuse (stderr error, exit 1) if either file is missing. Both /home/agent: the explicit legacy case, root-owned copy as before. Anything else, including a mixed pair or `..`: refuse. The earlier mounted-path-missing fallback is removed. - oci-engine-grant-devs.sh refuses a missing selected mount helper and any path outside the mount or the root-owned directory; no silent fallback. - scripts/verify fails when readonly was honored but a mount file is missing, or when only one file is on the mount. - Docs: table of token cases, why a non-zero exit is safe (Quickstart reports a failing startup command as a warning), the pairing with Quickstart#637, and the mount-enforcement assumption. - Tests: offline fixtures for each case, with mutation checks. Co-authored-by: OpenCode Agent <[email protected]>
1 parent ccad8a7 commit 3743330

7 files changed

Lines changed: 241 additions & 87 deletions

File tree

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,11 @@ Rules for kit authors:
165165
honored the argv element is still the original `path`, which is
166166
agent-writable. A root command must validate **each** such token on its own
167167
against the allowed prefix (the read-only mount, `/var/lib/acq/host/kit-files/`)
168-
and otherwise substitute a root-owned copy or refuse, as `oci-engine` does.
168+
and otherwise refuse, as `oci-engine` does. Substitute a root-owned copy only
169+
for the explicit legacy case (the token is still the agent path). If a token
170+
names the mount but the file is missing, fail closed with an error and a
171+
non-zero exit; do not fall back, because a root-owned copy published from the
172+
agent home at create time is not host-authoritative across restarts.
169173
Checking only one token lets a partial rewrite slip an agent path through the
170174
other. A kit with no root-owned copy to fall back on (the file is staged at
171175
start, so nothing publishes it at create) should not use the flag; see

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

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,9 @@ installed** — it group-scopes `/dev/net/tun` and `/dev/fuse` to the agent
4242
(`root:agent`, `0660`) so rootless podman networking and the fuse-overlayfs
4343
storage mount work, and it **re-evaluates the system storage driver**. The elevated install and startup scripts, plus the storage helper sourced by
4444
them, run only from a host-authoritative read-only mount (when the consumer honors
45-
`readonly`) or from root-owned copies under `/usr/local/lib/acq/oci-engine/`, never
46-
from the agent-home staging files. `/dev` is a devtmpfs
45+
`readonly`; a missing mount file is a refusal, not a fallback) or, for a consumer
46+
that ignores `readonly`, from root-owned copies under `/usr/local/lib/acq/oci-engine/`,
47+
never from the agent-home staging files. `/dev` is a devtmpfs
4748
re-created each boot, so both must re-run on restart, not just at create;
4849
re-evaluating the driver each boot lets it **converge from `vfs` to `overlay`**
4950
once `fuse-overlayfs` and `/dev/fuse` are both available (a transient `/dev/fuse`
@@ -99,8 +100,9 @@ engine")** decision, declaratively:
99100
kit mechanism, but root phases do not execute or source those mutable copies.
100101
The root command wrappers publish the install script into
101102
`/usr/local/lib/acq/oci-engine/`; the startup script and sourced helper run from
102-
the read-only mount when the consumer honors `readonly`, else from root-owned
103-
copies published there. Neither runs from the mutable staging copies.
103+
the read-only mount when the consumer honors `readonly` (failing closed if the
104+
file is missing), else from root-owned copies published there for a consumer
105+
that ignores `readonly`. Neither runs from the mutable staging copies.
104106
- **Least-privilege registry resolution.** `short-name-mode` defaults to
105107
**`enforcing`**, not `permissive`. Because there is a single search registry
106108
(`docker.io`), unqualified names still resolve deterministically to Docker Hub
@@ -122,13 +124,39 @@ The root `startup` step runs two kit files: `oci-engine-grant-devs.sh` and the
122124
honors the flag (acq `msb`, quickstart ADR-0035) runs them from a
123125
host-authoritative read-only mount, so a guest user with `sudo` cannot edit what
124126
root executes on each start. A consumer that ignores the flag copies them under
125-
`/home/agent` as before, and the step then runs the root-owned copy that
126-
`oci-engine-install.sh` published. The step accepts a path only if it is under
127-
`/var/lib/acq/host/kit-files/` (the read-only mount), checks the script and the
128-
helper independently, and substitutes the root-owned copy for anything else, so
129-
it never runs an `/home/agent` path. `oci-engine-grant-devs.sh` repeats that
130-
check on the helper it sources. If neither the mount nor the root-owned copy has
131-
the script, the step prints a warning and `scripts/verify` fails.
127+
`/home/agent` as before (the *legacy* case), and the step then runs the
128+
root-owned copy that `oci-engine-install.sh` published.
129+
130+
The step **fails closed**. It classifies the two tokens together:
131+
132+
| Tokens | Behavior |
133+
|---|---|
134+
| Both under `/var/lib/acq/host/kit-files/` | Run exactly those files. If either file is missing: error on stderr, run nothing as root, exit 1. It does **not** fall back to the root-owned copy, which came from `/home/agent` at create time and is not host-authoritative across restarts. |
135+
| Both under `/home/agent/` | Legacy: run the root-owned copy that install published. If install published nothing, warn and exit 0, as before. |
136+
| Anything else (one mounted and one not, `..`, an unknown prefix, an empty token) | Refuse: error on stderr, exit 1. |
137+
138+
`oci-engine-grant-devs.sh` applies the same rule to the helper it sources: a
139+
missing selected mount helper is a refusal, not a fallback. A refusal costs only
140+
the device grant and storage re-evaluation for that boot. Quickstart reports a
141+
failing startup command as a warning and continues; it never treats it as an
142+
escalation. `scripts/verify` fails in that state.
143+
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
146+
the legacy downgrade by tampering with a guest probe. When staging a read-only
147+
file fails on the host, the consumer falls back to a guest copy for that file and
148+
leaves its `/home/agent` token in argv. If both files fall back, that is the
149+
legacy row above. If only one does, the pair is mixed (one mount token, one
150+
`/home/agent` token) and the step refuses, so one failed host copy costs the
151+
device grant and storage re-evaluation for that boot. The consumer's create-time
152+
startup script derives its rewrite table without checking whether staging
153+
succeeded, so it can name a mount file that was never staged; the step refuses
154+
that case too.
155+
156+
The mount is enforced by the backend. A guest user with `sudo` who can unmount or
157+
bind-mount over `/var/lib/acq/host/kit-files` is outside what token validation
158+
can defend against; the read-only property rests on the backend's mount
159+
enforcement.
132160

133161
The install step still trusts `/home/agent` at create time (it publishes the
134162
staged copies into the root-owned directory, before the agent's first session).

‎integrations/isolation/acq-kits/oci-engine/docs/decisions/port-oci-engine-failsoft-and-vfs-fallback.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -158,12 +158,14 @@ direction and flagged six implementation defects, all addressed here:
158158
> **Superseded in part** by the `readonly: true` startup files (quickstart
159159
> ADR-0035). The grant script and storage helper are now declared `readonly`:
160160
> a consumer that honors the flag runs them from a read-only host mount and the
161-
> install step has nothing to publish. The startup command then accepts a path
162-
> only under `/var/lib/acq/host/kit-files/` (each of the two argv tokens checked
163-
> independently) and otherwise uses the root-owned copy, and the grant script
164-
> re-validates the helper it sources. The invariant is unchanged: root startup
165-
> code never runs from an agent-writable path. The install step still trusts
166-
> `/home/agent` at create time, before the agent's first session.
161+
> install step has nothing to publish. The startup command then fails closed:
162+
> tokens under `/var/lib/acq/host/kit-files/` run only if the files exist (a
163+
> missing selected file is a refusal, never a fallback to the root-owned copy);
164+
> only the explicit legacy case, both tokens still `/home/agent/*`, uses the
165+
> root-owned copy; any other or mixed pair is refused. The grant script
166+
> re-validates the helper it sources the same way. The invariant is unchanged:
167+
> root startup code never runs from an agent-writable path. The install step
168+
> still trusts `/home/agent` at create time, before the agent's first session.
167169
168170
8. **Stale device grant after podman disappears.** The no-podman startup path now
169171
best-effort resets `/dev/net/tun` and `/dev/fuse` to `root:root` `0600` before

‎integrations/isolation/acq-kits/oci-engine/files/home/oci-engine-grant-devs.sh‎

Lines changed: 29 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -55,26 +55,44 @@ if ! command -v podman >/dev/null 2>&1; then
5555
exit 0
5656
fi
5757

58-
# Storage helper to source, passed by the startup command as $1: a path on acq's
59-
# host-authoritative read-only mount (the helper is a `readonly: true` kit file)
60-
# or the root-owned copy oci-engine-install.sh publishes. It is sourced as ROOT, so
61-
# it is validated HERE, independent of the caller: only those two locations are
62-
# accepted (no `..`); anything else, notably an agent-writable path, is refused
63-
# loudly and the root-owned copy is used instead. Defaults to the root-owned copy
64-
# when run without arguments.
58+
# Storage helper to source, passed by the startup command as $1. It is sourced as
59+
# ROOT, so it is validated HERE, independent of the caller, and this script FAILS
60+
# CLOSED:
61+
# - a path under the host-authoritative read-only mount (the helper is a
62+
# `readonly: true` kit file): used only if that file exists; if it is missing
63+
# the script refuses (error on stderr, exit 1) and does NOT fall back to the
64+
# root-owned copy, which came from /home/agent at create time;
65+
# - a path under the root-owned directory (the LEGACY layout, where the consumer
66+
# ignored `readonly`): used if present, else storage re-evaluation is skipped
67+
# with a warning, as before;
68+
# - anything else, notably an agent-writable path or any `..`: refused.
69+
# With no argument (run by hand) it defaults to the root-owned copy.
6570
OCI_ENGINE_TRUSTED_DIR="/usr/local/lib/acq/oci-engine"
6671
OCI_ENGINE_RO_MOUNT_PREFIX="/var/lib/acq/host/kit-files/"
6772
TRUSTED_STORAGE_HELPER="$OCI_ENGINE_TRUSTED_DIR/oci-engine-storage-driver.sh"
68-
if [ "$#" -ge 1 ] && [ -n "$1" ]; then
73+
if [ "$#" -ge 1 ]; then
6974
case "$1" in
75+
"")
76+
echo "oci-engine: ERROR: empty storage helper path; refusing." >&2
77+
exit 1
78+
;;
7079
*..*)
71-
echo "oci-engine: WARNING: refusing storage helper path containing '..': $1; using $TRUSTED_STORAGE_HELPER." >&2
80+
echo "oci-engine: ERROR: storage helper path contains '..': $1; refusing." >&2
81+
exit 1
82+
;;
83+
"$OCI_ENGINE_RO_MOUNT_PREFIX"?*)
84+
if [ ! -f "$1" ]; then
85+
echo "oci-engine: ERROR: selected read-only storage helper is missing: $1; refusing (no fallback to a root-owned copy)." >&2
86+
exit 1
87+
fi
88+
TRUSTED_STORAGE_HELPER="$1"
7289
;;
73-
"$OCI_ENGINE_RO_MOUNT_PREFIX"?*|"$OCI_ENGINE_TRUSTED_DIR"/?*)
90+
"$OCI_ENGINE_TRUSTED_DIR"/?*)
7491
TRUSTED_STORAGE_HELPER="$1"
7592
;;
7693
*)
77-
echo "oci-engine: WARNING: refusing storage helper outside the read-only mount and $OCI_ENGINE_TRUSTED_DIR: $1; using $TRUSTED_STORAGE_HELPER." >&2
94+
echo "oci-engine: ERROR: storage helper outside the read-only mount and $OCI_ENGINE_TRUSTED_DIR: $1; refusing." >&2
95+
exit 1
7896
;;
7997
esac
8098
fi

‎integrations/isolation/acq-kits/oci-engine/scripts/verify‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,10 @@ trusted="$(in_sbx 'for f in /usr/local/lib/acq /usr/local/lib/acq/oci-engine /us
216216
# /usr/local/lib; one that ignores the flag publishes root-owned copies. Either is
217217
# fine, but ONE of them must be true for each file: a mount copy (probed here by
218218
# the same slug/cksum name acq derives) or a root-owned published copy. Neither
219-
# means the startup step has nothing to run, which FAILS this check.
219+
# means the startup step has nothing to run, which FAILS this check. The startup
220+
# step fails closed: when the consumer honored `readonly` (no agent-home copy), a
221+
# missing mount file is a failure even if a root-owned copy exists, because the
222+
# startup step will not use that copy.
220223
ro_probe='for p in /home/agent/oci-engine-grant-devs.sh /home/agent/oci-engine-config/oci-engine-storage-driver.sh; do s=$(printf "%s" "${p#/}" | tr -c "A-Za-z0-9" "-" | tr -s "-"); s=${s%-}; c=$(printf "%s" "$p" | cksum | cut -d" " -f1); if [ -f "/var/lib/acq/host/kit-files/$s.$c" ]; then echo "mount:$p"; else echo "nomount:$p"; fi; done'
221224
ro_state="$(in_sbx "$ro_probe")"
222225
agent_copies="$(in_sbx 'for f in /home/agent/oci-engine-grant-devs.sh /home/agent/oci-engine-config/oci-engine-storage-driver.sh; do [ -e "$f" ] && echo "present:$f"; done; true')"
@@ -236,11 +239,23 @@ elif ! { printf '%s\n' "$trusted" | grep -q '^0:0 755 /usr/local/lib/acq$' \
236239
&& printf '%s\n' "$trusted" | grep -q '^0:0 755 /usr/local/lib/acq/oci-engine/oci-engine-install\.sh$'; }; then
237240
bad "trusted startup path ownership/mode unexpected"
238241
printf ' %s\n' "$trusted" >&2
242+
elif [ "$grant_mnt" -ne "$helper_mnt" ]; then
243+
# The startup step classifies the two tokens together; a pair split between the
244+
# mount and the legacy path is refused, so device grant and storage
245+
# re-evaluation do not run.
246+
bad "only one of the grant script and storage helper is on the read-only mount: the startup step refuses a mixed selection"
247+
printf ' %s\n %s\n' "$trusted" "$ro_state" >&2
248+
elif [ -z "$agent_copies" ] && { [ "$grant_mnt" -eq 0 ] || [ "$helper_mnt" -eq 0 ]; }; then
249+
# No agent-home copy means the consumer honored `readonly` and selected the
250+
# mount for the startup tokens. A missing mount file then makes the startup
251+
# command refuse (fail closed) instead of falling back to a root-owned copy.
252+
bad "readonly was honored (no agent-home copy) but a selected mount file is missing: the startup step refuses, so device grant and storage re-evaluation do NOT run"
253+
printf ' %s\n %s\n' "$trusted" "$ro_state" >&2
239254
elif [ "$grant_pub" -eq 0 ] && [ "$grant_mnt" -eq 0 ]; then
240-
bad "startup grant script is neither on the read-only mount nor published root-owned: device grant would silently not run (install failed, or mount absent)"
255+
bad "startup grant script is neither on the read-only mount nor published root-owned: device grant would not run (install failed, or mount absent)"
241256
printf ' %s\n %s\n' "$trusted" "$ro_state" >&2
242257
elif [ "$helper_pub" -eq 0 ] && [ "$helper_mnt" -eq 0 ]; then
243-
bad "storage helper is neither on the read-only mount nor published root-owned: storage re-evaluation would silently not run"
258+
bad "storage helper is neither on the read-only mount nor published root-owned: storage re-evaluation would not run"
244259
printf ' %s\n %s\n' "$trusted" "$ro_state" >&2
245260
elif [ "$grant_pub" -eq 0 ] && [ -n "$agent_copies" ]; then
246261
bad "grant script runs from the read-only mount but a writable agent-home copy also exists"

‎integrations/isolation/acq-kits/oci-engine/spec.yaml‎

Lines changed: 46 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,8 @@ commands:
143143
# storage helper) into the root-owned directory ONLY when a consumer that does
144144
# not honor `readonly` copied them under /home/agent. Where `readonly` is
145145
# honored they are absent there and the startup step runs them from the
146-
# read-only mount instead. This command's argv stays the plain `sh -c <script>`
146+
# read-only mount instead (and refuses, rather than using these copies, if a
147+
# selected mount file is missing). This command's argv stays the plain `sh -c <script>`
147148
# form: the sbx translator only passes that form through intact.
148149
- phase: install
149150
user: "0"
@@ -162,18 +163,25 @@ commands:
162163
exit 0
163164
# STARTUP phase — every start, as root (uid "0"). The two trailing argv tokens
164165
# are the readonly: true files above, passed as WHOLE tokens ($1 grant script,
165-
# $2 storage helper). A consumer that mounts kit code read-only rewrites them to
166-
# its read-only mount path (/var/lib/acq/host/kit-files/...), and this command
167-
# then runs them from there: a sudo guest cannot edit that mount. A consumer
168-
# that does not know `readonly` leaves the tokens as /home/agent paths and
169-
# copies the files there as before. Each token is checked INDEPENDENTLY: it is
170-
# used only if it sits under /var/lib/acq/host/kit-files/ (and has no `..`);
171-
# anything else, including an /home/agent token, is replaced by the root-owned
172-
# copy the install step published under /usr/local/lib/acq/oci-engine/. So a
173-
# mixed rewrite (one token mounted, one not) never runs an agent-home path. A
174-
# mounted path that does not exist (staging failed) also falls back. If
175-
# neither a mounted nor a published grant script exists it warns loudly and
176-
# skips (scripts/verify fails in that state). GATED ON PODMAN: revokes any stale device grant
166+
# $2 storage helper). The command classifies them and FAILS CLOSED:
167+
# - Both under /var/lib/acq/host/kit-files/ (a consumer that mounts kit code
168+
# read-only rewrote them): run exactly those files. If either file is
169+
# missing, refuse: print an error to stderr, run nothing as root, exit 1. It
170+
# never falls back to a root-owned copy, because those copies came from
171+
# /home/agent at create time and are not host-authoritative across restarts.
172+
# - Both under /home/agent/ (a consumer that ignores `readonly`, or made no
173+
# selection): the LEGACY case. Run the root-owned copies the install step
174+
# published under /usr/local/lib/acq/oci-engine/, as before. If those are
175+
# absent it warns and exits 0 (install fell soft or the base had its own
176+
# engine).
177+
# - Anything else (one token mounted and one not, `..`, an unknown prefix, an
178+
# empty token): refuse, exit 1. A mixed pair means the consumer selected the
179+
# read-only mount for one file but not the other; guessing would run a
180+
# guest-writable copy.
181+
# A non-zero exit is safe for the consumer: acq's msb backend reports a failing
182+
# startup command as a warning and carries on; it never escalates. So a refusal
183+
# costs only the device grant and storage re-evaluation, and `scripts/verify`
184+
# fails in that state. GATED ON PODMAN: revokes any stale device grant
177185
# and exits if podman is absent (install fell soft, or the base had its own
178186
# engine and the kit early-outed) — no engine, no device grant (finding #3).
179187
# Otherwise re-grants /dev/net/tun + /dev/fuse to the agent (/dev is a devtmpfs
@@ -192,20 +200,35 @@ commands:
192200
- |
193201
mount=/var/lib/acq/host/kit-files/
194202
trusted=/usr/local/lib/acq/oci-engine
195-
pick() {
203+
refuse() {
204+
echo "oci-engine: ERROR: $1; refusing to run root startup code (device grant and storage re-evaluation NOT applied)." >&2
205+
exit 1
206+
}
207+
case "$1|$2" in
208+
*..*) refuse "path traversal in startup tokens" ;;
209+
esac
210+
kind() {
196211
case "$1" in
197-
*..*) printf '%s\n' "$2" ;;
198-
"$mount"?*) if [ -f "$1" ]; then printf '%s\n' "$1"; else printf '%s\n' "$2"; fi ;;
199-
*) printf '%s\n' "$2" ;;
212+
"$mount"?*) echo mount ;;
213+
/home/agent/?*) echo legacy ;;
214+
*) echo bad ;;
200215
esac
201216
}
202-
grant=$(pick "$1" "$trusted/oci-engine-grant-devs.sh")
203-
helper=$(pick "$2" "$trusted/oci-engine-storage-driver.sh")
204-
if [ -f "$grant" ]; then
205-
exec sh "$grant" "$helper"
217+
g=$(kind "$1")
218+
h=$(kind "$2")
219+
if [ "$g" = mount ] && [ "$h" = mount ]; then
220+
[ -f "$1" ] || refuse "selected read-only grant script is missing: $1"
221+
[ -f "$2" ] || refuse "selected read-only storage helper is missing: $2"
222+
exec sh "$1" "$2"
206223
fi
207-
echo "oci-engine: WARNING: no trusted startup script (not on the read-only mount, not published under $trusted); device grant and storage re-evaluation NOT applied." >&2
208-
exit 0
224+
if [ "$g" = legacy ] && [ "$h" = legacy ]; then
225+
if [ -f "$trusted/oci-engine-grant-devs.sh" ]; then
226+
exec sh "$trusted/oci-engine-grant-devs.sh" "$trusted/oci-engine-storage-driver.sh"
227+
fi
228+
echo "oci-engine: WARNING: no root-owned startup script under $trusted (install did not publish it); device grant and storage re-evaluation NOT applied." >&2
229+
exit 0
230+
fi
231+
refuse "unrecognized or mixed startup tokens ($g, $h)"
209232
- oci-engine-startup
210233
- /home/agent/oci-engine-grant-devs.sh
211234
- /home/agent/oci-engine-config/oci-engine-storage-driver.sh

0 commit comments

Comments
 (0)