791 lines
31 KiB
Python
Executable File
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())
|