Skip to content

Commit 9f24004

Browse files
committed
fix(test-guest): verify OCI cache provenance
Signed-off-by: Drew Newberry <[email protected]>
1 parent 49ae902 commit 9f24004

3 files changed

Lines changed: 78 additions & 14 deletions

File tree

‎architecture/build.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,9 @@ read-only and each test receives a fresh writable overlay and cloud-init
147147
identity. The optional shared cache stores the compressed standalone disk and
148148
its compatibility metadata as a custom OCI artifact. Normal test runs consume
149149
local entries only; the separate cache app owns OCI pulls, trusted builds, and
150-
explicit publication.
150+
explicit publication. OCI pulls require a trusted manifest digest and retain
151+
that provenance with the local entry; mutable tags are used only for explicit
152+
publication.
151153

152154
## Python Wheel Packaging
153155

‎nix/test-guest/README.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,13 +122,15 @@ nix run .#test-guest-cache -- \
122122
--with docker
123123
```
124124

125-
Configure an OCI repository to use it as a shared backing cache:
125+
Configure an OCI repository and a trusted manifest digest to use it as a shared
126+
backing cache:
126127

127128
```shell
128129
nix run .#test-guest-cache -- \
129130
--distro ubuntu \
130131
--with docker \
131-
--repository ghcr.io/nvidia/openshell/test-guest-cache
132+
--repository ghcr.io/nvidia/openshell/test-guest-cache \
133+
--digest sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
132134
```
133135

134136
The command never publishes implicitly. Add `--push` after authenticating ORAS through its Docker-compatible credential configuration:
@@ -141,6 +143,11 @@ nix run .#test-guest-cache -- \
141143
--push
142144
```
143145

146+
A successful push prints the immutable `repository@sha256:...` reference. Supply
147+
that digest to consumers through trusted CI configuration. Pulls by mutable tag
148+
are not allowed. A pulled local entry records its manifest digest and is reused
149+
only when it matches the requested trusted digest.
150+
144151
A cache build boots and configures a disposable VM, runs the internal sealing script, flattens the overlay into a standalone QCOW2 disk, and validates a fresh boot before committing the entry. The OCI artifact contains metadata and a `disk.qcow2.zst` layer.
145152

146153
The key includes the pinned base-image identity, guest architecture, ordered configuration file digests, Ansible version, cache generation, and sealing script digest. Installed packages, copied binaries, forwarded ports, and guest commands are never cached.
@@ -155,6 +162,7 @@ Cache command options:
155162
--distro NAME Base distro: ubuntu, centos, fedora, or rocky
156163
--with NAME Apply docker, podman, or selinux; repeatable
157164
--repository REF OCI repository without a tag
165+
--digest DIGEST Trusted OCI manifest digest required for pulls
158166
--cache-dir PATH Override the local prepared-disk cache directory
159167
--push Publish the ensured entry to the repository
160168
```

‎nix/test-guest/cache.sh‎

Lines changed: 65 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,14 @@ Options:
1515
--distro NAME Base distro: ubuntu, centos, fedora, or rocky
1616
--with NAME Apply a configuration; repeatable (docker, podman, selinux)
1717
--repository REF OCI repository without a tag
18+
--digest DIGEST Trusted OCI manifest digest required for pulls
1819
--cache-dir PATH Override the local prepared-disk cache directory
1920
--push Publish a newly built or local entry to the repository
2021
-h, --help Show this help
2122
2223
The command ensures one exact distro, architecture, and ordered configuration
23-
combination exists locally. It checks the local cache, pulls from OCI when a
24-
repository is configured, or builds and validates a prepared disk on a miss.
24+
combination exists locally. OCI pulls require a trusted manifest digest.
25+
Otherwise, the command builds and validates a prepared disk on a miss.
2526
Publishing is explicit and requires both --repository and --push.
2627
EOF
2728
}
@@ -48,6 +49,7 @@ require_value() {
4849

4950
distro=
5051
repository=${OPENSHELL_TEST_GUEST_CACHE_REPOSITORY:-}
52+
pull_digest=${OPENSHELL_TEST_GUEST_CACHE_DIGEST:-}
5153
cache_dir=
5254
push=0
5355
configurations=()
@@ -69,6 +71,11 @@ while [ "$#" -gt 0 ]; do
6971
repository=$2
7072
shift 2
7173
;;
74+
--digest)
75+
require_value "$@"
76+
pull_digest=$2
77+
shift 2
78+
;;
7279
--cache-dir)
7380
require_value "$@"
7481
cache_dir=$2
@@ -121,6 +128,19 @@ if [[ ${repository} == *[[:space:]]* ]] || [[ ${repository} == *@* ]]; then
121128
echo "--repository must be an untagged OCI repository reference" >&2
122129
exit 2
123130
fi
131+
if [ -n "${repository}" ] && [ "${push}" -eq 0 ] && [ -z "${pull_digest}" ]; then
132+
echo "--repository requires --digest for OCI pulls" >&2
133+
exit 2
134+
fi
135+
if [ -n "${pull_digest}" ] && [ -z "${repository}" ]; then
136+
echo "--digest requires --repository" >&2
137+
exit 2
138+
fi
139+
if [ -n "${pull_digest}" ] &&
140+
[[ ! ${pull_digest} =~ ^sha256:[a-f0-9]{64}$ ]]; then
141+
echo "--digest must be a lowercase sha256 OCI manifest digest" >&2
142+
exit 2
143+
fi
124144

125145
if [ -n "${cache_dir}" ]; then
126146
OPENSHELL_TEST_GUEST_CACHE_DIR=${cache_dir}
@@ -133,9 +153,13 @@ cache_key=$(test_vm_cache_key "${distro}" "${configurations[@]}")
133153
cache_tag=$(test_vm_cache_tag "${distro}" "${cache_key}")
134154
entry_dir=$(test_vm_cache_entry_dir "${cache_root}" "${cache_key}")
135155
remote_ref=
156+
pull_ref=
136157
if [ -n "${repository}" ]; then
137158
remote_ref="${repository}:${cache_tag}"
138159
fi
160+
if [ -n "${pull_digest}" ]; then
161+
pull_ref="${repository}@${pull_digest}"
162+
fi
139163

140164
mkdir -p "${cache_root}/entries" "${cache_root}/locks" "${cache_root}/staging"
141165

@@ -177,17 +201,21 @@ fi
177201
install_entry() {
178202
local disk=$1
179203
local metadata=$2
204+
local manifest_digest=${3:-}
180205
local temporary_entry
181206
temporary_entry=$(mktemp -d "${cache_root}/entries/.${cache_key}.XXXXXX")
182207
cp --sparse=always "${disk}" "${temporary_entry}/disk.qcow2"
183208
chmod 0444 "${temporary_entry}/disk.qcow2"
184209
install -m 0444 "${metadata}" "${temporary_entry}/metadata.json"
210+
if [ -n "${manifest_digest}" ]; then
211+
printf '%s\n' "${manifest_digest}" >"${temporary_entry}/manifest.digest"
212+
chmod 0444 "${temporary_entry}/manifest.digest"
213+
fi
185214
: >"${temporary_entry}/complete"
186215
chmod 0444 "${temporary_entry}/complete"
187216

188217
if [ -e "${entry_dir}" ]; then
189-
if test_vm_cache_local_entry_valid \
190-
"${cache_root}" "${cache_key}" "${distro}" "${configurations[@]}"; then
218+
if local_entry_valid; then
191219
rm -rf "${temporary_entry}"
192220
return
193221
fi
@@ -198,6 +226,16 @@ install_entry() {
198226
mv "${temporary_entry}" "${entry_dir}"
199227
}
200228

229+
local_entry_valid() {
230+
test_vm_cache_local_entry_valid \
231+
"${cache_root}" "${cache_key}" "${distro}" "${configurations[@]}" ||
232+
return 1
233+
if [ -n "${pull_digest}" ]; then
234+
[ -f "${entry_dir}/manifest.digest" ] &&
235+
[ "$(<"${entry_dir}/manifest.digest")" = "${pull_digest}" ]
236+
fi
237+
}
238+
201239
is_remote_miss() {
202240
grep -Eqi '404|MANIFEST_UNKNOWN|manifest unknown|not found' "$1"
203241
}
@@ -208,10 +246,21 @@ pull_remote() {
208246
local compressed_size
209247
local expected_sha
210248
local actual_sha
249+
local resolved_digest
211250
pull_dir=$(mktemp -d "${cache_root}/staging/pull.${cache_key}.XXXXXX")
212251
pull_log="${pull_dir}/oras.log"
213252

214-
if ! oras pull --output "${pull_dir}" "${remote_ref}" >"${pull_log}" 2>&1; then
253+
resolved_digest=$(oras resolve "${pull_ref}") || {
254+
rm -rf "${pull_dir}"
255+
return 2
256+
}
257+
if [ "${resolved_digest}" != "${pull_digest}" ]; then
258+
echo "OCI cache manifest digest does not match trusted digest" >&2
259+
rm -rf "${pull_dir}"
260+
return 2
261+
fi
262+
263+
if ! oras pull --output "${pull_dir}" "${pull_ref}" >"${pull_log}" 2>&1; then
215264
if is_remote_miss "${pull_log}"; then
216265
rm -rf "${pull_dir}"
217266
return 1
@@ -261,9 +310,10 @@ pull_remote() {
261310
return 2
262311
fi
263312

264-
install_entry "${pull_dir}/disk.qcow2" "${pull_dir}/metadata.json"
313+
install_entry \
314+
"${pull_dir}/disk.qcow2" "${pull_dir}/metadata.json" "${resolved_digest}"
265315
rm -rf "${pull_dir}"
266-
echo "==> Cache remote hit: ${remote_ref}"
316+
echo "==> Cache remote hit: ${pull_ref}"
267317
}
268318

269319
build_local() {
@@ -378,11 +428,14 @@ build_local() {
378428
push_remote() {
379429
local push_dir
380430
local manifest_log
431+
local published_digest
381432
push_dir=$(mktemp -d "${cache_root}/staging/push.${cache_key}.XXXXXX")
382433
manifest_log="${push_dir}/manifest.log"
383434

384435
if oras manifest fetch "${remote_ref}" >"${manifest_log}" 2>&1; then
385436
echo "==> Cache already published: ${remote_ref}"
437+
published_digest=$(oras resolve "${remote_ref}")
438+
echo "==> Cache immutable reference: ${repository}@${published_digest}"
386439
rm -rf "${push_dir}"
387440
return
388441
fi
@@ -405,13 +458,14 @@ push_remote() {
405458
"metadata.json:${TEST_GUEST_CACHE_METADATA_TYPE}" \
406459
"disk.qcow2.zst:${TEST_GUEST_CACHE_DISK_TYPE}"
407460
)
461+
published_digest=$(oras resolve "${remote_ref}")
408462
rm -rf "${push_dir}"
409463
echo "==> Cache push complete: ${remote_ref}"
464+
echo "==> Cache immutable reference: ${repository}@${published_digest}"
410465
}
411466

412467
echo "==> Cache key: ${cache_key}"
413-
if test_vm_cache_local_entry_valid \
414-
"${cache_root}" "${cache_key}" "${distro}" "${configurations[@]}"; then
468+
if local_entry_valid; then
415469
echo "==> Cache local hit: ${entry_dir}"
416470
else
417471
if [ -e "${entry_dir}" ]; then
@@ -421,15 +475,15 @@ else
421475
fi
422476

423477
pulled=0
424-
if [ -n "${remote_ref}" ]; then
478+
if [ -n "${pull_ref}" ]; then
425479
if pull_remote; then
426480
pulled=1
427481
else
428482
pull_status=$?
429483
if [ "${pull_status}" -ne 1 ]; then
430484
exit "${pull_status}"
431485
fi
432-
echo "==> Cache remote miss: ${remote_ref}"
486+
echo "==> Cache remote miss: ${pull_ref}"
433487
fi
434488
fi
435489
if [ "${pulled}" -eq 0 ]; then

0 commit comments

Comments
 (0)