From 5924c5b93b7b709f4c0845268af8cbb05b650967 Mon Sep 17 00:00:00 2001 From: Timothy Wayne Gregg Date: Sun, 25 Oct 2026 23:02:20 -0400 Subject: [PATCH] Preserve healthy siblings when image planning fails --- README.md | 10 +++ SHA256SUMS | 2 +- oci_runtime_inventory.py | 43 ++++++++----- test_sibling_planning.py | 127 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 165 insertions(+), 17 deletions(-) create mode 100644 test_sibling_planning.py diff --git a/README.md b/README.md index 58d50a5..5dc7d4f 100644 --- a/README.md +++ b/README.md @@ -135,4 +135,14 @@ as unscoped Sharp/Flowise/Node names. Layer reads share a 200,000-call budget, bounding per-byte gzip header processing as well as byte/expansion limits. OCI image planning errors produce an incomplete image record while independently supported sibling images retain their observations. Limits remain shared across images. +Malformed child OCI indexes and independent Docker-save entries are localized +to incomplete records while supported siblings retain package observations and +digest provenance, regardless of sibling order. A rejected child index retains +its verified descriptor identity; a Docker entry retains its config digest only +after the config bytes have been read, otherwise its identity is `unknown`. +Rejected entries provide no consumer records. Overall status remains incomplete +and exits 2. Corruption of the root layout/index or exhaustion of global planning +limits may still prevent archive inspection; shared budgets are never reset for +a sibling. + Every candidate package.json is captured and strictly parsed before its package name is known. Irrelevant manifests still consume the shared capture budget; malformed or excessive candidates make that image incomplete. These deliberately conservative bounds can reject large valid images/SBOMs. OCI attestation manifests and unsupported layer media types are recorded as incomplete; platform labels are not collected. No-force publication requires hard-link support and fails closed otherwise. diff --git a/SHA256SUMS b/SHA256SUMS index 42e5548..acb345b 100644 --- a/SHA256SUMS +++ b/SHA256SUMS @@ -1 +1 @@ -21d6cbd46b86c101b346d507ed0de30af6f6655fc8b4825ce7b6c2b0ec44c4fe oci_runtime_inventory.py +e4bec83a0e16bdfb7935040844535a82164d113b16c3d9aea17c3284242cadd4 oci_runtime_inventory.py diff --git a/oci_runtime_inventory.py b/oci_runtime_inventory.py index 9679b95..05cc2d9 100644 --- a/oci_runtime_inventory.py +++ b/oci_runtime_inventory.py @@ -304,6 +304,14 @@ def blob_json(stream, index, descriptor, budget): def image_plans(stream, index, budget): + def index_descriptors(document, depth): + if not isinstance(document, dict) or type(document.get("schemaVersion")) is not int or document["schemaVersion"] != 2: + raise InventoryError("unsupported_index_schema_version") + descriptors = document.get("manifests") + if depth > 3 or not isinstance(descriptors, list) or len(descriptors) > MAX_IMAGES: + raise InventoryError("invalid_or_excessive_image_index") + return descriptors + plans = [] if "oci-layout" in index: if json_value(read_member(stream, index, "oci-layout", budget)) != {"imageLayoutVersion": "1.0.0"}: @@ -313,11 +321,7 @@ def image_plans(stream, index, budget): visits = 0 while pending: document, depth = pending.pop() - if not isinstance(document,dict) or type(document.get("schemaVersion")) is not int or document["schemaVersion"] != 2: - raise InventoryError("unsupported_index_schema_version") - descriptors = document.get("manifests") - if depth > 3 or not isinstance(descriptors, list) or len(descriptors) > MAX_IMAGES: - raise InventoryError("invalid_or_excessive_image_index") + descriptors = index_descriptors(document, depth) for descriptor in descriptors: visits += 1 if visits > 64: @@ -334,6 +338,9 @@ def image_plans(stream, index, budget): if "artifactType" in manifest: raise InventoryError("unsupported_oci_artifact") if media in index_media: + # Reject malformed children inside this descriptor's + # failure boundary, before deferring their traversal. + index_descriptors(manifest, depth + 1) pending.append((manifest, depth + 1)) continue if not isinstance(manifest, dict) or type(manifest.get("schemaVersion")) is not int or manifest["schemaVersion"] != 2 or not isinstance(manifest.get("layers"), list): @@ -368,17 +375,21 @@ def image_plans(stream, index, budget): if not isinstance(manifests, list) or not manifests or len(manifests) > MAX_IMAGES: raise InventoryError("invalid_docker_manifest_list") for manifest in manifests: - if not isinstance(manifest, dict) or not isinstance(manifest.get("Layers"), list) or len(manifest["Layers"]) > MAX_LAYERS: - raise InventoryError("invalid_docker_image_manifest") - config = safe_path(manifest.get("Config")) - digest = "sha256:" + hashlib.sha256(read_member(stream, index, config, budget)).hexdigest() - layers = [] - for layer in manifest["Layers"]: - name = safe_path(layer) - if name not in index or index[name][2] != "file": - raise InventoryError("missing_docker_layer") - layers.append((name, False, None)) - plans.append((digest, layers, "docker_config", None)) + digest = "unknown" + try: + if not isinstance(manifest, dict) or not isinstance(manifest.get("Layers"), list) or len(manifest["Layers"]) > MAX_LAYERS: + raise InventoryError("invalid_docker_image_manifest") + config = safe_path(manifest.get("Config")) + digest = "sha256:" + hashlib.sha256(read_member(stream, index, config, budget)).hexdigest() + layers = [] + for layer in manifest["Layers"]: + name = safe_path(layer) + if name not in index or index[name][2] != "file": + raise InventoryError("missing_docker_layer") + layers.append((name, False, None)) + plans.append((digest, layers, "docker_config", None)) + except InventoryError as exc: + plans.append((digest, [], "docker_config", str(exc))) else: raise InventoryError("unsupported_archive_layout") if not plans: diff --git a/test_sibling_planning.py b/test_sibling_planning.py new file mode 100644 index 0000000..e27df9d --- /dev/null +++ b/test_sibling_planning.py @@ -0,0 +1,127 @@ +"""Synthetic independent planning failures must not erase healthy siblings.""" +import hashlib +import io +import json +import tarfile +import unittest +from unittest import mock + +import oci_runtime_inventory as c +import test_inventory as t + + +def unpack(raw): + with tarfile.open(fileobj=io.BytesIO(raw)) as archive: + return {m.name: archive.extractfile(m).read() for m in archive if m.isfile()} + + +def blob(files, value): + raw = json.dumps(value).encode() + digest = "sha256:" + hashlib.sha256(raw).hexdigest() + files["blobs/sha256/" + digest[7:]] = raw + return dict(digest=digest, size=len(raw), mediaType="application/vnd.oci.image.index.v1+json") + + +class SiblingPlanningTests(unittest.TestCase): + cli = t.InventoryTests.cli + scan = t.InventoryTests.scan + + def assert_siblings(self, files, identity, reason, kind): + code, report, _ = self.scan(t.tar_bytes(list(files.items()))) + self.assertEqual(2, code) + self.assertFalse(report["complete"]) + self.assertEqual(2, len(report["images"])) + healthy = next(image for image in report["images"] if image["coverage_complete"]) + failed = next(image for image in report["images"] if not image["coverage_complete"]) + self.assertEqual(identity, healthy["digest"]) + self.assertEqual(kind, healthy["identity_kind"]) + self.assertEqual("sharp", healthy["components"][0]["name"]) + self.assertEqual("0.35.5", healthy["components"][0]["version"]) + self.assertEqual(healthy["layers"][0], healthy["components"][0]["layer_digest"]) + self.assertEqual("not_tested", healthy["components"][0]["exploitability"]) + self.assertEqual([], failed["components"]) + self.assertEqual([], failed["layers"]) + self.assertIn(reason, failed["notes"]) + code, consumer, _ = self.scan(t.tar_bytes(list(files.items())), "--consumer", "sharp") + self.assertEqual(2, code) + self.assertEqual([["0.35.5"]], [row["sharp_versions"] for row in consumer["records"]]) + return failed + + def test_nested_index_structural_failures_preserve_siblings_in_both_orders(self): + original = unpack(t.oci_archive([t.tar_bytes([("app/package.json", t.package())])])) + for malformed, reason in ((dict(schemaVersion=3, manifests=[]), "unsupported_index_schema_version"), + (dict(schemaVersion=True, manifests=[]), "unsupported_index_schema_version"), + (dict(schemaVersion=2, manifests="PRIVATE-CONTENT"), "invalid_or_excessive_image_index"), + (dict(schemaVersion=2, manifests=[{}] * 17), "invalid_or_excessive_image_index")): + for reverse in (False, True): + with self.subTest(malformed=malformed, reverse=reverse): + files = dict(original) + index = json.loads(files["index.json"]) + valid = index["manifests"][0] + rejected = blob(files, malformed) + index["manifests"] = [rejected, valid] if reverse else [valid, rejected] + files["index.json"] = json.dumps(index).encode() + failed = self.assert_siblings(files, valid["digest"], reason, "oci_manifest") + self.assertEqual(rejected["digest"], failed["digest"]) + self.assertNotIn("PRIVATE-CONTENT", json.dumps(failed)) + + def test_docker_planning_failures_preserve_siblings_in_both_orders(self): + original = unpack(t.docker_archive([t.tar_bytes([("app/package.json", t.package())])])) + identity = "sha256:" + hashlib.sha256(original["config.json"]).hexdigest() + for malformed, reason, known_identity in ((dict(Config="config.json", Layers=["missing.tar"]), "missing_docker_layer", True), + (dict(Config="missing.json", Layers=[]), "missing_or_excessive_manifest", False), + (dict(Config="config.json", Layers="PRIVATE-CONTENT"), "invalid_docker_image_manifest", False), + (None, "invalid_docker_image_manifest", False), + (dict(Config="config.json", Layers=["../outside"]), "unsafe_archive_path", True)): + for reverse in (False, True): + with self.subTest(malformed=malformed, reverse=reverse): + files = dict(original) + valid = json.loads(files["manifest.json"])[0] + files["manifest.json"] = json.dumps([malformed, valid] if reverse else [valid, malformed]).encode() + failed = self.assert_siblings(files, identity, reason, "docker_config") + self.assertEqual(identity if known_identity else "unknown", failed["digest"]) + self.assertNotIn("PRIVATE-CONTENT", json.dumps(failed)) + + def test_valid_nested_index_is_still_traversed(self): + files = unpack(t.oci_archive([t.tar_bytes([("app/package.json", t.package())])])) + index = json.loads(files["index.json"]) + valid = index["manifests"][0] + index["manifests"] = [blob(files, dict(schemaVersion=2, manifests=[valid]))] + files["index.json"] = json.dumps(index).encode() + code, report, _ = self.scan(t.tar_bytes(list(files.items()))) + self.assertEqual(0, code) + self.assertEqual(valid["digest"], report["images"][0]["digest"]) + + def test_nested_depth_limit_remains_local_and_bounded(self): + files = unpack(t.oci_archive([t.tar_bytes([("app/package.json", t.package())])])) + root = json.loads(files["index.json"]) + valid = root["manifests"][0] + nested = valid + for _ in range(4): + nested = blob(files, dict(schemaVersion=2, manifests=[nested])) + root["manifests"] = [valid, nested] + files["index.json"] = json.dumps(root).encode() + self.assert_siblings(files, valid["digest"], "invalid_or_excessive_image_index", "oci_manifest") + + def test_global_root_corruption_and_shared_capture_budget_remain_conservative(self): + files = unpack(t.oci_archive([t.tar_bytes([("app/package.json", t.package())])])) + files["index.json"] = json.dumps(dict(schemaVersion=3, manifests=[])).encode() + code, report, _ = self.scan(t.tar_bytes(list(files.items()))) + self.assertEqual(2, code) + self.assertEqual([], report["images"]) + files = unpack(t.docker_archive([t.tar_bytes([("app/package.json", t.package())])])) + entry = json.loads(files["manifest.json"])[0] + files["manifest.json"] = json.dumps([entry, entry]).encode() + # Planning both configs exceeds this one shared budget; the failure + # must not reset it and fabricate a complete second image. + cap = len(files["manifest.json"]) + len(files["config.json"]) + with mock.patch.object(c, "MAX_CAPTURE", cap): + code, report, _ = self.scan(t.tar_bytes(list(files.items()))) + self.assertEqual(2, code) + self.assertTrue(all(not image["coverage_complete"] for image in report["images"])) + self.assertEqual(cap, report["usage"]["capture"]) + self.assertTrue(all("capture_limit" in image["notes"] for image in report["images"])) + + +if __name__ == "__main__": + unittest.main()