Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion SHA256SUMS
Original file line number Diff line number Diff line change
@@ -1 +1 @@
21d6cbd46b86c101b346d507ed0de30af6f6655fc8b4825ce7b6c2b0ec44c4fe oci_runtime_inventory.py
e4bec83a0e16bdfb7935040844535a82164d113b16c3d9aea17c3284242cadd4 oci_runtime_inventory.py
43 changes: 27 additions & 16 deletions oci_runtime_inventory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"}:
Expand All @@ -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:
Expand All @@ -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):
Expand Down Expand Up @@ -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:
Expand Down
127 changes: 127 additions & 0 deletions test_sibling_planning.py
Original file line number Diff line number Diff line change
@@ -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()
Loading