Skip to content

Commit 94f807a

Browse files
authored
feat(kits): run oci-engine root startup scripts from the read-only host mount (#543)
## Summary Lets a Quickstart MSB consumer run the oci-engine kit's root startup scripts from a host-authoritative read-only mount instead of agent-writable copies (the Patterns side of audit finding G3 under GSA-TTS/agentic-coding-quickstart#503). The oci-engine grant script and storage-driver helper are marked `readonly: true` and passed to the root startup command as whole argv tokens. ## Context A sudo guest can edit the guest-resident files that root re-runs on every MSB heal. Quickstart's read-only mount mechanism (`_acq_msb_stage_readonly_file`, present from v4.0.2) rewrites exact argv tokens to `/var/lib/acq/host/kit-files/...` for kits that opt in, but no shipped kit did. Pairs with the MSB host-recorded `:ro` decision in [Quickstart PR #637](GSA-TTS/agentic-coding-quickstart#637), which removes the guest probe from that decision. If the host fails to stage one of the two files, the pair is mixed and is refused for that boot. ## Changes - `oci-engine`: `readonly: true` on the grant script and storage helper. The root startup command classifies its two tokens together. **Both under `/var/lib/acq/host/kit-files/`** (no `..`): run those files, or refuse (stderr error, exit 1) if either is missing; it never falls back to the root-owned copy. **Both `/home/agent/*`:** the legacy case for a consumer that ignores the flag; it uses the root-owned copy published at create time, as before. **Anything else, including a mixed pair:** refuse. The grant script re-validates the helper it sources as root and refuses a missing selected mount helper. A refusal costs only that boot's device grant and storage re-evaluation; Quickstart reports a failing startup command as a warning and continues. - `readonly` registered in `schemas/kit-hybrid-v1.schema.json`; `validate-kits.py` rejects any value but the literal `true`/`false` and flow-style `command:` lists (the consumer's line-based reader ignores or drops them). - `zscaler-ca-certificate` and `opendesign` are intentionally not marked (reasons in their READMEs): the zscaler cert is staged at start with no create-time root-owned copy to fall back to, and opendesign's only root command is an inline `mkdir`/`chown`. - Loud warnings and `scripts/verify` cover "neither the mount copy nor a published copy exists"; the install phase's trust in `/home/agent` at create time is documented. ## Verification - Full `scripts/tests` (715 passed), `validate-kits --strict`, `make validate`, `make generate-check`, markdownlint on the changed docs. - Offline tests run the real startup body, grant script and install script against a temp tree: missing mount grant, missing mount helper, legacy fallback, mixed and traversal cases. Mutation checks (falling back on a missing mount file, allowing a mixed pair, removing the `..` check, a refusal that exits 0, the grant script accepting `/home/agent`) each fail a test. - Two independent adversarial reviews, then a third round after an external review. Not run: `make ci`, shellcheck, any live msb/sbx sandbox. ## Rollout Needs a Patterns release and a `PATTERNS_KIT_REF` pin bump in Quickstart. Older Quickstart releases (v4.0.0 to v4.0.2) and sbx ignore the flag and use the root-owned fallback, so nothing regresses there. Live MSB check after the bump: argv carries `/var/lib/acq/host/kit-files/...`, no scripts remain in `/home/agent`, device grants and storage driver still apply, a write to the mount fails (EROFS), and an older sandbox with no `:ro` mount takes the fallback with the warning. Also confirm storage is configured before first use now that install no longer seeds `storage.conf` when the flag is honored. ## Rollback Revert this PR. ## Security impact Removes a path where root could execute a guest-writable or create-time copy after the backend had selected the read-only mount. Residual: the install step still trusts `/home/agent` at create time, the root-owned legacy copies are guest-tamperable under `sudo` (so the legacy path is not tamper-resistant, unchanged from before), and the read-only property depends on the backend's mount enforcement. AI-assisted (OpenCode); human review required. Co-authored-by: OpenCode Agent <[email protected]>
1 parent 918e46d commit 94f807a

14 files changed

Lines changed: 898 additions & 36 deletions

File tree

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ vocabulary:
6060
- `caps.network.allow` — outbound egress hosts.
6161
- `files[]` — files to drop into the guest (inline `content` or a `source:`
6262
under the kit's `files/` tree), optionally tagged with a lifecycle `phase`.
63+
`readonly: true` marks a file whose bytes are trusted **code** that root runs
64+
at startup; see [Read-only startup code](#read-only-startup-code).
6365
- `commands[]` — lifecycle commands, each with a `phase` (`install` /
6466
`initFiles` / `startup`), `user`, and argv `command`.
6567
- `agentContext` — markdown surfaced to the agent.
@@ -141,3 +143,50 @@ the split cannot rot in either direction: converting a kit without moving it
141143
fails, a converted kit reverting fails, and a README edit alone fails. The
142144
unconverted list must reach empty, at which point this carve-out goes away and
143145
the contract above applies to every kit.
146+
147+
## Read-only startup code
148+
149+
A `files[]` entry may set `readonly: true` (it requires `source:`). The flag
150+
tells a consumer that the file is trusted code and should not run from a
151+
guest-writable copy, because a guest user with `sudo` can edit any file in the
152+
guest, including a root-owned one. A consumer that supports it (acq's `msb`
153+
backend, quickstart ADR-0035) keeps the file on a host-authoritative read-only
154+
mount, does **not** copy it to `path`, and replaces any `commands[]` argv
155+
element that is **exactly** `path` with the mounted location. A consumer that
156+
does not know the flag ignores it and copies the file to `path` as before.
157+
158+
Rules for kit authors:
159+
160+
- Pass the file to the command as a **whole argv element**. A path buried inside
161+
an `sh -c` script string, or built from a variable, is not rewritten, so the
162+
command would look for a file that was never copied. `validate-kits.py`
163+
rejects a `readonly` file that no command passes as a whole element.
164+
- Write the command so it is safe on **both** consumers. When the flag is not
165+
honored the argv element is still the original `path`, which is
166+
agent-writable. A root command must validate **each** such token on its own
167+
against the allowed prefix (the read-only mount, `/var/lib/acq/host/kit-files/`)
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.
173+
Checking only one token lets a partial rewrite slip an agent path through the
174+
other. A kit with no root-owned copy to fall back on (the file is staged at
175+
start, so nothing publishes it at create) should not use the flag; see
176+
`zscaler-ca-certificate`.
177+
- Write `readonly` as the literal `true` and `command:` as a block list. The acq
178+
consumer reads specs with a line-based reader that only recognizes the string
179+
`true` and drops flow-style `[a, b]` argv lists; `validate-kits.py` rejects both.
180+
- Do not set it on a file the kit or the user modifies at runtime, a file other
181+
code reads by a fixed path, or a file a command copies by path. Those files
182+
are not copied to `path` when the flag is honored.
183+
- Expect the whole-element rewrite in every phase `msb` runs. Do not rely on
184+
the file existing at `path` in any command, including `install` commands.
185+
186+
Shipped kit that uses it: `oci-engine` (root startup grant script and the
187+
storage helper it sources). `zscaler-ca-certificate` and `opendesign` do not; see
188+
their READMEs.
189+
190+
The `install` phase still trusts `/home/agent` at create time: it runs before the
191+
agent has had a session, and `readonly` protects the startup code that runs on
192+
every later start.

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

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,10 @@ On **every start** (the `startup` phase, run as root) — **only if podman is
4141
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
44-
them, are copied into `/usr/local/lib/acq/oci-engine/` and executed/sourced only
45-
from those root-owned copies, not from the agent-home staging files. `/dev` is a devtmpfs
44+
them, run only from a host-authoritative read-only mount (when the consumer honors
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
4648
re-created each boot, so both must re-run on restart, not just at create;
4749
re-evaluating the driver each boot lets it **converge from `vfs` to `overlay`**
4850
once `fuse-overlayfs` and `/dev/fuse` are both available (a transient `/dev/fuse`
@@ -96,8 +98,11 @@ engine")** decision, declaratively:
9698
inside the sandbox, which is itself the security boundary.
9799
- **Trusted elevated code.** Files are staged in the agent home by the neutral
98100
kit mechanism, but root phases do not execute or source those mutable copies.
99-
The root command wrappers publish the install script, startup script, and sourced
100-
helper into `/usr/local/lib/acq/oci-engine/` and use only those root-owned files.
101+
The root command wrappers publish the install script into
102+
`/usr/local/lib/acq/oci-engine/`; the startup script and sourced helper run from
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.
101106
- **Least-privilege registry resolution.** `short-name-mode` defaults to
102107
**`enforcing`**, not `permissive`. Because there is a single search registry
103108
(`docker.io`), unqualified names still resolve deterministically to Docker Hub
@@ -111,6 +116,59 @@ engine")** decision, declaratively:
111116

112117
Nothing in this kit is a secret. podman needs no credentials to run rootless.
113118

119+
### Read-only startup code
120+
121+
The root `startup` step runs two kit files: `oci-engine-grant-devs.sh` and the
122+
`oci-engine-storage-driver.sh` helper it sources. Both are declared
123+
`readonly: true` and passed to the step as whole argv elements. A consumer that
124+
honors the flag (acq `msb`, quickstart ADR-0035) runs them from a
125+
host-authoritative read-only mount, so a guest user with `sudo` cannot edit what
126+
root executes on each start. A consumer that ignores the flag copies them under
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.
160+
161+
The install step still trusts `/home/agent` at create time (it publishes the
162+
staged copies into the root-owned directory, before the agent's first session).
163+
The read-only mount protects the startup code on every later start.
164+
165+
Not marked `readonly`, on purpose: `oci-engine-install.sh` (an inline install
166+
command copies it by path), `oci-engine-vfs-fallback.sh` (runs as the agent,
167+
not root), and the `docker` wrapper and `01-acq-shortnames.conf` (the install
168+
script copies them by path, which needs them at `/home/agent`). When the flag is
169+
honored, the install step does not publish the grant script or helper; the
170+
`startup` step configures the storage driver on that same boot.
171+
114172
## Network egress
115173

116174
Two distinct egress needs, handled differently on purpose:

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,18 @@ direction and flagged six implementation defects, all addressed here:
155155
`/usr/local/lib/acq/oci-engine/` as root-owned files, and execute/source only
156156
those trusted copies. The grant script does not fall back to agent-home staging.
157157

158+
> **Superseded in part** by the `readonly: true` startup files (quickstart
159+
> ADR-0035). The grant script and storage helper are now declared `readonly`:
160+
> 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 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.
169+
158170
8. **Stale device grant after podman disappears.** The no-podman startup path now
159171
best-effort resets `/dev/net/tun` and `/dev/fuse` to `root:root` `0600` before
160172
exiting, so a grant from an earlier successful boot is not intentionally left in

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

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

58-
# Root-owned helper installed by oci-engine-install.sh. Do not source helper code
59-
# from the agent-writable staging path on startup.
60-
TRUSTED_STORAGE_HELPER="/usr/local/lib/acq/oci-engine/oci-engine-storage-driver.sh"
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.
70+
OCI_ENGINE_TRUSTED_DIR="/usr/local/lib/acq/oci-engine"
71+
OCI_ENGINE_RO_MOUNT_PREFIX="/var/lib/acq/host/kit-files/"
72+
TRUSTED_STORAGE_HELPER="$OCI_ENGINE_TRUSTED_DIR/oci-engine-storage-driver.sh"
73+
if [ "$#" -ge 1 ]; then
74+
case "$1" in
75+
"")
76+
echo "oci-engine: ERROR: empty storage helper path; refusing." >&2
77+
exit 1
78+
;;
79+
*..*)
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"
89+
;;
90+
"$OCI_ENGINE_TRUSTED_DIR"/?*)
91+
TRUSTED_STORAGE_HELPER="$1"
92+
;;
93+
*)
94+
echo "oci-engine: ERROR: storage helper outside the read-only mount and $OCI_ENGINE_TRUSTED_DIR: $1; refusing." >&2
95+
exit 1
96+
;;
97+
esac
98+
fi
6199

62100
# The unprivileged user the engine runs as. Non-secret; overridable via the
63101
# OCI_ENGINE_AGENT_USER env var (declared in spec.yaml environment) for a base

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

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -100,24 +100,46 @@ if ! mkdir -p "$TRUSTED_DIR" 2>/dev/null \
100100
echo "oci-engine: WARNING: could not prepare trusted root startup directory; OCI setup unavailable." >&2
101101
exit 0
102102
fi
103+
# The storage helper and the startup grant script are `readonly: true` kit files.
104+
# A consumer that honors the flag (acq msb, quickstart ADR-0035) keeps them OFF the
105+
# agent-writable disk and runs/sources them from a host-authoritative read-only
106+
# mount at every startup, so there is nothing here to publish. A consumer that
107+
# ignores the flag copies them under /home/agent as before; publish root-owned
108+
# copies of whatever was staged so the startup step has something trusted to run.
109+
#
110+
# TRUST NOTE: this install step still trusts /home/agent at CREATE time. It copies
111+
# whatever is staged there into the root-owned directory, which is safe only
112+
# because the sandbox has just been created and the agent has not yet had a
113+
# session. The tamper resistance of `readonly` applies to the startup phase on
114+
# every later start, not to this step.
115+
RO_MOUNT_DIR="/var/lib/acq/host/kit-files"
116+
_stage_missing=0
103117
if [ -f "$STAGE_DIR/oci-engine-storage-driver.sh" ]; then
104118
if ! install -m 0644 "$STAGE_DIR/oci-engine-storage-driver.sh" "$TRUSTED_STORAGE_HELPER"; then
105119
echo "oci-engine: WARNING: could not install trusted storage helper; OCI setup unavailable." >&2
106120
exit 0
107121
fi
108122
else
109-
echo "oci-engine: WARNING: staged storage helper missing; cannot configure OCI storage." >&2
110-
exit 0
123+
_stage_missing=1
124+
echo "oci-engine: note: storage helper not staged under $STAGE_DIR (read-only kit file); the startup step will configure storage." >&2
111125
fi
112126
if [ -f "$STAGED_GRANT_SCRIPT" ]; then
113127
if ! install -m 0755 "$STAGED_GRANT_SCRIPT" "$TRUSTED_GRANT_SCRIPT"; then
114128
echo "oci-engine: WARNING: could not install trusted startup grant script; OCI setup unavailable." >&2
115129
exit 0
116130
fi
117131
else
118-
echo "oci-engine: WARNING: staged startup grant script missing; startup device grant unavailable." >&2
119-
exit 0
132+
_stage_missing=1
133+
echo "oci-engine: note: startup grant script not staged under /home/agent (read-only kit file); the startup step runs it from the read-only mount." >&2
120134
fi
135+
# A staged file may be absent because the consumer honored `readonly` (the files
136+
# are on the read-only mount) or because the file copy failed. Tell them apart:
137+
# with neither a staged copy nor the mount, the startup step has nothing to run
138+
# and device grant + storage re-evaluation will silently not happen. Say so loudly.
139+
if [ "$_stage_missing" -eq 1 ] && [ ! -d "$RO_MOUNT_DIR" ]; then
140+
echo "oci-engine: WARNING: kit startup files are neither staged under /home/agent nor available on $RO_MOUNT_DIR; the startup step will NOT grant devices or configure storage." >&2
141+
fi
142+
unset _stage_missing
121143

122144
# 1) EARLY-OUT if the base image already provides a FUNCTIONAL container engine.
123145
#
@@ -205,9 +227,13 @@ fi
205227
# transient /dev/fuse miss at create is not permanently baked in — see the
206228
# helper's comment and finding #4 in the kit's docs/decisions.
207229
mkdir -p /etc/containers
208-
# shellcheck source=files/home/oci-engine-config/oci-engine-storage-driver.sh
209-
. "$TRUSTED_STORAGE_HELPER"
210-
oci_engine_write_storage_conf
230+
if [ -f "$TRUSTED_STORAGE_HELPER" ]; then
231+
# shellcheck source=files/home/oci-engine-config/oci-engine-storage-driver.sh
232+
. "$TRUSTED_STORAGE_HELPER"
233+
oci_engine_write_storage_conf
234+
else
235+
echo "oci-engine: note: storage driver selection deferred to the startup step (helper is a read-only kit file)." >&2
236+
fi
211237

212238
# 4) Docker-Hub-first registry resolution (ADR-0020). System-level so it applies
213239
# to the rootless agent (read as the lowest-precedence source). Install the

0 commit comments

Comments
 (0)