Files
crank/scripts/check-image-scan.py
bsodfather f685616ae8
CI / Rust Checks (pull_request) Successful in 23m1s
CI / UI Checks (pull_request) Successful in 6s
CI / Community Image Smoke (pull_request) Successful in 7m28s
CI / Frontend E2E (pull_request) Successful in 9m33s
CI / Deploy (pull_request) Skipped
fix(security): minimize runtime images and enforce complete vulnerability scans
2026-10-10 01:41:38 +03:00

791 lines
31 KiB
Python
Executable File

#!/usr/bin/env python3
"""Strict evidence gate over a raw Trivy image scan and the real image.
The scanner wrapper (``scripts/scan-images.sh``) produces one raw Trivy JSON
report per image and a copy of the Trivy DB metadata. This gate never rewrites
those raw artifacts; it reads them, validates their schema and provenance, then
cross-checks the findings against the immutable Docker image itself.
Exit codes:
0 PASS - evidence is consistent and no unresolved High/Critical remains.
1 BLOCKED- at least one High/Critical finding is not narrowly excepted.
2 ERROR - the evidence (report, DB metadata, manifest or image export) is
missing, malformed, stale or inconsistent.
The raw report is never modified. The evaluation result is written separately to
the ``--decision`` path. The only allowed High/Critical exception is the
CVE-2025-69720 false positive on the Debian 12 ``libtinfo6:6.4-4`` shared
library when the ``infocmp`` front-end tool (``ncurses-bin``) is genuinely
absent from the image; that absence is proven from the exported image, not from
the scan report.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import posixpath
import re
import subprocess
import sys
import tarfile
import tempfile
import threading
from datetime import datetime, timedelta, timezone
from pathlib import Path
# Packages that make up the Debian 12 server runtime rootfs. They must appear in
# both the dpkg status database and the Trivy OS package inventory.
EXPECTED_PACKAGES = (
"base-files",
"libc6",
"libgcc-s1",
"gcc-12-base",
"bash",
"dash",
"libtinfo6",
"libselinux1",
"libpcre2-8-0",
"coreutils",
)
# Fixed, non-overridable runtime inventory location (see prepare-runtime-rootfs).
RUNTIME_MANIFEST_PATH = "/usr/share/crank/runtime-inventory.tsv"
DPKG_STATUS_PATH = "/var/lib/dpkg/status"
SYNTHETIC_PACKAGE = "runtime-generated"
CAPTURED_PATHS = frozenset({RUNTIME_MANIFEST_PATH, DPKG_STATUS_PATH})
POST_PACKAGE_FILES = frozenset({
RUNTIME_MANIFEST_PATH, DPKG_STATUS_PATH,
"/etc/ssl/certs/ca-certificates.crt",
"/usr/local/bin/admin-api", "/usr/local/bin/crank-migrate",
"/usr/local/bin/mcp-server", "/usr/local/bin/crank-admin-entrypoint",
"/usr/local/bin/crank-http-healthcheck",
# Docker adds these container files; they are not Debian package contents.
"/.dockerenv", "/dev/console", "/etc/hostname", "/etc/hosts",
"/etc/mtab", "/etc/resolv.conf",
})
RUNTIME_OS_FAMILY = "debian"
RUNTIME_OS_NAME_PREFIX = "12"
ALLOWED_SEVERITIES = frozenset({"UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL"})
BLOCKING_SEVERITIES = frozenset({"HIGH", "CRITICAL"})
EXPECTED_CVE = "CVE-2025-69720"
EXCEPTED_PACKAGE = "libtinfo6"
EXCEPTED_VERSION = "6.4-4"
EXCEPTION_JUSTIFICATION = (
"CVE-2025-69720 describes the infocmp ncurses front-end. The runtime image "
"ships only the libtinfo6:6.4-4 shared library from Debian 12 and does not "
"contain /usr/bin/infocmp or the ncurses-bin package, so the vulnerable "
"code path is unreachable. Proven against the exported immutable image, not "
"the scan report."
)
ALLOWED_MANIFEST_PACKAGES = frozenset(EXPECTED_PACKAGES) | {SYNTHETIC_PACKAGE}
DB_MAX_AGE = timedelta(hours=24)
DB_MAX_FUTURE = timedelta(minutes=5)
MAX_REPORT_BYTES = 256 * 1024 * 1024
MAX_DB_METADATA_BYTES = 1024 * 1024
MAX_SPECIAL_FILE_BYTES = 4 * 1024 * 1024
MAX_EXPORT_ENTRIES = 200_000
MAX_EXPORT_BYTES = 512 * 1024 * 1024
DOCKER_TIMEOUT_SECONDS = 600
READ_CHUNK_BYTES = 64 * 1024
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
CONTAINER_ID_RE = re.compile(r"^[0-9a-f]{12,64}$")
TIMESTAMP_RE = re.compile(
r"^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})"
r"(?:\.(\d+))?(Z|z|[+-]\d{2}:?\d{2})?$"
)
class EvidenceError(Exception):
"""Raised when scan evidence is missing, malformed or inconsistent."""
def parse_args(argv) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Fail closed on unresolved High/Critical image findings."
)
parser.add_argument("--report", required=True, help="raw Trivy JSON report")
parser.add_argument("--image-id", required=True, help="immutable image ID")
parser.add_argument("--db-metadata", required=True, help="Trivy DB metadata")
parser.add_argument("--decision", required=True, help="decision output JSON")
return parser.parse_args(argv)
def unique_json_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise EvidenceError(f"duplicate JSON key: {key}")
result[key] = value
return result
def load_json(path: Path, max_bytes: int, label: str) -> dict:
try:
if not path.is_file():
raise EvidenceError(f"{label} is not a regular file")
with path.open("rb") as stream:
raw = stream.read(max_bytes + 1)
except OSError as error:
raise EvidenceError(f"{label} cannot be read: {error}") from error
if len(raw) > max_bytes:
raise EvidenceError(f"{label} exceeds the size budget")
if not raw.strip():
raise EvidenceError(f"{label} is empty")
try:
payload = json.loads(raw, object_pairs_hook=unique_json_object)
except (json.JSONDecodeError, UnicodeDecodeError) as error:
raise EvidenceError(f"{label} is not valid JSON: {error}") from error
if not isinstance(payload, dict):
raise EvidenceError(f"{label} must be a JSON object")
return payload
def parse_timestamp(value, label: str) -> datetime:
if not isinstance(value, str):
raise EvidenceError(f"{label} must be a string timestamp")
match = TIMESTAMP_RE.match(value.strip())
if not match or not match.group(8):
raise EvidenceError(f"{label} is not an RFC3339 timestamp: {value!r}")
text = value.strip()
if text.endswith(("Z", "z")):
text = text[:-1] + "+00:00"
try:
return datetime.fromisoformat(text)
except ValueError as error:
raise EvidenceError(f"{label} is not a valid timestamp: {value!r}") from error
def load_db_metadata(path: Path, now: datetime) -> dict:
payload = load_json(path, MAX_DB_METADATA_BYTES, "Trivy DB metadata")
if type(payload.get("Version")) is not int or payload["Version"] != 2:
raise EvidenceError("unsupported or missing Trivy DB schema version")
updated_at = parse_timestamp(payload.get("UpdatedAt"), "Trivy DB UpdatedAt")
age = now - updated_at
if age > DB_MAX_AGE:
raise EvidenceError(
f"Trivy DB is stale: updated {int(age.total_seconds())}s ago "
f"(limit {int(DB_MAX_AGE.total_seconds())}s)"
)
if updated_at - now > DB_MAX_FUTURE:
raise EvidenceError("Trivy DB UpdatedAt is too far in the future")
return {
"path": str(path),
"updated_at": updated_at.isoformat(),
"age_seconds": max(0, int(age.total_seconds())),
"max_age_seconds": int(DB_MAX_AGE.total_seconds()),
}
def validate_vulnerability(vuln, result_index: int, vuln_index: int) -> None:
prefix = f"report result {result_index} vulnerability {vuln_index}"
if not isinstance(vuln, dict):
raise EvidenceError(f"{prefix} is not a JSON object")
for field in ("VulnerabilityID", "PkgName", "InstalledVersion", "Severity"):
value = vuln.get(field)
if not isinstance(value, str) or not value.strip():
raise EvidenceError(f"{prefix} is missing a non-empty {field}")
severity = vuln["Severity"].strip().upper()
if severity not in ALLOWED_SEVERITIES:
raise EvidenceError(f"{prefix} has an unknown severity {vuln['Severity']!r}")
fixed = vuln.get("FixedVersion")
if fixed is not None and not isinstance(fixed, str):
raise EvidenceError(f"{prefix} has an invalid FixedVersion")
status = vuln.get("Status")
if status is not None and not isinstance(status, str):
raise EvidenceError(f"{prefix} has an invalid Status")
def validate_report(report: dict, expected_image_id: str):
if type(report.get("SchemaVersion")) is not int or report["SchemaVersion"] != 2:
raise EvidenceError("unsupported or missing Trivy SchemaVersion")
if not IMAGE_ID_RE.fullmatch(expected_image_id):
raise EvidenceError("--image-id must be an immutable sha256 image id")
if report.get("ArtifactType") != "container_image":
raise EvidenceError("scan report ArtifactType is not container_image")
metadata = report.get("Metadata")
if not isinstance(metadata, dict):
raise EvidenceError("scan report Metadata is missing")
if metadata.get("ImageID") != expected_image_id:
raise EvidenceError(
f"scan report image id {metadata.get('ImageID')!r} does not match "
f"the expected {expected_image_id!r}"
)
os_meta = metadata.get("OS")
if not isinstance(os_meta, dict):
raise EvidenceError("scan report Metadata.OS is missing")
family = os_meta.get("Family")
if not isinstance(family, str) or not family.strip():
raise EvidenceError("scan report OS family is missing")
name = os_meta.get("Name")
if not isinstance(name, str) or not name.strip():
raise EvidenceError("scan report is missing the OS version name")
results = report.get("Results")
if not isinstance(results, list) or not results:
raise EvidenceError("scan report Results is missing or empty")
trivy_packages: dict[str, str] = {}
os_packages_result = None
for index, result in enumerate(results):
if not isinstance(result, dict):
raise EvidenceError(f"report result {index} is not a JSON object")
packages = result.get("Packages")
if not isinstance(packages, list):
raise EvidenceError(f"report result {index} is missing the Packages list")
for package in packages:
if not isinstance(package, dict):
raise EvidenceError(f"report result {index} has a malformed package")
for field in ("Name", "Version"):
if not isinstance(package.get(field), str) or not package[field].strip():
raise EvidenceError(f"report result {index} package lacks {field}")
vulnerabilities = result.get("Vulnerabilities")
if vulnerabilities is None:
if not packages:
raise EvidenceError(
f"report result {index} has neither packages nor vulnerabilities"
)
elif not isinstance(vulnerabilities, list):
raise EvidenceError(
f"report result {index} has an invalid Vulnerabilities list"
)
else:
for vuln_index, vuln in enumerate(vulnerabilities):
validate_vulnerability(vuln, index, vuln_index)
if str(result.get("Class", "")).strip().lower() == "os-pkgs" and packages:
if result.get("Type") != family.strip().lower():
raise EvidenceError("OS package result does not match the reported OS")
os_packages_result = result
for package in packages:
package_name = package["Name"]
release = package.get("Release", "")
epoch = package.get("Epoch", 0)
if not isinstance(release, str) or type(epoch) is not int or epoch < 0:
raise EvidenceError(f"invalid package version fields for {package_name}")
version = package["Version"]
if release:
version += "-" + release
if epoch:
version = str(epoch) + ":" + version
if package_name in trivy_packages:
raise EvidenceError(f"duplicate OS package: {package_name}")
trivy_packages[package_name] = version
if os_packages_result is None:
raise EvidenceError("scan report has no non-empty OS package inventory")
os_info = {
"family": family.strip().lower(),
"name": name.strip() if isinstance(name, str) else "",
}
return os_info, results, trivy_packages
def is_runtime_os(os_info: dict) -> bool:
return (
os_info.get("family") == RUNTIME_OS_FAMILY
and re.fullmatch(r"12(?:\.\d+)*", str(os_info.get("name", ""))) is not None
)
def normalize_tar_path(name: str):
text = str(name).replace("\\", "/").lstrip("/")
while text.startswith("./"):
text = text[2:]
# Go's tar writer (used by `docker export`) marks directories with a
# trailing slash; strip it before splitting so directory entries normalize.
text = text.rstrip("/")
if text in ("", "."):
return None
parts = text.split("/")
if any(part in ("", ".", "..") for part in parts):
raise EvidenceError(f"docker export contains an unsafe path: {name!r}")
return "/" + "/".join(parts)
def validate_manifest_path(path: str, line_number: int) -> None:
if not path.startswith("/"):
raise EvidenceError(
f"manifest line {line_number} path must be absolute: {path!r}"
)
if "\\" in path or "\x00" in path:
raise EvidenceError(f"manifest line {line_number} path is invalid: {path!r}")
if path == "/" or posixpath.normpath(path) != path:
raise EvidenceError(
f"manifest line {line_number} path is not normalized: {path!r}"
)
for segment in path.split("/")[1:]:
if segment in ("", ".", ".."):
raise EvidenceError(
f"manifest line {line_number} path is not normalized: {path!r}"
)
def parse_manifest(text: str):
entries = []
seen: set[str] = set()
for line_number, raw in enumerate(text.splitlines(), 1):
if raw == "":
continue
fields = raw.split("\t")
if len(fields) != 3:
raise EvidenceError(
f"manifest line {line_number} must have three tab-separated fields"
)
package, path, digest = fields
if not package:
raise EvidenceError(f"manifest line {line_number} has an empty package label")
if package not in ALLOWED_MANIFEST_PACKAGES:
raise EvidenceError(
f"manifest line {line_number} has an unexpected package label "
f"{package!r}"
)
validate_manifest_path(path, line_number)
if path in seen:
raise EvidenceError(f"manifest lists the path more than once: {path}")
seen.add(path)
if not digest:
raise EvidenceError(f"manifest line {line_number} has an empty digest")
entries.append((package, path, digest, SHA256_RE.fullmatch(digest) is not None))
if not entries:
raise EvidenceError("runtime manifest is empty")
if RUNTIME_MANIFEST_PATH in seen:
raise EvidenceError("runtime manifest must not list its own path")
if DPKG_STATUS_PATH in seen:
raise EvidenceError("runtime manifest must not list the dpkg status file")
return entries
def parse_dpkg_status(text: str) -> dict:
packages: dict[str, str] = {}
for block in text.split("\n\n"):
fields: dict[str, str] = {}
for line in block.splitlines():
if not line or line[0] in " \t":
continue
key, separator, value = line.partition(":")
if not separator:
continue
fields[key.strip()] = value.strip()
name = fields.get("Package")
if name:
if name in packages:
raise EvidenceError(f"dpkg status lists {name} more than once")
if fields.get("Status") != "install ok installed" or not fields.get("Version"):
raise EvidenceError(f"dpkg status has invalid installed metadata for {name}")
packages[name] = fields["Version"]
return packages
def _docker_create(image_id: str) -> str:
try:
result = subprocess.run(
["docker", "create", "--entrypoint", "/bin/sh", image_id],
capture_output=True,
text=True,
timeout=DOCKER_TIMEOUT_SECONDS,
)
except (OSError, subprocess.SubprocessError) as error:
raise EvidenceError(f"docker create could not run: {error}") from error
if result.returncode != 0:
detail = result.stderr.strip() or f"exit {result.returncode}"
raise EvidenceError(f"docker create failed for {image_id}: {detail}")
container_id = result.stdout.strip()
if not CONTAINER_ID_RE.fullmatch(container_id):
raise EvidenceError("docker create returned an unexpected container id")
return container_id
def _docker_remove(container_id: str) -> None:
try:
result = subprocess.run(
["docker", "rm", container_id],
capture_output=True,
text=True,
timeout=DOCKER_TIMEOUT_SECONDS,
)
except (OSError, subprocess.SubprocessError) as error:
raise EvidenceError(f"owned export container cleanup failed: {error}") from error
if result.returncode != 0:
raise EvidenceError("owned export container cleanup failed: " + result.stderr.strip())
def _consume_member(member, archive, entries, contents, basenames, counters) -> None:
path = normalize_tar_path(member.name)
if path is None:
return
counters["entries"] += 1
if counters["entries"] > MAX_EXPORT_ENTRIES:
raise EvidenceError("docker export exceeds the entry budget")
basenames.add(posixpath.basename(path))
if path in entries:
raise EvidenceError(f"docker export contains a duplicate path: {path}")
if member.isdir():
entries[path] = ("dir", None)
return
if member.issym():
entries[path] = ("symlink", member.linkname)
return
if member.islnk():
target = normalize_tar_path(member.linkname)
linked = entries.get(target) if target else None
if linked is not None and linked[0] == "file":
entries[path] = ("file", linked[1])
else:
entries[path] = ("hardlink", member.linkname)
return
if not member.isfile():
entries[path] = ("other", None)
return
counters["bytes"] += member.size
if counters["bytes"] > MAX_EXPORT_BYTES:
raise EvidenceError("docker export exceeds the size budget")
hasher = hashlib.sha256()
capture = bytearray() if path in CAPTURED_PATHS else None
stream = archive.extractfile(member)
if stream is None:
raise EvidenceError(f"docker export could not read {path}")
remaining = member.size
with stream:
while remaining > 0:
chunk = stream.read(min(READ_CHUNK_BYTES, remaining))
if not chunk:
raise EvidenceError(f"docker export truncated while reading {path}")
hasher.update(chunk)
remaining -= len(chunk)
if capture is not None:
capture.extend(chunk)
if len(capture) > MAX_SPECIAL_FILE_BYTES:
raise EvidenceError(f"captured file exceeds budget: {path}")
entries[path] = ("file", hasher.hexdigest())
if capture is not None:
contents[path] = bytes(capture)
def _docker_export(container_id: str):
# A file avoids stderr pipe backpressure while the tar stream is consumed.
with tempfile.TemporaryFile() as stderr_file:
try:
process = subprocess.Popen(
["docker", "export", container_id],
stdout=subprocess.PIPE,
stderr=stderr_file,
)
except OSError as error:
raise EvidenceError(f"docker export could not run: {error}") from error
timed_out = threading.Event()
def expire():
if process.poll() is None:
timed_out.set()
try:
process.kill()
except ProcessLookupError:
pass
deadline = threading.Timer(DOCKER_TIMEOUT_SECONDS, expire)
deadline.daemon = True
deadline.start()
entries: dict[str, tuple] = {}
contents: dict[str, bytes] = {}
basenames: set[str] = set()
counters = {"entries": 0, "bytes": 0}
failure = None
try:
if process.stdout is None:
raise EvidenceError("docker export has no output stream")
try:
with tarfile.open(fileobj=process.stdout, mode="r|") as archive:
for member in archive:
_consume_member(member, archive, entries, contents, basenames, counters)
except tarfile.TarError as error:
raise EvidenceError(f"docker export produced an unreadable archive: {error}") from error
except EvidenceError as error:
failure = error
finally:
if process.stdout is not None:
process.stdout.close()
if failure is not None and process.poll() is None:
process.kill()
return_code = process.wait()
deadline.cancel()
deadline.join()
if timed_out.is_set():
raise EvidenceError("docker export timed out")
if failure is not None:
raise failure
if return_code != 0:
stderr_file.seek(0)
detail = stderr_file.read(READ_CHUNK_BYTES).decode("utf-8", "replace").strip()
raise EvidenceError(f"docker export failed for {container_id}: {detail or f'exit {return_code}'}")
return entries, contents, basenames
def read_image(image_id: str):
container_id = _docker_create(image_id)
try:
return _docker_export(container_id)
finally:
_docker_remove(container_id)
def verify_runtime(entries, contents, trivy_packages):
manifest_bytes = contents.get(RUNTIME_MANIFEST_PATH)
if manifest_bytes is None:
raise EvidenceError(f"runtime manifest {RUNTIME_MANIFEST_PATH} is missing")
status_bytes = contents.get(DPKG_STATUS_PATH)
if status_bytes is None:
raise EvidenceError(f"package status {DPKG_STATUS_PATH} is missing")
try:
manifest = parse_manifest(manifest_bytes.decode("utf-8"))
dpkg_packages = parse_dpkg_status(status_bytes.decode("utf-8"))
except UnicodeDecodeError as error:
raise EvidenceError("runtime inventory is not valid UTF-8") from error
unexpected_dpkg = set(dpkg_packages) - set(EXPECTED_PACKAGES)
unexpected_trivy = set(trivy_packages) - set(EXPECTED_PACKAGES)
if unexpected_dpkg or unexpected_trivy:
raise EvidenceError("unexpected runtime packages: " + ", ".join(sorted(unexpected_dpkg | unexpected_trivy)))
for package in EXPECTED_PACKAGES:
if package not in dpkg_packages:
raise EvidenceError(f"dpkg status is missing package {package}")
missing_trivy = [name for name in EXPECTED_PACKAGES if name not in trivy_packages]
if missing_trivy:
raise EvidenceError(
"Trivy OS package inventory is missing: " + ", ".join(missing_trivy)
)
for package in EXPECTED_PACKAGES:
if dpkg_packages[package] != trivy_packages[package]:
raise EvidenceError(f"Trivy/dpkg version mismatch for {package}")
for package, path, digest, is_hash in manifest:
actual = entries.get(path)
if actual is None:
raise EvidenceError(f"manifest file is missing from the image: {path}")
kind, value = actual
if is_hash:
if kind != "file" or value != digest:
raise EvidenceError(f"manifest hash mismatch for {path}")
elif kind != "symlink" or value != digest:
raise EvidenceError(f"manifest symlink mismatch for {path}")
declared = {path for _, path, _, _ in manifest}
undeclared = sorted(path for path, (kind, _) in entries.items()
if kind != "dir" and path not in declared and path not in POST_PACKAGE_FILES)
if undeclared:
raise EvidenceError("undeclared runtime files: " + ", ".join(undeclared[:10]))
return {
"manifest_entries": len(manifest),
"manifest_packages": sorted({entry[0] for entry in manifest}),
"dpkg_packages": len(dpkg_packages),
"trivy_packages": len(trivy_packages),
"manifest_verified": True,
}, dpkg_packages
def _is_excepted(vuln, os_info, infocmp_present, ncurses_bin_present, actual_version) -> bool:
if vuln["VulnerabilityID"] != EXPECTED_CVE:
return False
if vuln["PkgName"] != EXCEPTED_PACKAGE:
return False
if vuln["InstalledVersion"] != EXCEPTED_VERSION:
return False
if actual_version != EXCEPTED_VERSION:
return False
if not is_runtime_os(os_info):
return False
if infocmp_present is not False:
return False
if ncurses_bin_present is not False:
return False
return True
def evaluate_findings(results, os_info, basenames, dpkg_packages, image_id):
counts = {severity: 0 for severity in ALLOWED_SEVERITIES}
high_critical = []
blocking = []
exceptions = []
infocmp_present = "infocmp" in basenames if basenames is not None else None
ncurses_bin_present = (
"ncurses-bin" in dpkg_packages if dpkg_packages is not None else None
)
for result in results:
target = result.get("Target", "")
for vuln in result.get("Vulnerabilities", []) or []:
severity = vuln["Severity"].strip().upper()
counts[severity] += 1
if severity not in BLOCKING_SEVERITIES:
continue
record = {
"vulnerability_id": vuln["VulnerabilityID"],
"package": vuln["PkgName"],
"installed_version": vuln["InstalledVersion"],
"fixed_version": vuln.get("FixedVersion") or None,
"severity": severity,
"status": vuln.get("Status") or None,
"target": target,
}
actual_version = dpkg_packages.get(EXCEPTED_PACKAGE) if dpkg_packages else None
if _is_excepted(vuln, os_info, infocmp_present, ncurses_bin_present, actual_version):
record["disposition"] = "excepted"
high_critical.append(record)
exceptions.append(
{
"vulnerability_id": vuln["VulnerabilityID"],
"package": vuln["PkgName"],
"installed_version": vuln["InstalledVersion"],
"severity": severity,
"image_id": image_id,
"justification": EXCEPTION_JUSTIFICATION,
}
)
else:
record["disposition"] = "blocked"
high_critical.append(record)
blocking.append(record)
return {
"severity_counts": {severity: counts[severity] for severity in sorted(counts)},
"high_critical": high_critical,
"blocking": blocking,
"exceptions": exceptions,
}
def _sha256_file(path: Path) -> str:
hasher = hashlib.sha256()
with path.open("rb") as stream:
while True:
chunk = stream.read(READ_CHUNK_BYTES)
if not chunk:
break
hasher.update(chunk)
return hasher.hexdigest()
def _assert_distinct(decision_path: Path, report_path: Path, db_path: Path) -> None:
protected = {report_path.resolve(), db_path.resolve()}
if decision_path.resolve() in protected:
raise EvidenceError(
"--decision must not overwrite the raw report or DB metadata"
)
def compute(decision: dict, args: argparse.Namespace) -> None:
report_path = Path(args.report)
db_path = Path(args.db_metadata)
decision_path = Path(args.decision)
_assert_distinct(decision_path, report_path, db_path)
now = datetime.now(timezone.utc)
decision["db_metadata"] = load_db_metadata(db_path, now)
report = load_json(report_path, MAX_REPORT_BYTES, "scan report")
decision["report_sha256"] = _sha256_file(report_path)
os_info, results, trivy_packages = validate_report(report, args.image_id)
decision["os"] = os_info
decision["artifact_type"] = "container_image"
basenames = None
dpkg_packages = None
if is_runtime_os(os_info):
entries, contents, basenames = read_image(args.image_id)
runtime_summary, dpkg_packages = verify_runtime(
entries, contents, trivy_packages
)
runtime_summary["image_files"] = len(entries)
decision["runtime_inventory"] = runtime_summary
decision.update(
evaluate_findings(results, os_info, basenames, dpkg_packages, args.image_id)
)
def write_decision(path: Path, decision: dict) -> None:
payload = json.dumps(decision, indent=2, sort_keys=True) + "\n"
directory = str(path.parent) if str(path.parent) else "."
descriptor, temporary = tempfile.mkstemp(prefix=".decision-", dir=directory)
try:
with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
stream.write(payload)
os.replace(temporary, path)
except OSError:
try:
os.unlink(temporary)
except OSError:
pass
raise
def base_decision(args: argparse.Namespace) -> dict:
return {
"schema": "crank.image-scan.decision.v1",
"image_id": args.image_id,
"report_path": str(args.report),
"db_metadata_path": str(args.db_metadata),
"status": "error",
"exit_code": 2,
"errors": [],
}
def main(argv=None) -> int:
args = parse_args(sys.argv[1:] if argv is None else argv)
# An unsafe output path must be rejected before any error receipt is written.
try:
_assert_distinct(Path(args.decision), Path(args.report), Path(args.db_metadata))
except EvidenceError as error:
print(f"image scan gate: evidence failure: {error}", file=sys.stderr)
return 2
decision = base_decision(args)
try:
compute(decision, args)
except EvidenceError as error:
decision["status"] = "error"
decision["exit_code"] = 2
decision["errors"].append(str(error))
try:
write_decision(Path(args.decision), decision)
except OSError as write_error:
print(
f"image scan gate: cannot write decision: {write_error}",
file=sys.stderr,
)
return 2
print(f"image scan gate: evidence failure: {error}", file=sys.stderr)
return 2
blocking = decision.get("blocking", [])
if blocking:
decision["status"] = "blocked"
decision["exit_code"] = 1
else:
decision["status"] = "pass"
decision["exit_code"] = 0
try:
write_decision(Path(args.decision), decision)
except OSError as error:
print(f"image scan gate: cannot write decision: {error}", file=sys.stderr)
return 2
print(
"image scan gate: {status} ({blocked} blocking, {excepted} excepted)".format(
status=decision["status"],
blocked=len(blocking),
excepted=len(decision.get("exceptions", [])),
)
)
return decision["exit_code"]
if __name__ == "__main__":
raise SystemExit(main())