From f685616ae873596d126951d0d367cf5b64cc0dac Mon Sep 17 00:00:00 2001 From: bsodfather Date: Sat, 10 Oct 2026 01:41:38 +0300 Subject: [PATCH] fix(security): minimize runtime images and enforce complete vulnerability scans --- .gitea/workflows/ci.yml | 16 + apps/admin-api/Dockerfile | 39 +- apps/admin-api/docker-entrypoint.sh | 13 +- apps/mcp-server/Dockerfile | 36 +- deploy/community/docker-compose.images.yml | 4 +- deploy/community/docker-compose.yml | 4 +- docker-compose.yml | 4 +- docs/security/image-scanning.md | 159 +++++ scripts/check-image-scan.py | 790 +++++++++++++++++++++ scripts/prepare-runtime-rootfs.sh | 169 +++++ scripts/scan-images.sh | 300 +++++++- tests/unit/test_check_image_scan.py | 777 ++++++++++++++++++++ tests/unit/test_scan_images.py | 462 ++++++++++++ 13 files changed, 2736 insertions(+), 37 deletions(-) create mode 100644 docs/security/image-scanning.md create mode 100755 scripts/check-image-scan.py create mode 100755 scripts/prepare-runtime-rootfs.sh create mode 100644 tests/unit/test_check_image_scan.py create mode 100644 tests/unit/test_scan_images.py diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index ee678bc..d7ca6ab 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -304,6 +304,14 @@ jobs: crank/mcp-server:ci \ crank/ui:ci + - name: Save Community image scan evidence + if: always() + uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 # v4 + with: + name: image-scan-evidence + path: .tmp/image-scan-evidence + if-no-files-found: warn + - name: Start Community image stack run: | mkdir -p .tmp @@ -458,6 +466,14 @@ jobs: docker push '${{ env.UI_IMAGE }}:${{ env.IMAGE_TAG }}' docker push '${{ env.UI_IMAGE }}:main' + - name: Save deploy image scan evidence + if: always() + uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 # v4 + with: + name: deploy-image-scan-evidence + path: .tmp/image-scan-evidence + if-no-files-found: warn + - name: Configure SSH key run: | . "$OPENBAO_ENV_FILE" diff --git a/apps/admin-api/Dockerfile b/apps/admin-api/Dockerfile index d6f7993..c856e66 100644 --- a/apps/admin-api/Dockerfile +++ b/apps/admin-api/Dockerfile @@ -15,33 +15,52 @@ RUN --mount=type=cache,id=crank-admin-cargo-registry,target=/usr/local/cargo/reg && cp /app/target/release/admin-api /tmp/admin-api \ && cp /app/target/release/crank-migrate /tmp/crank-migrate -FROM debian:bookworm-slim +# Trusted CA bundle source for the package stage. The slim image ships no CA +# certificates, so the HTTPS Debian mirror can only be reached after seeding +# them; the Rust base image provides the bundle without rebuilding the app. +FROM rust:1.96.1-bookworm AS ca-bundle + +RUN test -s /etc/ssl/certs/ca-certificates.crt + +# Package stage: install the security-refreshed Debian packages, then assemble +# the minimal runtime rootfs. Kept independent of the Rust builder so it can be +# built and reviewed on its own. +FROM debian:bookworm-slim AS runtime-rootfs ARG CRANK_SECURITY_REFRESH -COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY --from=ca-bundle /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY scripts/prepare-runtime-rootfs.sh /usr/local/bin/prepare-runtime-rootfs RUN sed -i 's|http://deb.debian.org|https://deb.debian.org|g' /etc/apt/sources.list.d/debian.sources \ && apt-get update \ - && apt-get install -y --no-install-recommends --only-upgrade libpcre2-8-0 perl-base \ + && apt-get install -y --no-install-recommends --only-upgrade \ + base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils \ && rm -rf /var/lib/apt/lists/* \ && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' libpcre2-8-0)" ge '10.42-1+deb12u2' \ - && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' perl-base)" ge '5.36.0-7+deb12u4' \ + && sh /usr/local/bin/prepare-runtime-rootfs /runtime \ && echo "crank-security-refresh=${CRANK_SECURITY_REFRESH}" -WORKDIR /app +COPY apps/admin-api/docker-entrypoint.sh /runtime/usr/local/bin/crank-admin-entrypoint +COPY scripts/docker-http-healthcheck.sh /runtime/usr/local/bin/crank-http-healthcheck + +RUN chmod 0755 /runtime/usr/local/bin/crank-admin-entrypoint \ + && chmod 0755 /runtime/usr/local/bin/crank-http-healthcheck + +FROM scratch + +COPY --from=ca-bundle /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY --from=runtime-rootfs /runtime / COPY --from=builder /tmp/admin-api /usr/local/bin/admin-api COPY --from=builder /tmp/crank-migrate /usr/local/bin/crank-migrate -COPY apps/admin-api/docker-entrypoint.sh /usr/local/bin/crank-admin-entrypoint -COPY scripts/docker-http-healthcheck.sh /usr/local/bin/crank-http-healthcheck - -RUN test -s /etc/ssl/certs/ca-certificates.crt \ - && chmod 0755 /usr/local/bin/crank-admin-entrypoint /usr/local/bin/crank-http-healthcheck +ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ENV CRANK_ADMIN_BIND=0.0.0.0:3001 ENV CRANK_STORAGE_ROOT=/var/lib/crank/storage +WORKDIR /app + EXPOSE 3001 ENTRYPOINT ["/usr/local/bin/crank-admin-entrypoint"] diff --git a/apps/admin-api/docker-entrypoint.sh b/apps/admin-api/docker-entrypoint.sh index 075c645..2373cf2 100644 --- a/apps/admin-api/docker-entrypoint.sh +++ b/apps/admin-api/docker-entrypoint.sh @@ -4,7 +4,7 @@ set -eu # Docker creates a fresh named volume as root:root 0755. The artifact store # deliberately rejects that mode: before starting the API, provision exactly # the private root its pinned-directory checks require. -if [ "$#" -gt 0 ] && [ "$1" = "admin-api" ]; then +provision_storage_root() { storage_root="${CRANK_STORAGE_ROOT:-/var/lib/crank/storage}" case "$storage_root" in /*) ;; @@ -20,6 +20,17 @@ if [ "$#" -gt 0 ] && [ "$1" = "admin-api" ]; then umask 077 mkdir -p -- "$storage_root" chmod 0700 -- "$storage_root" +} + +# The dedicated init service calls this entrypoint as `crank-storage-init`; it +# provisions the artifact root and exits without running a server binary. +if [ "${1:-}" = "crank-storage-init" ]; then + provision_storage_root + exit 0 +fi + +if [ "${1:-}" = "admin-api" ]; then + provision_storage_root fi exec "$@" diff --git a/apps/mcp-server/Dockerfile b/apps/mcp-server/Dockerfile index c7e88db..dc83b89 100644 --- a/apps/mcp-server/Dockerfile +++ b/apps/mcp-server/Dockerfile @@ -53,30 +53,48 @@ RUN --mount=type=cache,id=crank-mcp-cargo-registry,target=/usr/local/cargo/regis SQLX_OFFLINE=true cargo build --release -p mcp-server \ && cp /app/target/release/mcp-server /tmp/mcp-server -FROM debian:bookworm-slim +# Trusted CA bundle source for the package stage. The slim image ships no CA +# certificates, so the HTTPS Debian mirror can only be reached after seeding +# them; the Rust base image provides the bundle without rebuilding the app. +FROM rust:1.96.1-bookworm AS ca-bundle + +RUN test -s /etc/ssl/certs/ca-certificates.crt + +# Package stage: install the security-refreshed Debian packages, then assemble +# the minimal runtime rootfs. Kept independent of the Rust builder so it can be +# built and reviewed on its own. +FROM debian:bookworm-slim AS runtime-rootfs ARG CRANK_SECURITY_REFRESH -COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY --from=ca-bundle /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY scripts/prepare-runtime-rootfs.sh /usr/local/bin/prepare-runtime-rootfs RUN sed -i 's|http://deb.debian.org|https://deb.debian.org|g' /etc/apt/sources.list.d/debian.sources \ && apt-get update \ - && apt-get install -y --no-install-recommends --only-upgrade libpcre2-8-0 perl-base \ + && apt-get install -y --no-install-recommends --only-upgrade \ + base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils \ && rm -rf /var/lib/apt/lists/* \ && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' libpcre2-8-0)" ge '10.42-1+deb12u2' \ - && dpkg --compare-versions "$(dpkg-query -W -f='${Version}' perl-base)" ge '5.36.0-7+deb12u4' \ + && sh /usr/local/bin/prepare-runtime-rootfs /runtime \ && echo "crank-security-refresh=${CRANK_SECURITY_REFRESH}" -WORKDIR /app +COPY scripts/docker-http-healthcheck.sh /runtime/usr/local/bin/crank-http-healthcheck + +RUN chmod 0755 /runtime/usr/local/bin/crank-http-healthcheck + +FROM scratch + +COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt +COPY --from=runtime-rootfs /runtime / COPY --from=builder /tmp/mcp-server /usr/local/bin/mcp-server -COPY scripts/docker-http-healthcheck.sh /usr/local/bin/crank-http-healthcheck - -RUN test -s /etc/ssl/certs/ca-certificates.crt \ - && chmod 0755 /usr/local/bin/crank-http-healthcheck +ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ENV CRANK_MCP_BIND=0.0.0.0:3002 +WORKDIR /app + EXPOSE 3002 CMD ["mcp-server"] diff --git a/deploy/community/docker-compose.images.yml b/deploy/community/docker-compose.images.yml index 9fb8cc1..5e4b5b2 100644 --- a/deploy/community/docker-compose.images.yml +++ b/deploy/community/docker-compose.images.yml @@ -57,8 +57,8 @@ services: artifact-storage-init: image: ${CRANK_ADMIN_API_IMAGE:-git.itexp.me/bsodfather/crank-community-admin-api:main} - entrypoint: ["/bin/sh", "-ec"] - command: ["install -d -m 700 -- \"$${CRANK_STORAGE_ROOT}\""] + entrypoint: ["/usr/local/bin/crank-admin-entrypoint"] + command: ["crank-storage-init"] restart: "no" environment: CRANK_STORAGE_ROOT: ${CRANK_STORAGE_ROOT:-/var/lib/crank/storage} diff --git a/deploy/community/docker-compose.yml b/deploy/community/docker-compose.yml index 51409ca..46cad9b 100644 --- a/deploy/community/docker-compose.yml +++ b/deploy/community/docker-compose.yml @@ -61,8 +61,8 @@ services: build: context: ../.. dockerfile: apps/admin-api/Dockerfile - entrypoint: ["/bin/sh", "-ec"] - command: ["install -d -m 700 -- \"$${CRANK_STORAGE_ROOT}\""] + entrypoint: ["/usr/local/bin/crank-admin-entrypoint"] + command: ["crank-storage-init"] restart: "no" environment: CRANK_STORAGE_ROOT: ${CRANK_STORAGE_ROOT:-/var/lib/crank/storage} diff --git a/docker-compose.yml b/docker-compose.yml index 828c26c..f1fe6aa 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -44,8 +44,8 @@ services: build: context: . dockerfile: apps/admin-api/Dockerfile - entrypoint: ["/bin/sh", "-ec"] - command: ["install -d -m 700 -- \"$${CRANK_STORAGE_ROOT}\""] + entrypoint: ["/usr/local/bin/crank-admin-entrypoint"] + command: ["crank-storage-init"] restart: "no" environment: CRANK_STORAGE_ROOT: ${CRANK_STORAGE_ROOT:-/var/lib/crank/storage} diff --git a/docs/security/image-scanning.md b/docs/security/image-scanning.md new file mode 100644 index 0000000..c65c34c --- /dev/null +++ b/docs/security/image-scanning.md @@ -0,0 +1,159 @@ +# Сканирование образов и минимальный runtime + +Документ описывает, как устроены конечные серверные образы Crank, как +сокращён состав окружения и как CI блокирует неподтверждённые результаты проверки. +Он относится к одной конкретной проблеме безопасности и **не закрывает +оставшиеся NFR-риски**: это только часть работы, а не полное подтверждение +соответствия NFR. + +## Минимальный runtime + +`admin-api` и `mcp-server` собираются `FROM scratch`: в финальный слой попадает +не Debian slim, а заранее собранный минимальный rootfs. Его формирует +`scripts/prepare-runtime-rootfs.sh` во время package stage Dockerfile +(`apps/admin-api/Dockerfile`, `apps/mcp-server/Dockerfile`). + +В rootfs переносятся только файлы явного allowlist-набора из **десяти** Debian +пакетов: + +```text +base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils +``` + +- `gcc-12-base` добавлен, чтобы copyright-файл, на который ссылается + `libgcc-s1`, существовал вместе со своим пакетом-владельцем. +- От `coreutils` переносятся только `mkdir`, `chmod`, `env` и их copyright. + Полный GNU coreutils, `apt`, `libacl`, GNU `gzip`, `util-linux`, `infocmp` и + BusyBox сознательно не попадают в образ. +- Сохраняются Rust 1.96.1/glibc, CA-сертификаты, мигратор, порты, readiness, + shell healthcheck, cold storage-init с правами 0700 и проверки путей. + +### Учёт файлов и лицензии + +Вместе с файлами rootfs создаётся проверяемая опись: + +- `/usr/share/crank/runtime-inventory.tsv` — TSV из трёх колонок: + `packagenormalized absolute pathsha256` для обычного файла либо + target симлинка. Сгенерированные самим helper-ом файлы (`/etc/passwd`, + `/etc/group`, `/etc/nsswitch.conf`) помечены синтетическим пакетом + `runtime-generated`. Путь фиксирован и не настраивается. +- `/var/lib/dpkg/status` — десять параграфов с реальными версиями пакетов. + Сам файл и inventory в TSV намеренно не перечисляются. +- Лицензии ориентируются на фактические `copyright`-файлы перенесённых + пакетов; версия каждого пакета берётся из dpkg, а не из внешнего списка. + +Инвентарь содержит около 355 записей и проверяется не по декларации, а по +реальному immutable образу (см. ниже). + +## Что делает обёртка сканирования + +`scripts/scan-images.sh IMAGE [IMAGE ...]` — единственная точка входа для CI: + +1. Однократно скачивает и проверяет по SHA256 зафиксированную версию Trivy 0.70.0 + (`8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9`). +2. Однократно скачивает свежую vulnerability DB в изолированный cache. +3. Для каждого образа получает immutable id через `docker image inspect` и + сканирует **именно id**, а не тег. +4. Завершает каждый скан вызовом checker: + `scripts/check-image-scan.py --report ... --image-id ... --db-metadata ... --decision ...`. + +Политика сканирования жёстко зашита и не читает локальную конфигурацию: + +```text +--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 --no-progress --skip-version-check +``` + +Перед запуском Trivy обёртка удаляет все унаследованные переменные `TRIVY_*` +(имена читаются, значения не логируются), поэтому окружение не может подменить +severity, config, ignorefile, skip-files или VEX. Наследуемые Docker context и +proxy-переменные сохраняются. + +## Артефакты и коды выхода + +Результаты каждого запуска сохраняются в отдельном каталоге `.tmp/image-scan-evidence/run.XXXXXX` (расположение можно +изменить только переменной `CRANK_IMAGE_SCAN_OUTPUT_DIR`, не фильтрами) и +**сохраняются даже при красном результате**: + +```text +db/metadata.json копия фактических метаданных Trivy DB +db-download.log лог загрузки базы +scanner.json версия сканера и применённая политика +.json сырой JSON-отчёт Trivy по образу +.scan.log лог сканирования +.gate.log вывод checker +.decision.json решение checker по образу +receipt.json агрегированная квитанция tag<->immutable id<->raw<->decision +``` + +Сырой отчёт никогда не перезаписывается решением. Коды выхода: + +- `0` — PASS: все образы прошли, неразрешённых High/Critical нет. +- `1` — BLOCKED: есть High/Critical без точечного обоснованного исключения. +- `2` — ERROR: bootstrap/скан/evidence неполны, испорчены, просрочены или + не совпадают с реальным образом. + +Обёртка не останавливается на красном образе и обрабатывает оставшиеся; +итоговый код ненулевой, если хотя бы один образ не PASS. Сбой загрузки сканера +или базы также даёт ненулевой код и error-квитанцию для каждого запрошенного +образа. + +## Единственное исключение + +Проверяющий скрипт допускает только одну конкретную неприменимую находку и только при одновременном выполнении всех +условий: + +- CVE — `CVE-2025-69720`; +- пакет — `libtinfo6`, `InstalledVersion == 6.4-4`; +- дистрибутив — Debian 12; +- реальная версия `libtinfo6` в dpkg/status — `6.4-4`; +- `infocmp` отсутствует среди **всех** basename экспортированного образа; +- `ncurses-bin` отсутствует в dpkg/status. + +Уязвимость относится к front-end `infocmp` из ncurses, поэтому проверяется не +только имя/версия из отчёта Trivy, но и фактическая файловая система и +dpkg/status реального immutable образа. Любое другое имя, версия, дистрибутив +или наличие `infocmp`/`ncurses-bin` запрещает исключение и блокирует сборку. +Исходная находка остаётся в отчёте; в decision попадают `justification` и `image_id`. + +Первичный источник: Debian Security Tracker — +. + +Предыдущий разбор применимости CVE и доказательства сохранены в +[задаче Gitea #92](https://git.itexp.me/bsodfather/crank/issues/92). + +## Почему fail-closed + +- Отсутствие `Results`, `Packages` или целого отчёта не считается «пустым + корректным» результатом: это ошибка evidence, а не PASS. +- `Metadata.ImageID` обязан точно совпадать с immutable id, а OS, DB `UpdatedAt` + и версии пакетов сверяются с реальностью. +- DB старше 24 часов или из будущего более чем на 5 минут отклоняется. +- Отсутствие `infocmp` берётся из реального экспорта, а не из самого Trivy + отчёта: отчёту нельзя доверять в этом вопросе. +- Любая ошибка docker/tar/IO трактуется как отказ. + +## Повторная проверка + +Воспроизвести контроль локально: + +```sh +scripts/scan-images.sh crank/admin-api:ci crank/mcp-server:ci crank/ui:ci +python3 -m unittest discover -s tests/unit -p 'test_scan_images.py' +python3 -m unittest discover -s tests/unit -p 'test_check_image_scan.py' +``` + +Решение по каждому образу — в `.decision.json`, агрегированный итог и +связь тега с immutable id и артефактивами — в `receipt.json`. В CI полные +результаты публикуются отдельными artifact-ами даже при красном gate +(`image-scan-evidence` в Community Image Smoke и `deploy-image-scan-evidence` в +Deploy). + +## Границы + +Документ не утверждает, что все NFR выполнены. Остальные CONCERNS, не +относящиеся к перечню уязвимых компонентов и скрывающему фильтру CI, остаются +открытыми и проверяются отдельно. diff --git a/scripts/check-image-scan.py b/scripts/check-image-scan.py new file mode 100755 index 0000000..697a1f6 --- /dev/null +++ b/scripts/check-image-scan.py @@ -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()) diff --git a/scripts/prepare-runtime-rootfs.sh b/scripts/prepare-runtime-rootfs.sh new file mode 100755 index 0000000..43dfb5e --- /dev/null +++ b/scripts/prepare-runtime-rootfs.sh @@ -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: +# +# packagenormalized absolute pathsha256 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")" diff --git a/scripts/scan-images.sh b/scripts/scan-images.sh index 63fc963..7ce7170 100755 --- a/scripts/scan-images.sh +++ b/scripts/scan-images.sh @@ -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 +# .json raw Trivy JSON report per image +# .scan.log Trivy scan log per image +# .gate.log checker output per image +# .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" diff --git a/tests/unit/test_check_image_scan.py b/tests/unit/test_check_image_scan.py new file mode 100644 index 0000000..f810c19 --- /dev/null +++ b/tests/unit/test_check_image_scan.py @@ -0,0 +1,777 @@ +import hashlib +import importlib.util +import io +import json +import os +import shutil +import subprocess +import tarfile +import tempfile +import unittest +from unittest import mock +from datetime import datetime, timedelta, timezone +from pathlib import Path + + +SCRIPT = Path(__file__).parents[2] / "scripts" / "check-image-scan.py" + + +def load_checker(): + spec = importlib.util.spec_from_file_location("check_image_scan", SCRIPT) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + +IMAGE_ID = "sha256:" + "a" * 64 +CID = "0123456789ab" + +EXPECTED_PACKAGES = ( + "base-files", + "libc6", + "libgcc-s1", + "gcc-12-base", + "bash", + "dash", + "libtinfo6", + "libselinux1", + "libpcre2-8-0", + "coreutils", +) + +MANIFEST_PATH = "/usr/share/crank/runtime-inventory.tsv" +DPKG_STATUS_PATH = "/var/lib/dpkg/status" + +FAKE_DOCKER = '''#!/usr/bin/env python3 +import json +import os +import sys + +args = sys.argv[1:] +log = os.environ.get("FAKE_DOCKER_LOG") +if log: + with open(log, "a", encoding="utf-8") as stream: + stream.write(json.dumps(args) + "\\n") +if not args: + sys.exit(2) +command = args[0] +if command == "create": + rc = int(os.environ.get("FAKE_DOCKER_CREATE_RC", "0")) + if rc != 0: + sys.stderr.write("create failed\\n") + sys.exit(rc) + sys.stdout.write(os.environ.get("FAKE_DOCKER_CID", "deadbeefcafe") + "\\n") + sys.exit(0) +if command == "export": + rc = int(os.environ.get("FAKE_DOCKER_EXPORT_RC", "0")) + if rc != 0: + sys.stderr.write("export failed\\n") + sys.exit(rc) + with open(os.environ["FAKE_DOCKER_TAR"], "rb") as stream: + sys.stdout.buffer.write(stream.read()) + sys.exit(0) +if command == "rm": + sys.exit(0) +sys.exit(2) +''' + + +def sha256(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def build_tar(entries) -> bytes: + buffer = io.BytesIO() + with tarfile.open(fileobj=buffer, mode="w") as archive: + for kind, path, value in entries: + info = tarfile.TarInfo(path.lstrip("/")) + info.mode = 0o644 + info.uid = 0 + info.gid = 0 + if kind == "file": + data = value if isinstance(value, bytes) else value.encode("utf-8") + info.type = tarfile.REGTYPE + info.size = len(data) + archive.addfile(info, io.BytesIO(data)) + elif kind == "symlink": + info.type = tarfile.SYMTYPE + info.linkname = value + info.size = 0 + archive.addfile(info) + elif kind == "dir": + # Emulate Go's tar writer, which marks directories with a slash. + info.name = path.lstrip("/") + "/" + info.type = tarfile.DIRTYPE + info.size = 0 + archive.addfile(info) + else: + raise AssertionError(f"unknown entry kind {kind}") + return buffer.getvalue() + + +def build_status(packages, versions=None) -> str: + versions = versions or {} + blocks = [] + for name in packages: + blocks.append( + "Package: {name}\n" + "Status: install ok installed\n" + "Architecture: amd64\n" + "Version: {version}\n" + "Description: test package\n".format( + name=name, version=versions.get(name, "6.4-4" if name == "libtinfo6" else "1.2.3-1") + ) + ) + return "\n".join(blocks) + + +def runtime_image( + *, + manifest_text=None, + status_text=None, + extra_entries=(), + drop_manifest=False, + drop_status=False, + drop_files=(), +): + entries = [] + manifest_lines = [] + for package in EXPECTED_PACKAGES: + path = f"/usr/share/crank/{package}.payload" + data = f"{package} payload\n".encode("utf-8") + entries.append(("file", path, data)) + manifest_lines.append(f"{package}\t{path}\t{sha256(data)}") + entries.append(("symlink", "/usr/bin/sh", "dash")) + manifest_lines.append("dash\t/usr/bin/sh\tdash") + entries.append(("dir", "/usr/bin", None)) + entries.append(("dir", "/usr/share/crank", None)) + for path in ("/etc/passwd", "/etc/group", "/etc/nsswitch.conf"): + data = f"{path} generated\n".encode("utf-8") + entries.append(("file", path, data)) + manifest_lines.append(f"runtime-generated\t{path}\t{sha256(data)}") + entries.extend(tuple(extra_entries)) + if manifest_text is None: + manifest_text = "".join(line + "\n" for line in manifest_lines) + if not drop_manifest: + entries.append(("file", MANIFEST_PATH, manifest_text.encode("utf-8"))) + if status_text is None: + status_text = build_status(EXPECTED_PACKAGES) + if not drop_status: + entries.append(("file", DPKG_STATUS_PATH, status_text.encode("utf-8"))) + kept = set(drop_files) + return [entry for entry in entries if entry[1] not in kept] + + +def vulnerability( + vulnerability_id="CVE-2024-9999", + package="libc6", + installed="1.2.3-1", + severity="HIGH", + fixed=None, + status="affected", +): + record = { + "VulnerabilityID": vulnerability_id, + "PkgName": package, + "InstalledVersion": installed, + "Severity": severity, + "Status": status, + "Title": "test finding", + } + if fixed is not None: + record["FixedVersion"] = fixed + return record + + +def make_report( + *, + image_id=IMAGE_ID, + artifact_type="container_image", + os_family="debian", + os_name="12.11", + include_os=True, + include_metadata=True, + include_results=True, + packages=None, + vulnerabilities=None, + results=None, +): + if packages is None: + packages = [ + {"ID": f"{name}@1.2.3-1", "Name": name, "Version": "6.4-4" if name == "libtinfo6" else "1.2.3-1", "Arch": "amd64"} + for name in EXPECTED_PACKAGES + ] + result = { + "Target": "crank/test", + "Class": "os-pkgs", + "Type": os_family, + "Packages": packages, + } + if vulnerabilities is not None: + result["Vulnerabilities"] = vulnerabilities + report = { + "SchemaVersion": 2, + "ArtifactName": "crank/test", + "ArtifactType": artifact_type, + } + if include_metadata: + metadata = {"ImageID": image_id, "RepoTags": ["crank/test:ci"]} + if include_os: + metadata["OS"] = {"Family": os_family, "Name": os_name} + report["Metadata"] = metadata + if include_results: + report["Results"] = [result] if results is None else results + return report + + +class ImageScanCheckerTests(unittest.TestCase): + def run_check( + self, + *, + report=None, + report_raw=None, + db_updated=None, + db_raw=None, + tar_bytes=None, + image_id=IMAGE_ID, + extra_env=None, + decision_alias=None, + ): + root = Path(tempfile.mkdtemp()) + self.addCleanup(shutil.rmtree, root, ignore_errors=True) + + report_path = root / "report.json" + if report_raw is not None: + report_path.write_text(report_raw, encoding="utf-8") + else: + report_path.write_text(json.dumps(report), encoding="utf-8") + + db_path = root / "db.json" + if db_raw is not None: + db_path.write_text(db_raw, encoding="utf-8") + else: + updated = db_updated if db_updated is not None else datetime.now(timezone.utc) + db_path.write_text( + json.dumps({"Version": 2, "UpdatedAt": updated.isoformat()}), + encoding="utf-8", + ) + + tar_path = root / "image.tar" + if tar_bytes is None: + tar_bytes = build_tar(runtime_image()) + tar_path.write_bytes(tar_bytes) + + bin_dir = root / "bin" + bin_dir.mkdir() + docker = bin_dir / "docker" + docker.write_text(FAKE_DOCKER, encoding="utf-8") + docker.chmod(0o755) + + log = root / "docker.jsonl" + env = os.environ.copy() + env["PATH"] = f"{bin_dir}:{env['PATH']}" + env["FAKE_DOCKER_TAR"] = str(tar_path) + env["FAKE_DOCKER_CID"] = CID + env["FAKE_DOCKER_LOG"] = str(log) + if extra_env: + env.update(extra_env) + + decision_path = root / "decision.json" + if decision_alias == "report": + decision_path = report_path + elif decision_alias == "db": + decision_path = db_path + elif decision_alias == "symlink": + decision_path.symlink_to(report_path) + result = subprocess.run( + [ + "python3", + str(SCRIPT), + "--report", + str(report_path), + "--image-id", + image_id, + "--db-metadata", + str(db_path), + "--decision", + str(decision_path), + ], + text=True, + capture_output=True, + env=env, + check=False, + ) + decision = None + if decision_path.exists(): + decision = json.loads(decision_path.read_text(encoding="utf-8")) + calls = [] + if log.exists(): + calls = [ + json.loads(line) + for line in log.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + return result, decision, root, calls + + # ------------------------------------------------------------------ pass + def test_decision_alias_never_changes_protected_input(self): + report = make_report() + for alias in ("report", "db", "symlink"): + with self.subTest(alias=alias): + result, _, root, _ = self.run_check(report=report, decision_alias=alias) + self.assertEqual(result.returncode, 2) + self.assertEqual(json.loads((root / "report.json").read_text()), report) + self.assertEqual(json.loads((root / "db.json").read_text())["Version"], 2) + + def test_malformed_package_records_are_evidence_errors(self): + for package in (None, {}, {"Name": ""}, {"Name": "bash"}, {"Name": "bash", "Version": 3}): + with self.subTest(package=package): + result, decision, _, _ = self.run_check(report=make_report(os_family="alpine", os_name="3.23", packages=[package])) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_package_versions_must_match_exported_status(self): + report = make_report() + report["Results"][0]["Packages"][0]["Version"] = "999.0" + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_exception_requires_actual_libtinfo_version(self): + report = make_report(vulnerabilities=[vulnerability(vulnerability_id="CVE-2025-69720", package="libtinfo6", installed="6.4-4")]) + report["Results"][0]["Packages"] = [dict(p, Version="9.9") if p["Name"] == "libtinfo6" else p for p in report["Results"][0]["Packages"]] + tar = build_tar(runtime_image(status_text=build_status(EXPECTED_PACKAGES, {"libtinfo6": "9.9"}))) + result, decision, _, _ = self.run_check(report=report, tar_bytes=tar) + self.assertEqual(result.returncode, 1) + self.assertEqual(decision["exceptions"], []) + + def test_debian_129_is_not_the_debian12_exception(self): + report = make_report(os_name="129", vulnerabilities=[vulnerability(vulnerability_id="CVE-2025-69720", package="libtinfo6", installed="6.4-4")]) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 1) + self.assertEqual(decision["exceptions"], []) + + def test_duplicate_json_keys_are_evidence_errors(self): + payload = json.dumps(make_report()) + payload = payload[:-1] + ',"ArtifactType":"container_image"}' + result, decision, _, _ = self.run_check(report_raw=payload) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_invalid_timezone_produces_error_decision(self): + result, decision, _, _ = self.run_check(report=make_report(), db_raw='{"Version":2,"UpdatedAt":"2026-10-10T00:00:00+99:99"}') + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_unsupported_db_schema_is_evidence_error(self): + for version in (None, True, "2", 3): + with self.subTest(version=version): + metadata = {"Version": version, "UpdatedAt": datetime.now(timezone.utc).isoformat()} + result, decision, _, _ = self.run_check(report=make_report(), db_raw=json.dumps(metadata)) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_manifest_cannot_omit_a_transferred_file(self): + entries = runtime_image() + changed = [] + for kind, path, value in entries: + if path == MANIFEST_PATH: + value = "\n".join(value.decode().splitlines()[1:]).encode() + b"\n" + changed.append((kind, path, value)) + result, decision, _, _ = self.run_check(report=make_report(), tar_bytes=build_tar(changed)) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_undeclared_runtime_file_is_evidence_error(self): + tar = build_tar(runtime_image(extra_entries=[("file", "/usr/lib/undeclared.so", b"file")])) + result, decision, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2) + self.assertEqual(decision["status"], "error") + + def test_unexpected_dpkg_package_is_evidence_error(self): + tar = build_tar(runtime_image(status_text=build_status(EXPECTED_PACKAGES + ("unexpected",)))) + result, decision, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(decision["status"], "error") + + def test_unexpected_trivy_package_is_evidence_error(self): + report = make_report() + report["Results"][0]["Packages"].append({"Name": "unexpected", "Version": "1"}) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(decision["status"], "error") + + def test_stalled_export_has_a_deadline(self): + module = load_checker() + with tempfile.TemporaryDirectory() as directory: + docker = Path(directory) / "docker" + docker.write_text("#!/usr/bin/env python3\nimport time\ntime.sleep(2)\n") + docker.chmod(0o755) + with mock.patch.dict(os.environ, {"PATH": directory + ":" + os.environ["PATH"]}), \ + mock.patch.object(module, "DOCKER_TIMEOUT_SECONDS", 0.1): + with self.assertRaisesRegex(module.EvidenceError, "timed out"): + module._docker_export(CID) + + def test_clean_runtime_image_passes_and_verifies_real_files(self): + result, decision, _, calls = self.run_check(report=make_report()) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(decision["status"], "pass") + self.assertEqual(decision["exit_code"], 0) + self.assertIn(["create", "--entrypoint", "/bin/sh", IMAGE_ID], calls) + self.assertIn(["export", CID], calls) + self.assertIn(["rm", CID], calls) + self.assertGreater(decision["runtime_inventory"]["manifest_entries"], 0) + + def test_narrow_libtinfo_exception_passes_with_image_bound_justification(self): + report = make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-4", + severity="HIGH", + ) + ] + ) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(decision["status"], "pass") + self.assertEqual(len(decision["exceptions"]), 1) + exception = decision["exceptions"][0] + self.assertEqual(exception["vulnerability_id"], "CVE-2025-69720") + self.assertEqual(exception["image_id"], IMAGE_ID) + self.assertTrue(exception["justification"]) + self.assertEqual(decision["high_critical"][0]["disposition"], "excepted") + + def test_absent_vulnerabilities_with_packages_is_a_valid_empty_result(self): + result, decision, _, _ = self.run_check(report=make_report()) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(decision["severity_counts"]["HIGH"], 0) + + def test_only_medium_low_unknown_findings_pass_and_are_counted(self): + report = make_report( + vulnerabilities=[ + vulnerability(package="libc6", severity="MEDIUM"), + vulnerability(package="bash", severity="LOW"), + vulnerability(package="dash", severity="UNKNOWN"), + ] + ) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(decision["severity_counts"]["MEDIUM"], 1) + self.assertEqual(decision["severity_counts"]["LOW"], 1) + self.assertEqual(decision["severity_counts"]["UNKNOWN"], 1) + self.assertEqual(decision["blocking"], []) + + def test_non_debian_image_skips_runtime_manifest(self): + report = make_report( + os_family="alpine", + os_name="3.24", + packages=[{"ID": "musl@1.2", "Name": "musl", "Version": "1.2"}], + ) + result, decision, _, calls = self.run_check( + report=report, tar_bytes=build_tar([("file", "/bin/sh", b"busybox")]) + ) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(calls, []) + + # --------------------------------------------------------------- blocked + def test_unfixed_high_is_blocked(self): + report = make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2024-0001", + package="libc6", + severity="HIGH", + fixed=None, + ) + ] + ) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 1) + self.assertEqual(decision["status"], "blocked") + self.assertEqual(len(decision["blocking"]), 1) + self.assertEqual(decision["blocking"][0]["vulnerability_id"], "CVE-2024-0001") + + def test_critical_is_blocked(self): + report = make_report( + vulnerabilities=[vulnerability(package="bash", severity="CRITICAL")] + ) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 1) + self.assertEqual(decision["status"], "blocked") + + def test_libtinfo_exception_is_guarded_by_version_package_and_state(self): + guarded_reports = { + "wrong_version": make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-3", + severity="HIGH", + ) + ] + ), + "wrong_package": make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libselinux1", + installed="6.4-4", + severity="HIGH", + ) + ] + ), + "wrong_distribution": make_report( + os_name="11.9", + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-4", + severity="HIGH", + ) + ] + ), + } + for label, report in guarded_reports.items(): + with self.subTest(label=label): + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertEqual(decision["exceptions"], []) + + def test_libtinfo_exception_blocked_when_ncurses_bin_present(self): + report = make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-4", + severity="HIGH", + ) + ] + ) + tar = build_tar( + runtime_image(status_text=build_status(EXPECTED_PACKAGES + ("ncurses-bin",))) + ) + result, decision, _, _ = self.run_check(report=report, tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(decision["status"], "error") + + def test_libtinfo_exception_blocked_when_infocmp_present(self): + report = make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-4", + severity="HIGH", + ) + ] + ) + tar = build_tar( + runtime_image(extra_entries=[("file", "/usr/bin/infocmp", b"infocmp\n")]) + ) + result, decision, _, _ = self.run_check(report=report, tar_bytes=tar) + self.assertIn(result.returncode, (1, 2), result.stderr) + self.assertEqual(decision.get("exceptions", []), []) + + def test_exception_not_trusted_from_trivy_report_alone(self): + report = make_report( + vulnerabilities=[ + vulnerability( + vulnerability_id="CVE-2025-69720", + package="libtinfo6", + installed="6.4-4", + severity="HIGH", + ) + ] + ) + tar = build_tar( + runtime_image(extra_entries=[("file", "/usr/bin/infocmp", b"infocmp\n")]) + ) + result, _, _, _ = self.run_check(report=report, tar_bytes=tar) + self.assertIn(result.returncode, (1, 2), result.stderr) + + # ------------------------------------------------------- evidence errors + def test_wrong_image_id_is_evidence_error(self): + report = make_report(image_id="sha256:" + "b" * 64) + result, decision, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(decision["status"], "error") + + def test_wrong_artifact_type_is_evidence_error(self): + result, _, _, _ = self.run_check(report=make_report(artifact_type="filesystem")) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_malformed_report_is_evidence_error(self): + result, _, _, _ = self.run_check(report_raw="{not json") + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_results_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(include_results=False) + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_empty_results_is_evidence_error(self): + result, _, _, _ = self.run_check(report=make_report(results=[])) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_os_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(include_os=False) + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_empty_packages_without_vulnerabilities_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(packages=[], vulnerabilities=None) + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_packages_key_is_evidence_error(self): + report = make_report() + del report["Results"][0]["Packages"] + result, _, _, _ = self.run_check(report=report) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_unknown_severity_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(vulnerabilities=[vulnerability(severity="MODERATE")]) + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_stale_db_is_evidence_error(self): + updated = datetime.now(timezone.utc) - timedelta(hours=26) + result, _, _, _ = self.run_check( + report=make_report(), db_updated=updated + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_future_db_is_evidence_error(self): + updated = datetime.now(timezone.utc) + timedelta(minutes=10) + result, _, _, _ = self.run_check( + report=make_report(), db_updated=updated + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_malformed_db_metadata_is_evidence_error(self): + result, _, _, _ = self.run_check(report=make_report(), db_raw="{") + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_manifest_is_evidence_error(self): + tar = build_tar(runtime_image(drop_manifest=True)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_dpkg_status_is_evidence_error(self): + tar = build_tar(runtime_image(drop_status=True)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_manifest_hash_mismatch_is_evidence_error(self): + manifest = ( + "base-files\t/usr/share/crank/base-files.payload\t" + "0" * 64 + "\n" + ) + tar = build_tar(runtime_image(manifest_text=manifest)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_manifest_missing_image_file_is_evidence_error(self): + tar = build_tar(runtime_image(drop_files=["/usr/share/crank/bash.payload"])) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_manifest_duplicate_or_unnormalized_paths_are_evidence_errors(self): + base = ( + "base-files\t/etc/passwd\t" + sha256(b"/etc/passwd generated\n") + "\n" + ) + cases = { + "duplicate": base + base, + "unnormalized": "base-files\t/etc/../etc/passwd\t" + "0" * 64 + "\n", + "relative": "base-files\tetc/passwd\t" + "0" * 64 + "\n", + } + for label, manifest in cases.items(): + with self.subTest(label=label): + tar = build_tar(runtime_image(manifest_text=manifest)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_manifest_with_unexpected_package_label_is_evidence_error(self): + manifest = "linux-image\t/usr/bin/bash\t" + "0" * 64 + "\n" + tar = build_tar(runtime_image(manifest_text=manifest)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_manifest_listing_its_own_path_is_evidence_error(self): + manifest = f"runtime-generated\t{MANIFEST_PATH}\t{'0' * 64}\n" + tar = build_tar(runtime_image(manifest_text=manifest)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_expected_package_in_dpkg_is_evidence_error(self): + status = build_status( + [name for name in EXPECTED_PACKAGES if name != "libgcc-s1"] + ) + tar = build_tar(runtime_image(status_text=status)) + result, _, _, _ = self.run_check(report=make_report(), tar_bytes=tar) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_missing_expected_package_in_trivy_report_is_evidence_error(self): + packages = [ + {"ID": f"{name}@1.2.3-1", "Name": name, "Version": "1.2.3-1"} + for name in EXPECTED_PACKAGES + if name != "coreutils" + ] + result, _, _, _ = self.run_check(report=make_report(packages=packages)) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_docker_create_failure_is_evidence_error(self): + result, decision, _, _ = self.run_check( + report=make_report(), extra_env={"FAKE_DOCKER_CREATE_RC": "1"} + ) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(decision["status"], "error") + + def test_docker_export_failure_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(), extra_env={"FAKE_DOCKER_EXPORT_RC": "1"} + ) + self.assertEqual(result.returncode, 2, result.stderr) + + def test_docker_export_malformed_archive_is_evidence_error(self): + result, _, _, _ = self.run_check( + report=make_report(), tar_bytes=b"not a tar archive" + ) + self.assertEqual(result.returncode, 2, result.stderr) + + # ------------------------------------------------------------ assurance + def test_tar_path_normalization_handles_directory_slashes_and_traversal(self): + module = load_checker() + self.assertEqual(module.normalize_tar_path("usr/bin/"), "/usr/bin") + self.assertEqual(module.normalize_tar_path("./etc/passwd"), "/etc/passwd") + self.assertEqual(module.normalize_tar_path("/lib64"), "/lib64") + self.assertIsNone(module.normalize_tar_path("./")) + self.assertIsNone(module.normalize_tar_path("/")) + for unsafe in ("etc/../../etc/passwd", "usr//bin", "a/./b"): + with self.assertRaises(module.EvidenceError): + module.normalize_tar_path(unsafe) + + def test_raw_report_is_not_modified_by_the_gate(self): + report = make_report() + payload = json.dumps(report) + result, _, root, _ = self.run_check(report_raw=payload) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual((root / "report.json").read_text(encoding="utf-8"), payload) + + def test_decision_written_separately_on_error(self): + result, decision, root, _ = self.run_check(report_raw="{broken") + self.assertEqual(result.returncode, 2) + self.assertTrue((root / "decision.json").exists()) + self.assertEqual(decision["status"], "error") + self.assertTrue(decision["errors"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/unit/test_scan_images.py b/tests/unit/test_scan_images.py new file mode 100644 index 0000000..dec0b33 --- /dev/null +++ b/tests/unit/test_scan_images.py @@ -0,0 +1,462 @@ +import hashlib +import io +import json +import os +import re +import shutil +import subprocess +import tarfile +import tempfile +import unittest +from datetime import datetime, timedelta, timezone +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +WRAPPER = ROOT / "scripts" / "scan-images.sh" +CHECKER = ROOT / "scripts" / "check-image-scan.py" + +VULN_ID = "sha256:" + "1" * 64 +CLEAN_ID = "sha256:" + "2" * 64 + +VULN_TAG = "crank/vuln:ci" +CLEAN_TAG = "crank/clean:ci" + +FAKE_CURL = """#!/usr/bin/env python3 +import os +import sys + +args = sys.argv[1:] +if os.environ.get("FAKE_CURL_FAIL") == "1": + sys.stderr.write("curl: (7) failed to connect\\n") + sys.exit(7) +output = None +for index, value in enumerate(args): + if value in ("--output", "-o"): + output = args[index + 1] +if output is None: + sys.stderr.write("curl: missing --output\\n") + sys.exit(2) +with open(os.environ["FAKE_CURL_ARCHIVE"], "rb") as source: + payload = source.read() +with open(output, "wb") as target: + target.write(payload) +sys.exit(0) +""" + +FAKE_DOCKER = """#!/usr/bin/env python3 +import json +import os +import sys + +args = sys.argv[1:] +with open(os.environ["FAKE_DOCKER_LOG"], "a", encoding="utf-8") as stream: + stream.write(json.dumps(args) + "\\n") +if args[:2] == ["image", "inspect"]: + with open(os.environ["FAKE_IMAGE_MAP"], encoding="utf-8") as source: + mapping = json.load(source) + entry = mapping.get(args[-1]) + if entry is None: + sys.stderr.write("docker: no such image " + args[-1] + "\\n") + sys.exit(1) + sys.stdout.write(entry["id"] + "\\n") + sys.exit(0) +sys.stderr.write("docker: unexpected command\\n") +sys.exit(2) +""" + +# Fake Trivy shipped inside the stub scanner archive. It records every +# invocation and any inherited TRIVY_* variable so the test can prove the +# wrapper both pinned the flags and scrubbed the environment. +FAKE_TRIVY = """#!/usr/bin/env python3 +import json +import os +import sys +from datetime import datetime, timedelta, timezone + +args = sys.argv[1:] +log = os.environ.get("FAKE_TRIVY_LOG") +if log: + record = { + "args": args, + "trivy_env": sorted(name for name in os.environ if name.startswith("TRIVY_")), + } + with open(log, "a", encoding="utf-8") as stream: + stream.write(json.dumps(record) + "\\n") +if "--version" in args: + if os.environ.get("FAKE_TRIVY_VERSION_FAIL"): + sys.exit(7) + sys.stdout.write("Version: 0.70.0\\n") + sys.exit(0) +if "--download-db-only" in args: + cache = args[args.index("--cache-dir") + 1] + db_dir = os.path.join(cache, "db") + os.makedirs(db_dir, exist_ok=True) + with open(os.path.join(db_dir, "trivy.db"), "w", encoding="utf-8") as stream: + stream.write("fixture-db\\n") + now = datetime.now(timezone.utc) + metadata = { + "Version": 2, + "UpdatedAt": now.isoformat().replace("+00:00", "Z"), + "NextUpdate": (now + timedelta(hours=24)).isoformat().replace("+00:00", "Z"), + } + with open(os.path.join(db_dir, "metadata.json"), "w", encoding="utf-8") as stream: + json.dump(metadata, stream) + sys.exit(0) +target = args[-1] +if os.environ.get("FAKE_TRIVY_NO_OUTPUT_ID") == target: + sys.exit(0) +if os.environ.get("FAKE_TRIVY_FAIL_ID") == target: + sys.stderr.write("trivy: fixture scan failure for " + target + "\\n") + sys.exit(1) +output = args[args.index("--output") + 1] +source = os.path.join(os.environ["FAKE_REPORT_DIR"], target.replace(":", "_") + ".json") +if not os.path.exists(source): + sys.stderr.write("trivy: no report fixture for " + target + "\\n") + sys.exit(1) +with open(source, encoding="utf-8") as stream: + report = json.load(stream) +report["Metadata"]["ImageID"] = target +with open(output, "w", encoding="utf-8") as stream: + json.dump(report, stream) +sys.exit(0) +""" + + +def build_archive(script: str) -> bytes: + buffer = io.BytesIO() + with tarfile.open(fileobj=buffer, mode="w:gz") as archive: + data = script.encode("utf-8") + info = tarfile.TarInfo("trivy") + info.size = len(data) + info.mode = 0o755 + info.type = tarfile.REGTYPE + archive.addfile(info, io.BytesIO(data)) + return buffer.getvalue() + + +def alpine_report(image_id: str, vulnerabilities=None) -> dict: + result = { + "Target": "fixture:latest (alpine 3.24)", + "Class": "os-pkgs", + "Type": "alpine", + "Packages": [ + {"ID": "musl@1.2.5-r0", "Name": "musl", "Version": "1.2.5-r0"} + ], + } + if vulnerabilities is not None: + result["Vulnerabilities"] = vulnerabilities + return { + "SchemaVersion": 2, + "ArtifactName": "fixture:latest", + "ArtifactType": "container_image", + "Metadata": { + "ImageID": image_id, + "OS": {"Family": "alpine", "Name": "3.24"}, + }, + "Results": [result], + } + + +def unfixed_high() -> dict: + return { + "VulnerabilityID": "CVE-2024-0001", + "PkgName": "musl", + "InstalledVersion": "1.2.5-r0", + "Severity": "HIGH", + "Status": "affected", + "Title": "fixture unfixed high", + } + + +class ScanImagesWrapperTests(unittest.TestCase): + def run_scan( + self, + *, + images=(VULN_TAG, CLEAN_TAG), + trivy_fail_id=None, + curl_fail=False, + extra_env=None, + workdir_files=None, + run_in_workdir=False, + repeat_without_output=False, + ): + temporary = tempfile.TemporaryDirectory() + self.addCleanup(temporary.cleanup) + root = Path(temporary.name) + + bin_dir = root / "bin" + bin_dir.mkdir() + for name, contents in (("curl", FAKE_CURL), ("docker", FAKE_DOCKER)): + path = bin_dir / name + path.write_text(contents, encoding="utf-8") + path.chmod(0o755) + + wrappers = root / "wrappers" + wrappers.mkdir() + fixture_archive = build_archive(FAKE_TRIVY) + production = WRAPPER.read_text(encoding="utf-8") + fixture_hash = hashlib.sha256(fixture_archive).hexdigest() + # Replace only the pinned archive hash in the test copy; the production + # wrapper is never modified and there is no bypass environment variable. + patched, replacements = re.subn( + r'expected_sha256="[0-9a-f]{64}"', + f'expected_sha256="{fixture_hash}"', + production, + count=1, + ) + self.assertEqual(replacements, 1) + self.assertIn('expected_sha256="8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9"', production) + wrapper_copy = wrappers / "scan-images.sh" + wrapper_copy.write_text(patched, encoding="utf-8") + wrapper_copy.chmod(0o755) + shutil.copy2(CHECKER, wrappers / "check-image-scan.py") + + archive_path = root / "trivy-fixture.tar.gz" + archive_path.write_bytes(fixture_archive) + + reports = root / "reports" + reports.mkdir() + (reports / (VULN_ID.replace(":", "_") + ".json")).write_text( + json.dumps(alpine_report(VULN_ID, [unfixed_high()])), encoding="utf-8" + ) + (reports / (CLEAN_ID.replace(":", "_") + ".json")).write_text( + json.dumps(alpine_report(CLEAN_ID)), encoding="utf-8" + ) + + image_map = root / "images.json" + image_map.write_text( + json.dumps( + { + VULN_TAG: {"id": VULN_ID}, + CLEAN_TAG: {"id": CLEAN_ID}, + } + ), + encoding="utf-8", + ) + + evidence = root / "evidence" + docker_log = root / "docker.jsonl" + trivy_log = root / "trivy.jsonl" + + for name, contents in (workdir_files or {}).items(): + (root / name).write_text(contents, encoding="utf-8") + + env = os.environ.copy() + env.update( + { + "PATH": f"{bin_dir}:{env['PATH']}", + "CRANK_IMAGE_SCAN_OUTPUT_DIR": str(evidence), + "FAKE_CURL_ARCHIVE": str(archive_path), + "FAKE_IMAGE_MAP": str(image_map), + "FAKE_REPORT_DIR": str(reports), + "FAKE_DOCKER_LOG": str(docker_log), + "FAKE_TRIVY_LOG": str(trivy_log), + } + ) + if trivy_fail_id is not None: + env["FAKE_TRIVY_FAIL_ID"] = trivy_fail_id + if curl_fail: + env["FAKE_CURL_FAIL"] = "1" + if extra_env: + env.update(extra_env) + + result = subprocess.run( + ["sh", str(wrapper_copy), *images], + text=True, + capture_output=True, + env=env, + cwd=str(root) if run_in_workdir else None, + check=False, + ) + if repeat_without_output: + self.assertEqual(result.returncode, 0, result.stderr) + env["FAKE_TRIVY_NO_OUTPUT_ID"] = CLEAN_ID + result = subprocess.run(["sh", str(wrapper_copy), *images], text=True, capture_output=True, + env=env, cwd=str(root) if run_in_workdir else None, check=False) + + docker_calls = [] + if docker_log.exists(): + docker_calls = [ + json.loads(line) + for line in docker_log.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + trivy_calls = [] + if trivy_log.exists(): + trivy_calls = [ + json.loads(line) + for line in trivy_log.read_text(encoding="utf-8").splitlines() + if line.strip() + ] + receipt = None + runs = sorted(evidence.glob("run.*"), key=lambda path: path.stat().st_mtime_ns) + if runs: + evidence = runs[-1] + receipt_path = evidence / "receipt.json" + if receipt_path.exists(): + receipt = json.loads(receipt_path.read_text(encoding="utf-8")) + return result, root, evidence, receipt, docker_calls, trivy_calls + + @staticmethod + def scan_calls(trivy_calls): + return [call for call in trivy_calls if call["args"][:1] == ["image"] and "--output" in call["args"]] + + @staticmethod + def target_of(call): + return call["args"][-1] + + def test_unfixed_high_blocks_overall_but_both_images_scanned(self): + result, _, evidence, receipt, docker_calls, trivy_calls = self.run_scan() + self.assertEqual(result.returncode, 1, result.stderr) + + scans = self.scan_calls(trivy_calls) + self.assertEqual({self.target_of(call) for call in scans}, {VULN_ID, CLEAN_ID}) + self.assertEqual( + {call[-1] for call in docker_calls if call[:2] == ["image", "inspect"]}, + {VULN_TAG, CLEAN_TAG}, + ) + + self.assertIsNotNone(receipt) + self.assertEqual(receipt["overall"]["exit_code"], 1) + self.assertEqual(receipt["overall"]["status"], "blocked") + self.assertEqual(len(receipt["images"]), 2) + self.assertEqual({entry["tag"] for entry in receipt["images"]}, {VULN_TAG, CLEAN_TAG}) + self.assertIn(VULN_ID, {entry["image_id"] for entry in receipt["images"]}) + + by_tag = {entry["tag"]: entry for entry in receipt["images"]} + for entry in receipt["images"]: + self.assertTrue(Path(entry["raw"]).is_file(), entry["raw"]) + self.assertTrue(Path(entry["decision"]).is_file(), entry["decision"]) + self.assertTrue(Path(entry["scan_log"]).is_file(), entry["scan_log"]) + self.assertEqual(by_tag[VULN_TAG]["status"], "blocked") + self.assertEqual(by_tag[CLEAN_TAG]["status"], "pass") + + vuln_raw = json.loads(Path(by_tag[VULN_TAG]["raw"]).read_text(encoding="utf-8")) + clean_raw = json.loads(Path(by_tag[CLEAN_TAG]["raw"]).read_text(encoding="utf-8")) + self.assertEqual(vuln_raw["Metadata"]["ImageID"], VULN_ID) + self.assertEqual(clean_raw["Metadata"]["ImageID"], CLEAN_ID) + + vuln_decision = json.loads(Path(by_tag[VULN_TAG]["decision"]).read_text(encoding="utf-8")) + clean_decision = json.loads(Path(by_tag[CLEAN_TAG]["decision"]).read_text(encoding="utf-8")) + self.assertEqual(vuln_decision["status"], "blocked") + self.assertEqual(vuln_decision["blocking"][0]["vulnerability_id"], "CVE-2024-0001") + self.assertEqual(clean_decision["status"], "pass") + + def test_pinned_flags_survive_hidden_trivy_overrides(self): + hostile = { + "TRIVY_SEVERITY": "LOW", + "TRIVY_IGNORE_UNFIXED": "true", + "TRIVY_CONFIG": "/dev/null", + "TRIVY_SKIP_FILES": "usr/bin/infocmp", + "TRIVY_VEX": "vex.json", + "TRIVY_IGNORE_POLICY": "policy.rego", + } + result, _, _, _, _, trivy_calls = self.run_scan( + extra_env=hostile, + workdir_files={"trivy.yaml": "severity: LOW\nignore-unfixed: true\n"}, + run_in_workdir=True, + ) + self.assertEqual(result.returncode, 1, result.stderr) + for call in trivy_calls: + args = call["args"] + self.assertIn("--config", args) + self.assertEqual(args[args.index("--config") + 1], "/dev/null") + + scans = self.scan_calls(trivy_calls) + self.assertTrue(scans) + for call in scans: + args = call["args"] + self.assertEqual(call["trivy_env"], []) + self.assertIn("--image-src", args) + self.assertEqual(args[args.index("--image-src") + 1], "docker") + self.assertEqual(args[args.index("--config") + 1], "/dev/null") + self.assertEqual(args[args.index("--ignorefile") + 1], "/dev/null") + self.assertIn("--ignore-unfixed=false", args) + self.assertIn("--list-all-pkgs=true", args) + self.assertIn("--skip-db-update", args) + self.assertIn("--skip-version-check", args) + self.assertIn("--no-progress", args) + self.assertEqual(args[args.index("--exit-code") + 1], "0") + self.assertEqual(args[args.index("--scanners") + 1], "vuln") + self.assertEqual(args[args.index("--format") + 1], "json") + self.assertEqual( + args[args.index("--severity") + 1], + "UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL", + ) + + def test_scan_error_on_first_image_does_not_stop_the_second(self): + result, _, _, receipt, _, trivy_calls = self.run_scan(trivy_fail_id=VULN_ID) + self.assertEqual(result.returncode, 2, result.stderr) + + scans = self.scan_calls(trivy_calls) + self.assertEqual({self.target_of(call) for call in scans}, {VULN_ID, CLEAN_ID}) + + self.assertIsNotNone(receipt) + self.assertEqual(receipt["overall"]["exit_code"], 2) + self.assertEqual(receipt["overall"]["status"], "error") + by_tag = {entry["tag"]: entry for entry in receipt["images"]} + self.assertEqual(by_tag[VULN_TAG]["status"], "error") + self.assertEqual(by_tag[CLEAN_TAG]["status"], "pass") + clean_decision = json.loads( + Path(by_tag[CLEAN_TAG]["decision"]).read_text(encoding="utf-8") + ) + self.assertEqual(clean_decision["status"], "pass") + vuln_decision = json.loads( + Path(by_tag[VULN_TAG]["decision"]).read_text(encoding="utf-8") + ) + self.assertEqual(vuln_decision["status"], "error") + + def test_scanner_version_failure_is_a_bootstrap_error(self): + result, _, _, receipt, _, _ = self.run_scan(extra_env={"FAKE_TRIVY_VERSION_FAIL": "1"}) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(receipt["overall"]["status"], "error") + + def test_rerun_cannot_reuse_an_old_successful_raw_report(self): + result, _, evidence, receipt, _, _ = self.run_scan(images=(CLEAN_TAG,), repeat_without_output=True) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(receipt["overall"]["status"], "error") + self.assertEqual(receipt["images"][0]["status"], "error") + + def test_bootstrap_failure_writes_error_receipt_for_each_image(self): + result, _, _, receipt, docker_calls, trivy_calls = self.run_scan(curl_fail=True) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertIsNotNone(receipt) + self.assertEqual(receipt["overall"]["status"], "error") + self.assertEqual(receipt["overall"]["exit_code"], 2) + self.assertEqual(len(receipt["images"]), 2) + self.assertTrue(all(entry["status"] == "error" for entry in receipt["images"])) + self.assertEqual({entry["tag"] for entry in receipt["images"]}, {VULN_TAG, CLEAN_TAG}) + self.assertEqual(docker_calls, []) + self.assertEqual(trivy_calls, []) + + def test_unknown_image_is_error_and_is_never_scanned(self): + missing = "crank/missing:ci" + result, _, _, receipt, _, trivy_calls = self.run_scan(images=(missing, CLEAN_TAG)) + self.assertEqual(result.returncode, 2, result.stderr) + by_tag = {entry["tag"]: entry for entry in receipt["images"]} + self.assertEqual(by_tag[missing]["status"], "error") + self.assertEqual(by_tag[CLEAN_TAG]["status"], "pass") + self.assertEqual([self.target_of(call) for call in self.scan_calls(trivy_calls)], [CLEAN_ID]) + decision = json.loads(Path(by_tag[missing]["decision"]).read_text()) + self.assertEqual(decision["status"], "error") + + def test_download_error_log_is_retained(self): + result, _, evidence, receipt, _, _ = self.run_scan(curl_fail=True) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertEqual(receipt["overall"]["status"], "error") + self.assertIn("failed to connect", (evidence / "scanner-download.log").read_text()) + + def test_evidence_kept_even_when_gate_is_red(self): + _, _, evidence, receipt, _, _ = self.run_scan() + self.assertTrue((evidence / "receipt.json").is_file()) + self.assertTrue((evidence / "scanner.json").is_file()) + self.assertTrue((evidence / "db" / "metadata.json").is_file()) + scanner = json.loads((evidence / "scanner.json").read_text(encoding="utf-8")) + self.assertEqual(scanner["expected_version"], "0.70.0") + self.assertEqual(scanner["policy"]["ignore_unfixed"], False) + self.assertIsNotNone(receipt) + + +if __name__ == "__main__": + unittest.main()