You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 94f807a
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Nothing in this kit is a secret. podman needs no credentials to run rootless.
113
118
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
+
114
172
## Network egress
115
173
116
174
Two distinct egress needs, handled differently on purpose:
echo"oci-engine: WARNING: could not install trusted startup grant script; OCI setup unavailable.">&2
115
129
exit 0
116
130
fi
117
131
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
120
134
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
121
143
122
144
# 1) EARLY-OUT if the base image already provides a FUNCTIONAL container engine.
123
145
#
@@ -205,9 +227,13 @@ fi
205
227
# transient /dev/fuse miss at create is not permanently baked in — see the
206
228
# helper's comment and finding #4 in the kit's docs/decisions.
0 commit comments