fix(security): minimize runtime images and enforce complete vulnerability scans
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

This commit is contained in:
bsodfather committed 2026-10-10 01:41:38 +03:00
1 parent 0c1fb38e31
commit f685616ae8
13 files changed
+2736 -37

No files matched your search

+790
View File
@@ -0,0 +1,790 @@
#!/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())
+169
View File
@@ -0,0 +1,169 @@
#!/bin/sh
# Assemble the minimal Debian runtime rootfs used by the Crank server images.
#
# The final admin-api and mcp-server images are built `FROM scratch`; this
# script runs inside the Debian package stage before the rootfs is copied into
# the scratch image. It transfers only the files owned by an explicit package
# allowlist plus three GNU coreutils programs and their copyright. No apt,
# libacl, GNU gzip, infocmp, util-linux or BusyBox files are copied.
#
# Merged-/usr: Debian exposes /bin, /sbin and /lib as symlinks into /usr. The
# package file lists still name the legacy paths (for example /bin/bash or
# /lib/x86_64-linux-gnu/libc.so.6). Before every copy the parent directory is
# resolved through those symlinks (readlink -f on the dirname only), so regular
# files and library symlinks land in their real /usr locations while the
# top-level directory symlinks (/bin -> usr/bin, /lib -> usr/lib,
# /lib64 -> usr/lib64) and file symlinks (for example /usr/bin/sh -> dash) are
# preserved unchanged.
#
# Inventory: /usr/share/crank/runtime-inventory.tsv is a tab-separated manifest
# with one row per file placed in the rootfs by this script:
#
# package<TAB>normalized absolute path<TAB>sha256 for regular files or the
# symlink target for symlinks
#
# Files generated here instead of shipped by a package use the synthetic
# package label `runtime-generated`. The scan stage cross-checks this manifest
# against the real image instead of trusting Trivy alone. The manifest path is
# fixed and cannot be overridden.
set -eu
dest="${1:-/runtime}"
case "$dest" in
/*) ;;
*)
echo "runtime rootfs destination must be an absolute path: $dest" >&2
exit 64
;;
esac
# Packages kept in the runtime image. Versions are recorded in dpkg/status.
# gcc-12-base supplies the copyright target of libgcc-s1; retaining its
# package-owned documentation preserves the license and its source version.
packages="base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils"
# shellcheck disable=SC2086
set -- $packages
expected_packages="$#"
set --
# GNU coreutils is installed only so apt resolves dependencies honestly; of the
# whole package just these files are transferred. install/cp/mv are deliberately
# left out because they pull in libacl.
coreutils_files="/bin/mkdir /bin/chmod /usr/bin/env /usr/share/doc/coreutils/copyright"
mkdir -p \
"$dest/usr/local/bin" \
"$dest/var/lib/dpkg" \
"$dest/etc" \
"$dest/tmp" \
"$dest/run/lock" \
"$dest/usr/share/crank"
# A world-writable sticky /tmp and the run-state directories match the FHS and
# the previous slim image. /run and /run/lock also give the base-files
# /var/run and /var/lock symlinks valid targets.
chmod 1777 "$dest/tmp"
chmod 0755 "$dest/run"
chmod 1777 "$dest/run/lock"
status="$dest/var/lib/dpkg/status"
inventory="$dest/usr/share/crank/runtime-inventory.tsv"
: > "$status"
: > "$inventory"
for package in $packages; do
version="$(dpkg-query -W -f='${Version}' "$package")"
printf 'runtime-package: %s %s\n' "$package" "$version"
# dpkg/status paragraph, separated from the next one by a blank line.
dpkg-query -s "$package" >> "$status"
printf '\n' >> "$status"
# shellcheck disable=SC2086
for source in $(dpkg-query -L "$package"); do
if [ "$package" = "coreutils" ]; then
allowed=0
# shellcheck disable=SC2086
for candidate in $coreutils_files; do
if [ "$source" = "$candidate" ]; then
allowed=1
break
fi
done
[ "$allowed" -eq 1 ] || continue
fi
if [ ! -f "$source" ] && [ ! -L "$source" ]; then
continue
fi
directory="$(readlink -f "$(dirname -- "$source")")"
base="$(basename -- "$source")"
if [ "$directory" = "/" ]; then
path="/$base"
parent="$dest"
else
path="$directory/$base"
parent="$dest$directory"
fi
# Several packages list the same merged-/usr symlink; keep the first
# copy and skip duplicates so the manifest has one row per path.
if [ -e "$dest$path" ] || [ -L "$dest$path" ]; then
continue
fi
mkdir -p "$parent"
cp -a --no-target-directory -- "$source" "$dest$path"
if [ -L "$source" ]; then
digest="$(readlink -- "$source")"
else
digest="$(sha256sum -- "$source")"
digest="${digest%% *}"
fi
printf '%s\t%s\t%s\n' "$package" "$path" "$digest" >> "$inventory"
done
done
# Docker mounts /etc/hosts and /etc/resolv.conf, but the image still needs the
# root account and a name-service switch policy. `hosts: files dns` is required
# for getaddrinfo to fall back to DNS for outbound requests.
printf 'root:x:0:0:root:/root:/bin/sh\n' > "$dest/etc/passwd"
printf 'root:x:0:\n' > "$dest/etc/group"
printf 'passwd: files\ngroup: files\nhosts: files dns\n' > "$dest/etc/nsswitch.conf"
for generated in /etc/passwd /etc/group /etc/nsswitch.conf; do
digest="$(sha256sum -- "$dest$generated")"
digest="${digest%% *}"
printf 'runtime-generated\t%s\t%s\n' "$generated" "$digest" >> "$inventory"
done
count="$(grep -c '^Package: ' "$status")"
if [ "$count" -ne "$expected_packages" ]; then
echo "dpkg status holds $count packages, expected $expected_packages" >&2
exit 1
fi
# Merged-/usr and shell-entrypoint contracts must hold in the assembled rootfs.
for link in bin lib lib64 sbin; do
if [ ! -L "$dest/$link" ]; then
echo "merged-/usr symlink /$link missing from runtime rootfs" >&2
exit 1
fi
done
for exe in usr/bin/sh usr/bin/mkdir usr/bin/chmod usr/bin/env usr/bin/bash; do
if [ ! -x "$dest/$exe" ]; then
echo "runtime shell or coreutils subset missing: /$exe" >&2
exit 1
fi
done
if [ "$(grep -c . "$inventory")" -eq 0 ]; then
echo "runtime inventory is empty" >&2
exit 1
fi
printf 'runtime-inventory: %s files\n' "$(grep -c . "$inventory")"
+289 -11
View File
@@ -1,4 +1,30 @@
#!/bin/sh
# Scan the built Crank server images with a pinned Trivy and fail closed.
#
# The wrapper downloads and checksum-verifies one fixed Trivy release, downloads
# one fresh vulnerability database, then scans every requested image by its
# immutable Docker id with a fully pinned policy. It never trusts a local
# trivy.yaml, .trivyignore, VEX file or skip list: --config and --ignorefile
# point at /dev/null and every inherited TRIVY_* variable is removed before
# Trivy runs. Docker context and proxy variables are preserved.
#
# Artifacts are written to the evidence directory (default
# .tmp/image-scan-evidence, relocatable only through CRANK_IMAGE_SCAN_OUTPUT_DIR)
# and are kept even when the gate is red:
#
# db/metadata.json copy of the actual downloaded Trivy DB metadata
# db-download.log database download log
# scanner.json pinned scanner version and scan policy receipt
# <NN-slug>.json raw Trivy JSON report per image
# <NN-slug>.scan.log Trivy scan log per image
# <NN-slug>.gate.log checker output per image
# <NN-slug>.decision.json checker decision per image
# receipt.json aggregate tag<->immutable id<->raw<->decision receipt
#
# Every scan is finished by the accepted checker (scripts/check-image-scan.py),
# which owns the PASS/BLOCKED/ERROR decision and the DB-age check. The wrapper
# exits 0 only when every image passed, 1 when at least one image is blocked and
# 2 on any bootstrap, scan or evidence error.
set -eu
if [ "$#" -eq 0 ]; then
@@ -6,24 +32,276 @@ if [ "$#" -eq 0 ]; then
exit 2
fi
# Strip inherited TRIVY_* overrides so neither the environment nor a local Trivy
# config can loosen the policy. Only names are read; no values are logged.
for name in $(env | sed -n 's/^\(TRIVY_[A-Za-z0-9_]*\)=.*/\1/p'); do
unset "$name"
done
script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
checker="$script_dir/check-image-scan.py"
trivy_version="0.70.0"
archive="trivy_${trivy_version}_Linux-64bit.tar.gz"
expected_sha256="8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9"
download_url="https://github.com/aquasecurity/trivy/releases/download/v${trivy_version}/${archive}"
output_dir="${CRANK_IMAGE_SCAN_OUTPUT_DIR:-.tmp/image-scan-evidence}"
if ! mkdir -p "$output_dir"; then
echo "scan-images: cannot create evidence directory $output_dir" >&2
exit 2
fi
if ! output_dir="$(CDPATH= cd -- "$output_dir" && pwd)"; then
echo "scan-images: cannot resolve evidence directory $output_dir" >&2
exit 2
fi
# Each invocation owns a fresh artifact directory. An absent new report can
# never be mistaken for a successful report left by a previous invocation.
if ! output_dir="$(mktemp -d "$output_dir/run.XXXXXX")"; then
echo "scan-images: cannot create a fresh evidence run directory" >&2
exit 2
fi
temp_dir="$(mktemp -d)"
trap 'rm -rf "$temp_dir"' EXIT HUP INT TERM
cache_dir="$temp_dir/trivy-cache"
mkdir -p "$cache_dir"
cleanup() { rm -rf "$temp_dir"; }
trap cleanup EXIT HUP INT TERM
curl --fail --silent --show-error --location \
"https://github.com/aquasecurity/trivy/releases/download/v${trivy_version}/${archive}" \
--output "$temp_dir/$archive"
printf '%s %s\n' "$expected_sha256" "$temp_dir/$archive" | sha256sum --check --status
tar -C "$temp_dir" -xzf "$temp_dir/$archive" trivy
requested="$temp_dir/requested-images.txt"
printf '%s\n' "$@" > "$requested"
records="$temp_dir/records.jsonl"
: > "$records"
# Bootstrap failures still produce a receipt naming every requested image.
fail_all() {
reason="$1"
python3 - "$output_dir/receipt.json" "$reason" "$requested" <<'PY'
import json
import sys
receipt_path, reason, requested_path = sys.argv[1:4]
with open(requested_path, encoding="utf-8") as stream:
images = [line for line in stream.read().splitlines() if line]
receipt = {
"schema": "crank.image-scan.receipt.v1",
"error": reason,
"overall": {"status": "error", "exit_code": 2},
"images": [
{"index": index + 1, "tag": tag, "status": "error", "error": reason}
for index, tag in enumerate(images)
],
}
with open(receipt_path, "w", encoding="utf-8") as stream:
json.dump(receipt, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
echo "scan-images: $reason" >&2
exit 2
}
# Download and checksum-verify the pinned scanner exactly once.
if ! curl --fail --silent --show-error --location --max-time 300 \
"$download_url" --output "$temp_dir/$archive" \
>"$output_dir/scanner-download.log" 2>&1; then
fail_all "could not download pinned Trivy ${trivy_version}"
fi
if ! printf '%s %s\n' "$expected_sha256" "$temp_dir/$archive" \
| sha256sum --check --status; then
fail_all "pinned Trivy archive checksum mismatch"
fi
trivy_bin="$temp_dir/trivy"
if ! tar -C "$temp_dir" -xzf "$temp_dir/$archive" trivy; then
fail_all "could not extract the pinned Trivy archive"
fi
if [ ! -x "$trivy_bin" ]; then
fail_all "pinned Trivy executable is missing after extraction"
fi
# Download one fresh vulnerability database; every scan reuses it read-only.
if ! "$trivy_bin" image --config /dev/null --download-db-only --cache-dir "$cache_dir" \
--no-progress --skip-version-check \
>"$output_dir/db-download.log" 2>&1; then
fail_all "could not download the Trivy vulnerability database"
fi
db_metadata="$output_dir/db/metadata.json"
mkdir -p "$output_dir/db"
if ! cp "$cache_dir/db/metadata.json" "$db_metadata"; then
fail_all "Trivy database metadata was not produced"
fi
if ! version_output="$("$trivy_bin" --config /dev/null --cache-dir "$cache_dir" --version 2>&1)"; then
fail_all "could not read pinned Trivy version"
fi
reported_version="$(printf '%s\n' "$version_output" | sed -n 's/^Version:[[:space:]]*//p' | head -n 1)"
if [ "$reported_version" != "$trivy_version" ]; then
fail_all "pinned Trivy reported an unexpected version"
fi
python3 - "$output_dir/scanner.json" "$trivy_version" "$expected_sha256" \
"$archive" "$version_output" <<'PY'
import json
import sys
path, expected, digest, archive, reported = sys.argv[1:6]
reported_version = next(
(line.strip() for line in reported.splitlines() if line.strip()), ""
)
payload = {
"schema": "crank.image-scan.scanner.v1",
"expected_version": expected,
"reported_version": reported_version,
"archive": archive,
"archive_sha256": digest,
"policy": {
"image_source": "docker",
"config": "/dev/null",
"ignorefile": "/dev/null",
"ignore_unfixed": False,
"list_all_pkgs": True,
"severities": ["UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL"],
"scanners": ["vuln"],
"skip_db_update": True,
"skip_version_check": True,
},
}
with open(path, "w", encoding="utf-8") as stream:
json.dump(payload, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
overall_rc=0
index=0
for image in "$@"; do
"$temp_dir/trivy" image \
--exit-code 1 \
--ignore-unfixed \
--severity HIGH,CRITICAL \
index=$((index + 1))
slug="$(printf '%s' "$image" \
| sed 's/[^A-Za-z0-9._-]/_/g; s/^[.-]*//; s/[.-]*$//' \
| cut -c1-80)"
[ -n "$slug" ] || slug="image"
base="$(printf '%02d' "$index")-$slug"
raw="$output_dir/$base.json"
scan_log="$output_dir/$base.scan.log"
gate_log="$output_dir/$base.gate.log"
decision="$output_dir/$base.decision.json"
image_id="$(docker image inspect --format '{{.Id}}' "$image" \
2>"$output_dir/$base.inspect.log" || true)"
image_id="$(printf '%s' "$image_id" | tr -d '[:space:]')"
scan_rc=0
if [ -z "$image_id" ]; then
scan_rc=2
printf 'scan-images: cannot resolve an immutable id for %s\n' "$image" >&2
elif "$trivy_bin" image \
--image-src docker \
--config /dev/null \
--ignorefile /dev/null \
--ignore-unfixed=false \
--list-all-pkgs=true \
--severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL \
--scanners vuln \
--format json \
--exit-code 0 \
--skip-db-update \
--cache-dir "$cache_dir" \
--no-progress \
"$image"
--skip-version-check \
--output "$raw" \
"$image_id" >"$scan_log" 2>&1; then
scan_rc=0
else
scan_rc=$?
fi
# The checker is always invoked so every image gets a decision artifact,
# even when the scan itself failed. Missing or malformed evidence is
# reported by the checker itself with exit code 2.
if gate_output="$(python3 "$checker" \
--report "$raw" \
--image-id "$image_id" \
--db-metadata "$db_metadata" \
--decision "$decision" 2>&1)"; then
gate_rc=0
else
gate_rc=$?
fi
printf '%s\n' "$gate_output" >"$gate_log"
printf '%s\n' "$gate_output"
effective_rc="$gate_rc"
if [ "$scan_rc" -ne 0 ] && [ "$effective_rc" -lt 2 ]; then
effective_rc=2
fi
if [ "$effective_rc" -gt "$overall_rc" ]; then
overall_rc="$effective_rc"
fi
case "$effective_rc" in
0) status="pass" ;;
1) status="blocked" ;;
*) status="error" ;;
esac
python3 - "$records" "$index" "$image" "$image_id" "$raw" "$scan_log" \
"$gate_log" "$decision" "$scan_rc" "$gate_rc" "$status" <<'PY'
import json
import sys
(
records_path, index, tag, image_id, raw, scan_log, gate_log, decision,
scan_exit, gate_exit, status,
) = sys.argv[1:12]
record = {
"index": int(index),
"tag": tag,
"image_id": image_id or None,
"raw": raw,
"scan_log": scan_log,
"gate_log": gate_log,
"decision": decision,
"scan_exit": int(scan_exit),
"gate_exit": int(gate_exit),
"status": status,
}
with open(records_path, "a", encoding="utf-8") as stream:
stream.write(json.dumps(record) + "\n")
PY
done
case "$overall_rc" in
0) overall_status="pass" ;;
1) overall_status="blocked" ;;
*) overall_status="error" ;;
esac
python3 - "$records" "$output_dir/receipt.json" "$db_metadata" \
"$output_dir/scanner.json" "$overall_rc" "$overall_status" "$output_dir" <<'PY'
import json
import sys
records_path, receipt_path, db_path, scanner_path, exit_code, status, out_dir = (
sys.argv[1:8]
)
with open(records_path, encoding="utf-8") as stream:
images = [json.loads(line) for line in stream if line.strip()]
with open(scanner_path, encoding="utf-8") as stream:
scanner = json.load(stream)
with open(db_path, encoding="utf-8") as stream:
db_metadata = json.load(stream)
receipt = {
"schema": "crank.image-scan.receipt.v1",
"output_dir": out_dir,
"scanner": scanner,
"database": {
"metadata_path": db_path,
"updated_at": db_metadata.get("UpdatedAt"),
},
"overall": {"status": status, "exit_code": int(exit_code)},
"images": images,
}
with open(receipt_path, "w", encoding="utf-8") as stream:
json.dump(receipt, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
printf 'scan-images: %s (%s/receipt.json)\n' "$overall_status" "$output_dir"
exit "$overall_rc"