From bd82bae107c91a0d6ed10b7218e87fa31ecbb458 Mon Sep 17 00:00:00 2001 From: "sec-check[bot]" Date: Sat, 19 Sep 2026 03:33:31 -0400 Subject: [PATCH] fix(kernel-cache): hash Containerfile.kernel whole so a recipe edit rotates the tag scripts/kernel-cache-tag.sh hashed only the ARG BASE_IMAGE= line of Containerfile.kernel, but the body of that file is the recipe: the single RUN decides what lands in /cache-out and the final stage decides what is copied out of the builder. Editing either left the tag unchanged, and CI builds the cache image only when its tag is not already published, so the gaming, nvidia and nvidia-gaming flavors would take a cache image built from the previous recipe and unpack stale artifacts without any failure. Hash the whole file instead. This strictly widens the key -- the base image pin is still covered, so Renovate bumps still rotate the tag -- and restores the bias the script documents, which is to over-rebuild rather than ever reuse something stale. tests/test_kernel_cache_tag.py holds the contract: every hashed input moves the tag, and a recipe edit that leaves ARG BASE_IMAGE= alone moves it too. Both new assertions fail against the previous implementation. The key rotates once as a result, so the next build of each cached flavor pays one ~45-minute cache rebuild. Signed-off-by: sec-check[bot] --- AGENTS.md | 2 +- docs/skills/index.json | 4 +- docs/skills/index.md | 2 +- docs/skills/kernel-cache.md | 18 +++-- scripts/kernel-cache-tag.sh | 18 +++-- tests/test_kernel_cache_tag.py | 126 +++++++++++++++++++++++++++++++++ 6 files changed, 157 insertions(+), 13 deletions(-) create mode 100644 tests/test_kernel_cache_tag.py diff --git a/AGENTS.md b/AGENTS.md index 92965df25..6655a3775 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,7 +58,7 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`, before editing it: sources arrive in as few COPYs as origins allow, small RUN steps fold into neighbours, and per-image ARGs are declared late because an ARG is part of the cache key of every layer below it. -- **The kernel cache tag** is a hash of `Containerfile.kernel`'s base image, +- **The kernel cache tag** is a hash of `Containerfile.kernel` (whole file), `scripts/install-ogc-kernel.sh`, `scripts/install-nvidia.sh`, and `packages/hummingbird.repo` (`scripts/kernel-cache-tag.sh`). Any edit to those files — comments included — forces a ~45-minute cache rebuild. That is diff --git a/docs/skills/index.json b/docs/skills/index.json index a94b71151..f11bec450 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-09-18", + "generated_at": "2026-09-19", "schema_version": "1.0", "skills": [ { @@ -88,7 +88,7 @@ ], "description": "The kernel cache image, its content-hash tag, and unpack-or-compile behavior. Use when touching install-ogc-kernel.sh, install-nvidia.sh, Containerfile.kernel, or debugging flavored builds.", "version": "1.0", - "last_updated": "2026-09-05", + "last_updated": "2026-09-19", "doc_type": "reference" }, { diff --git a/docs/skills/index.md b/docs/skills/index.md index c62b2f2eb..d3800c2cb 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -3,7 +3,7 @@ This file is a human-readable mirror of `index.json`. Both are generated by `scripts/generate_skill_index.py` — do not hand-edit either file. -Generated: 2026-09-18 · schema 1.0 · 8 skills +Generated: 2026-09-19 · schema 1.0 · 8 skills | id | category | status | one-line purpose | |---|---|---|---| diff --git a/docs/skills/kernel-cache.md b/docs/skills/kernel-cache.md index 2dab3d3c0..b48397b3a 100644 --- a/docs/skills/kernel-cache.md +++ b/docs/skills/kernel-cache.md @@ -1,7 +1,7 @@ --- name: kernel-cache version: "1.0" -last_updated: "2026-09-05" +last_updated: "2026-09-19" id: kernel-cache one_line_purpose: Understand and rebuild the OGC kernel and NVIDIA module cache image. entry_point: docs/skills/kernel-cache.md @@ -48,21 +48,31 @@ The tag must change whenever anything the cache image contains would change, and not otherwise, so it is a hash of exactly those inputs (header comment, `scripts/kernel-cache-tag.sh`): -- The `ARG BASE_IMAGE=` line of `Containerfile.kernel` -- the base image the - cache is built from. +- `Containerfile.kernel`, whole file -- the recipe that builds the cache. Its + `ARG BASE_IMAGE=` line names the base image, but its body is what decides + what the image ends up containing: the repo files copied into the builder, + and the single `RUN` that fills `/cache-out`, and the final stage's + `COPY --from=builder`. Hashing only the `ARG` line would leave an edit to + any of that invisible to the key, and since CI builds the cache image only + when its tag is not already published, the three cached flavors would + silently take an image built from the previous recipe. - `scripts/install-ogc-kernel.sh` and `scripts/install-nvidia.sh`, whole files, comments included -- the two scripts that do the building. - `packages/hummingbird.repo` and `packages/fedora-44.repo` -- the repositories the toolchain comes from (Fedora 44 is builder-only); a different compiler produces a different kernel. -Editing either script changes the hash and forces a rebuild, comment-only +Editing any of them changes the hash and forces a rebuild, comment-only edits included. That is deliberate: the key can only ever rebuild something that did not need rebuilding, never reuse something stale. A cheaper key that hashed just the version pins would miss a change to how the kernel is configured or how the module is linked (header comment, `scripts/kernel-cache-tag.sh`). +`tests/test_kernel_cache_tag.py` holds the key to that contract: it asserts +that mutating a non-`ARG` line of `Containerfile.kernel`, or any of the four +other hashed files, moves the tag. + The `BASE_IMAGE` in `Containerfile.kernel` must match the one in `Containerfile`, or the prebuilt NVIDIA module would be linked against a kernel the image never boots. Two literals, one invariant, so `just check` diff --git a/scripts/kernel-cache-tag.sh b/scripts/kernel-cache-tag.sh index 3983d3378..f236e56d7 100755 --- a/scripts/kernel-cache-tag.sh +++ b/scripts/kernel-cache-tag.sh @@ -2,19 +2,27 @@ # The tag under which the kernel cache image is published. # # It must change whenever anything the cache image contains would change, and -# not otherwise. Those inputs are the base image it is built from, the two -# scripts that do the building, and the repositories the toolchain comes from -- -# a different compiler produces a different kernel -- so the tag is a hash of +# not otherwise. Those inputs are the recipe that builds it, the two scripts +# that do the building, and the repositories the toolchain comes from -- a +# different compiler produces a different kernel -- so the tag is a hash of # exactly those. # -# Hashing the whole scripts, comments included, is deliberate: it can only ever +# Containerfile.kernel is hashed whole, not just its ARG BASE_IMAGE= line: its +# body is the recipe. The single RUN decides what lands in /cache-out and the +# final stage decides what is copied out of the builder, so an edit there +# changes the image's contents while leaving the base pin untouched. Since CI +# builds the cache image only when its tag is not already published, a key that +# missed those edits would silently hand the three cached flavors an image +# built from the previous recipe. +# +# Hashing the whole files, comments included, is deliberate: it can only ever # rebuild something that did not need rebuilding, never reuse something stale. # A cheaper key that hashed just the version pins would miss a change to how # the kernel is configured or how the module is linked. set -euo pipefail cd "$(dirname "$0")/.." { - grep -m1 '^ARG BASE_IMAGE=' Containerfile.kernel + cat Containerfile.kernel cat scripts/install-ogc-kernel.sh scripts/install-nvidia.sh cat packages/hummingbird.repo packages/fedora-44.repo } | sha256sum | cut -c1-16 diff --git a/tests/test_kernel_cache_tag.py b/tests/test_kernel_cache_tag.py new file mode 100644 index 000000000..76392b5ee --- /dev/null +++ b/tests/test_kernel_cache_tag.py @@ -0,0 +1,126 @@ +"""The kernel cache tag must move whenever the cache image's contents would. + +CI builds and pushes the cache image only when `just kernel-cache-tag` names a +tag that is not already published, and the gaming, nvidia and nvidia-gaming +builds take that image as their BASE_IMAGE. So a key that misses an input does +not fail anything -- it hands those three flavors an image built from the +previous recipe, and the only symptom is a kernel build that did not happen. + +These tests copy the repository's hashed inputs into a scratch tree, mutate one +at a time, and assert the tag changes. The mutations are deliberately shallow +(a trailing comment) because the contract is "any edit, comments included", not +"any semantically significant edit". +""" + +from __future__ import annotations + +import shutil +import subprocess +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SCRIPT = ROOT / "scripts" / "kernel-cache-tag.sh" + +# Every file the tag is required to cover, relative to the repository root. +HASHED_INPUTS = ( + "Containerfile.kernel", + "scripts/install-ogc-kernel.sh", + "scripts/install-nvidia.sh", + "packages/hummingbird.repo", + "packages/fedora-44.repo", +) + + +def tag_of(root: Path) -> str: + """Run the real script against `root` and return the tag it prints.""" + result = subprocess.run( + ["bash", str(root / "scripts" / "kernel-cache-tag.sh")], + capture_output=True, + text=True, + ) + if result.returncode != 0: + raise AssertionError(f"kernel-cache-tag.sh failed:\n{result.stderr}") + return result.stdout.strip() + + +class KernelCacheTagTests(unittest.TestCase): + def setUp(self): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + self.root = Path(tmp.name) / "utah" + (self.root / "scripts").mkdir(parents=True) + (self.root / "packages").mkdir(parents=True) + shutil.copy2(SCRIPT, self.root / "scripts" / "kernel-cache-tag.sh") + for rel in HASHED_INPUTS: + shutil.copy2(ROOT / rel, self.root / rel) + self.baseline = tag_of(self.root) + + def test_tag_is_a_short_stable_hex_digest(self): + self.assertRegex(self.baseline, r"^[0-9a-f]{16}$") + self.assertEqual(self.baseline, tag_of(self.root), "tag is not deterministic") + + def test_tag_matches_the_real_repository(self): + """The scratch tree reproduces the tag the repository itself produces.""" + self.assertEqual(self.baseline, tag_of(ROOT)) + + def test_every_hashed_input_moves_the_tag(self): + for rel in HASHED_INPUTS: + with self.subTest(input=rel): + path = self.root / rel + original = path.read_text() + path.write_text(original + "\n# cache-key probe\n") + self.addCleanup(path.write_text, original) + self.assertNotEqual( + self.baseline, + tag_of(self.root), + f"editing {rel} left the kernel cache tag unchanged, so CI would " + f"reuse the previously published cache image", + ) + path.write_text(original) + + def test_containerfile_recipe_body_moves_the_tag(self): + """A recipe edit that leaves `ARG BASE_IMAGE=` alone must still rotate. + + Hashing only the `ARG BASE_IMAGE=` line was the original defect: the + single RUN decides what lands in /cache-out and the final stage decides + what is copied out, and neither is on that line. + """ + path = self.root / "Containerfile.kernel" + original = path.read_text() + self.assertIn("/cache-out", original) + mutated = original.replace("/cache-out", "/cache-out-probe") + self.assertNotEqual(original, mutated) + + arg_line = "ARG BASE_IMAGE=" + before = [ln for ln in original.splitlines() if ln.startswith(arg_line)] + after = [ln for ln in mutated.splitlines() if ln.startswith(arg_line)] + self.assertEqual(before, after, "probe must not touch the base image pin") + + path.write_text(mutated) + self.addCleanup(path.write_text, original) + self.assertNotEqual( + self.baseline, + tag_of(self.root), + "a Containerfile.kernel recipe change that leaves ARG BASE_IMAGE= " + "alone did not change the tag, so the published cache image would " + "be reused for a recipe that no longer builds it", + ) + + def test_base_image_pin_still_moves_the_tag(self): + """Widening the key must not drop what it already covered.""" + path = self.root / "Containerfile.kernel" + original = path.read_text() + mutated = "\n".join( + line.replace("sha256:", "sha256:0") if line.startswith("ARG BASE_IMAGE=") else line + for line in original.splitlines() + ) + self.assertNotEqual(original, mutated, "no ARG BASE_IMAGE= digest to mutate") + path.write_text(mutated + "\n") + self.addCleanup(path.write_text, original) + self.assertNotEqual(self.baseline, tag_of(self.root)) + + +if __name__ == "__main__": + unittest.main()