fix(security): minimize runtime images and enforce complete vulnerability scans
CI / Rust Checks (pull_request) Successful in 23m1s
CI / UI Checks (pull_request) Successful in 6s
CI / Community Image Smoke (pull_request) Successful in 7m28s
CI / Frontend E2E (pull_request) Successful in 9m33s
CI / Deploy (pull_request) Skipped

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

No files matched your search

+16
View File
@@ -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"
+29 -10
View File
@@ -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"]
+12 -1
View File
@@ -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 "$@"
+27 -9
View File
@@ -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"]
+2 -2
View File
@@ -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}
+2 -2
View File
@@ -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}
+2 -2
View File
@@ -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}
+159
View File
@@ -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 из трёх колонок:
`package<TAB>normalized absolute path<TAB>sha256` для обычного файла либо
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 <isolated> --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 версия сканера и применённая политика
<NN-slug>.json сырой JSON-отчёт Trivy по образу
<NN-slug>.scan.log лог сканирования
<NN-slug>.gate.log вывод checker
<NN-slug>.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 —
<https://security-tracker.debian.org/tracker/CVE-2025-69720>.
Предыдущий разбор применимости 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'
```
Решение по каждому образу — в `<NN-slug>.decision.json`, агрегированный итог и
связь тега с immutable id и артефактивами — в `receipt.json`. В CI полные
результаты публикуются отдельными artifact-ами даже при красном gate
(`image-scan-evidence` в Community Image Smoke и `deploy-image-scan-evidence` в
Deploy).
## Границы
Документ не утверждает, что все NFR выполнены. Остальные CONCERNS, не
относящиеся к перечню уязвимых компонентов и скрывающему фильтру CI, остаются
открытыми и проверяются отдельно.
+790
View File
@@ -0,0 +1,790 @@
#!/usr/bin/env python3
"""Strict evidence gate over a raw Trivy image scan and the real image.
The scanner wrapper (``scripts/scan-images.sh``) produces one raw Trivy JSON
report per image and a copy of the Trivy DB metadata. This gate never rewrites
those raw artifacts; it reads them, validates their schema and provenance, then
cross-checks the findings against the immutable Docker image itself.
Exit codes:
0 PASS - evidence is consistent and no unresolved High/Critical remains.
1 BLOCKED- at least one High/Critical finding is not narrowly excepted.
2 ERROR - the evidence (report, DB metadata, manifest or image export) is
missing, malformed, stale or inconsistent.
The raw report is never modified. The evaluation result is written separately to
the ``--decision`` path. The only allowed High/Critical exception is the
CVE-2025-69720 false positive on the Debian 12 ``libtinfo6:6.4-4`` shared
library when the ``infocmp`` front-end tool (``ncurses-bin``) is genuinely
absent from the image; that absence is proven from the exported image, not from
the scan report.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import posixpath
import re
import subprocess
import sys
import tarfile
import tempfile
import threading
from datetime import datetime, timedelta, timezone
from pathlib import Path
# Packages that make up the Debian 12 server runtime rootfs. They must appear in
# both the dpkg status database and the Trivy OS package inventory.
EXPECTED_PACKAGES = (
"base-files",
"libc6",
"libgcc-s1",
"gcc-12-base",
"bash",
"dash",
"libtinfo6",
"libselinux1",
"libpcre2-8-0",
"coreutils",
)
# Fixed, non-overridable runtime inventory location (see prepare-runtime-rootfs).
RUNTIME_MANIFEST_PATH = "/usr/share/crank/runtime-inventory.tsv"
DPKG_STATUS_PATH = "/var/lib/dpkg/status"
SYNTHETIC_PACKAGE = "runtime-generated"
CAPTURED_PATHS = frozenset({RUNTIME_MANIFEST_PATH, DPKG_STATUS_PATH})
POST_PACKAGE_FILES = frozenset({
RUNTIME_MANIFEST_PATH, DPKG_STATUS_PATH,
"/etc/ssl/certs/ca-certificates.crt",
"/usr/local/bin/admin-api", "/usr/local/bin/crank-migrate",
"/usr/local/bin/mcp-server", "/usr/local/bin/crank-admin-entrypoint",
"/usr/local/bin/crank-http-healthcheck",
# Docker adds these container files; they are not Debian package contents.
"/.dockerenv", "/dev/console", "/etc/hostname", "/etc/hosts",
"/etc/mtab", "/etc/resolv.conf",
})
RUNTIME_OS_FAMILY = "debian"
RUNTIME_OS_NAME_PREFIX = "12"
ALLOWED_SEVERITIES = frozenset({"UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL"})
BLOCKING_SEVERITIES = frozenset({"HIGH", "CRITICAL"})
EXPECTED_CVE = "CVE-2025-69720"
EXCEPTED_PACKAGE = "libtinfo6"
EXCEPTED_VERSION = "6.4-4"
EXCEPTION_JUSTIFICATION = (
"CVE-2025-69720 describes the infocmp ncurses front-end. The runtime image "
"ships only the libtinfo6:6.4-4 shared library from Debian 12 and does not "
"contain /usr/bin/infocmp or the ncurses-bin package, so the vulnerable "
"code path is unreachable. Proven against the exported immutable image, not "
"the scan report."
)
ALLOWED_MANIFEST_PACKAGES = frozenset(EXPECTED_PACKAGES) | {SYNTHETIC_PACKAGE}
DB_MAX_AGE = timedelta(hours=24)
DB_MAX_FUTURE = timedelta(minutes=5)
MAX_REPORT_BYTES = 256 * 1024 * 1024
MAX_DB_METADATA_BYTES = 1024 * 1024
MAX_SPECIAL_FILE_BYTES = 4 * 1024 * 1024
MAX_EXPORT_ENTRIES = 200_000
MAX_EXPORT_BYTES = 512 * 1024 * 1024
DOCKER_TIMEOUT_SECONDS = 600
READ_CHUNK_BYTES = 64 * 1024
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
CONTAINER_ID_RE = re.compile(r"^[0-9a-f]{12,64}$")
TIMESTAMP_RE = re.compile(
r"^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2}):(\d{2})"
r"(?:\.(\d+))?(Z|z|[+-]\d{2}:?\d{2})?$"
)
class EvidenceError(Exception):
"""Raised when scan evidence is missing, malformed or inconsistent."""
def parse_args(argv) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Fail closed on unresolved High/Critical image findings."
)
parser.add_argument("--report", required=True, help="raw Trivy JSON report")
parser.add_argument("--image-id", required=True, help="immutable image ID")
parser.add_argument("--db-metadata", required=True, help="Trivy DB metadata")
parser.add_argument("--decision", required=True, help="decision output JSON")
return parser.parse_args(argv)
def unique_json_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise EvidenceError(f"duplicate JSON key: {key}")
result[key] = value
return result
def load_json(path: Path, max_bytes: int, label: str) -> dict:
try:
if not path.is_file():
raise EvidenceError(f"{label} is not a regular file")
with path.open("rb") as stream:
raw = stream.read(max_bytes + 1)
except OSError as error:
raise EvidenceError(f"{label} cannot be read: {error}") from error
if len(raw) > max_bytes:
raise EvidenceError(f"{label} exceeds the size budget")
if not raw.strip():
raise EvidenceError(f"{label} is empty")
try:
payload = json.loads(raw, object_pairs_hook=unique_json_object)
except (json.JSONDecodeError, UnicodeDecodeError) as error:
raise EvidenceError(f"{label} is not valid JSON: {error}") from error
if not isinstance(payload, dict):
raise EvidenceError(f"{label} must be a JSON object")
return payload
def parse_timestamp(value, label: str) -> datetime:
if not isinstance(value, str):
raise EvidenceError(f"{label} must be a string timestamp")
match = TIMESTAMP_RE.match(value.strip())
if not match or not match.group(8):
raise EvidenceError(f"{label} is not an RFC3339 timestamp: {value!r}")
text = value.strip()
if text.endswith(("Z", "z")):
text = text[:-1] + "+00:00"
try:
return datetime.fromisoformat(text)
except ValueError as error:
raise EvidenceError(f"{label} is not a valid timestamp: {value!r}") from error
def load_db_metadata(path: Path, now: datetime) -> dict:
payload = load_json(path, MAX_DB_METADATA_BYTES, "Trivy DB metadata")
if type(payload.get("Version")) is not int or payload["Version"] != 2:
raise EvidenceError("unsupported or missing Trivy DB schema version")
updated_at = parse_timestamp(payload.get("UpdatedAt"), "Trivy DB UpdatedAt")
age = now - updated_at
if age > DB_MAX_AGE:
raise EvidenceError(
f"Trivy DB is stale: updated {int(age.total_seconds())}s ago "
f"(limit {int(DB_MAX_AGE.total_seconds())}s)"
)
if updated_at - now > DB_MAX_FUTURE:
raise EvidenceError("Trivy DB UpdatedAt is too far in the future")
return {
"path": str(path),
"updated_at": updated_at.isoformat(),
"age_seconds": max(0, int(age.total_seconds())),
"max_age_seconds": int(DB_MAX_AGE.total_seconds()),
}
def validate_vulnerability(vuln, result_index: int, vuln_index: int) -> None:
prefix = f"report result {result_index} vulnerability {vuln_index}"
if not isinstance(vuln, dict):
raise EvidenceError(f"{prefix} is not a JSON object")
for field in ("VulnerabilityID", "PkgName", "InstalledVersion", "Severity"):
value = vuln.get(field)
if not isinstance(value, str) or not value.strip():
raise EvidenceError(f"{prefix} is missing a non-empty {field}")
severity = vuln["Severity"].strip().upper()
if severity not in ALLOWED_SEVERITIES:
raise EvidenceError(f"{prefix} has an unknown severity {vuln['Severity']!r}")
fixed = vuln.get("FixedVersion")
if fixed is not None and not isinstance(fixed, str):
raise EvidenceError(f"{prefix} has an invalid FixedVersion")
status = vuln.get("Status")
if status is not None and not isinstance(status, str):
raise EvidenceError(f"{prefix} has an invalid Status")
def validate_report(report: dict, expected_image_id: str):
if type(report.get("SchemaVersion")) is not int or report["SchemaVersion"] != 2:
raise EvidenceError("unsupported or missing Trivy SchemaVersion")
if not IMAGE_ID_RE.fullmatch(expected_image_id):
raise EvidenceError("--image-id must be an immutable sha256 image id")
if report.get("ArtifactType") != "container_image":
raise EvidenceError("scan report ArtifactType is not container_image")
metadata = report.get("Metadata")
if not isinstance(metadata, dict):
raise EvidenceError("scan report Metadata is missing")
if metadata.get("ImageID") != expected_image_id:
raise EvidenceError(
f"scan report image id {metadata.get('ImageID')!r} does not match "
f"the expected {expected_image_id!r}"
)
os_meta = metadata.get("OS")
if not isinstance(os_meta, dict):
raise EvidenceError("scan report Metadata.OS is missing")
family = os_meta.get("Family")
if not isinstance(family, str) or not family.strip():
raise EvidenceError("scan report OS family is missing")
name = os_meta.get("Name")
if not isinstance(name, str) or not name.strip():
raise EvidenceError("scan report is missing the OS version name")
results = report.get("Results")
if not isinstance(results, list) or not results:
raise EvidenceError("scan report Results is missing or empty")
trivy_packages: dict[str, str] = {}
os_packages_result = None
for index, result in enumerate(results):
if not isinstance(result, dict):
raise EvidenceError(f"report result {index} is not a JSON object")
packages = result.get("Packages")
if not isinstance(packages, list):
raise EvidenceError(f"report result {index} is missing the Packages list")
for package in packages:
if not isinstance(package, dict):
raise EvidenceError(f"report result {index} has a malformed package")
for field in ("Name", "Version"):
if not isinstance(package.get(field), str) or not package[field].strip():
raise EvidenceError(f"report result {index} package lacks {field}")
vulnerabilities = result.get("Vulnerabilities")
if vulnerabilities is None:
if not packages:
raise EvidenceError(
f"report result {index} has neither packages nor vulnerabilities"
)
elif not isinstance(vulnerabilities, list):
raise EvidenceError(
f"report result {index} has an invalid Vulnerabilities list"
)
else:
for vuln_index, vuln in enumerate(vulnerabilities):
validate_vulnerability(vuln, index, vuln_index)
if str(result.get("Class", "")).strip().lower() == "os-pkgs" and packages:
if result.get("Type") != family.strip().lower():
raise EvidenceError("OS package result does not match the reported OS")
os_packages_result = result
for package in packages:
package_name = package["Name"]
release = package.get("Release", "")
epoch = package.get("Epoch", 0)
if not isinstance(release, str) or type(epoch) is not int or epoch < 0:
raise EvidenceError(f"invalid package version fields for {package_name}")
version = package["Version"]
if release:
version += "-" + release
if epoch:
version = str(epoch) + ":" + version
if package_name in trivy_packages:
raise EvidenceError(f"duplicate OS package: {package_name}")
trivy_packages[package_name] = version
if os_packages_result is None:
raise EvidenceError("scan report has no non-empty OS package inventory")
os_info = {
"family": family.strip().lower(),
"name": name.strip() if isinstance(name, str) else "",
}
return os_info, results, trivy_packages
def is_runtime_os(os_info: dict) -> bool:
return (
os_info.get("family") == RUNTIME_OS_FAMILY
and re.fullmatch(r"12(?:\.\d+)*", str(os_info.get("name", ""))) is not None
)
def normalize_tar_path(name: str):
text = str(name).replace("\\", "/").lstrip("/")
while text.startswith("./"):
text = text[2:]
# Go's tar writer (used by `docker export`) marks directories with a
# trailing slash; strip it before splitting so directory entries normalize.
text = text.rstrip("/")
if text in ("", "."):
return None
parts = text.split("/")
if any(part in ("", ".", "..") for part in parts):
raise EvidenceError(f"docker export contains an unsafe path: {name!r}")
return "/" + "/".join(parts)
def validate_manifest_path(path: str, line_number: int) -> None:
if not path.startswith("/"):
raise EvidenceError(
f"manifest line {line_number} path must be absolute: {path!r}"
)
if "\\" in path or "\x00" in path:
raise EvidenceError(f"manifest line {line_number} path is invalid: {path!r}")
if path == "/" or posixpath.normpath(path) != path:
raise EvidenceError(
f"manifest line {line_number} path is not normalized: {path!r}"
)
for segment in path.split("/")[1:]:
if segment in ("", ".", ".."):
raise EvidenceError(
f"manifest line {line_number} path is not normalized: {path!r}"
)
def parse_manifest(text: str):
entries = []
seen: set[str] = set()
for line_number, raw in enumerate(text.splitlines(), 1):
if raw == "":
continue
fields = raw.split("\t")
if len(fields) != 3:
raise EvidenceError(
f"manifest line {line_number} must have three tab-separated fields"
)
package, path, digest = fields
if not package:
raise EvidenceError(f"manifest line {line_number} has an empty package label")
if package not in ALLOWED_MANIFEST_PACKAGES:
raise EvidenceError(
f"manifest line {line_number} has an unexpected package label "
f"{package!r}"
)
validate_manifest_path(path, line_number)
if path in seen:
raise EvidenceError(f"manifest lists the path more than once: {path}")
seen.add(path)
if not digest:
raise EvidenceError(f"manifest line {line_number} has an empty digest")
entries.append((package, path, digest, SHA256_RE.fullmatch(digest) is not None))
if not entries:
raise EvidenceError("runtime manifest is empty")
if RUNTIME_MANIFEST_PATH in seen:
raise EvidenceError("runtime manifest must not list its own path")
if DPKG_STATUS_PATH in seen:
raise EvidenceError("runtime manifest must not list the dpkg status file")
return entries
def parse_dpkg_status(text: str) -> dict:
packages: dict[str, str] = {}
for block in text.split("\n\n"):
fields: dict[str, str] = {}
for line in block.splitlines():
if not line or line[0] in " \t":
continue
key, separator, value = line.partition(":")
if not separator:
continue
fields[key.strip()] = value.strip()
name = fields.get("Package")
if name:
if name in packages:
raise EvidenceError(f"dpkg status lists {name} more than once")
if fields.get("Status") != "install ok installed" or not fields.get("Version"):
raise EvidenceError(f"dpkg status has invalid installed metadata for {name}")
packages[name] = fields["Version"]
return packages
def _docker_create(image_id: str) -> str:
try:
result = subprocess.run(
["docker", "create", "--entrypoint", "/bin/sh", image_id],
capture_output=True,
text=True,
timeout=DOCKER_TIMEOUT_SECONDS,
)
except (OSError, subprocess.SubprocessError) as error:
raise EvidenceError(f"docker create could not run: {error}") from error
if result.returncode != 0:
detail = result.stderr.strip() or f"exit {result.returncode}"
raise EvidenceError(f"docker create failed for {image_id}: {detail}")
container_id = result.stdout.strip()
if not CONTAINER_ID_RE.fullmatch(container_id):
raise EvidenceError("docker create returned an unexpected container id")
return container_id
def _docker_remove(container_id: str) -> None:
try:
result = subprocess.run(
["docker", "rm", container_id],
capture_output=True,
text=True,
timeout=DOCKER_TIMEOUT_SECONDS,
)
except (OSError, subprocess.SubprocessError) as error:
raise EvidenceError(f"owned export container cleanup failed: {error}") from error
if result.returncode != 0:
raise EvidenceError("owned export container cleanup failed: " + result.stderr.strip())
def _consume_member(member, archive, entries, contents, basenames, counters) -> None:
path = normalize_tar_path(member.name)
if path is None:
return
counters["entries"] += 1
if counters["entries"] > MAX_EXPORT_ENTRIES:
raise EvidenceError("docker export exceeds the entry budget")
basenames.add(posixpath.basename(path))
if path in entries:
raise EvidenceError(f"docker export contains a duplicate path: {path}")
if member.isdir():
entries[path] = ("dir", None)
return
if member.issym():
entries[path] = ("symlink", member.linkname)
return
if member.islnk():
target = normalize_tar_path(member.linkname)
linked = entries.get(target) if target else None
if linked is not None and linked[0] == "file":
entries[path] = ("file", linked[1])
else:
entries[path] = ("hardlink", member.linkname)
return
if not member.isfile():
entries[path] = ("other", None)
return
counters["bytes"] += member.size
if counters["bytes"] > MAX_EXPORT_BYTES:
raise EvidenceError("docker export exceeds the size budget")
hasher = hashlib.sha256()
capture = bytearray() if path in CAPTURED_PATHS else None
stream = archive.extractfile(member)
if stream is None:
raise EvidenceError(f"docker export could not read {path}")
remaining = member.size
with stream:
while remaining > 0:
chunk = stream.read(min(READ_CHUNK_BYTES, remaining))
if not chunk:
raise EvidenceError(f"docker export truncated while reading {path}")
hasher.update(chunk)
remaining -= len(chunk)
if capture is not None:
capture.extend(chunk)
if len(capture) > MAX_SPECIAL_FILE_BYTES:
raise EvidenceError(f"captured file exceeds budget: {path}")
entries[path] = ("file", hasher.hexdigest())
if capture is not None:
contents[path] = bytes(capture)
def _docker_export(container_id: str):
# A file avoids stderr pipe backpressure while the tar stream is consumed.
with tempfile.TemporaryFile() as stderr_file:
try:
process = subprocess.Popen(
["docker", "export", container_id],
stdout=subprocess.PIPE,
stderr=stderr_file,
)
except OSError as error:
raise EvidenceError(f"docker export could not run: {error}") from error
timed_out = threading.Event()
def expire():
if process.poll() is None:
timed_out.set()
try:
process.kill()
except ProcessLookupError:
pass
deadline = threading.Timer(DOCKER_TIMEOUT_SECONDS, expire)
deadline.daemon = True
deadline.start()
entries: dict[str, tuple] = {}
contents: dict[str, bytes] = {}
basenames: set[str] = set()
counters = {"entries": 0, "bytes": 0}
failure = None
try:
if process.stdout is None:
raise EvidenceError("docker export has no output stream")
try:
with tarfile.open(fileobj=process.stdout, mode="r|") as archive:
for member in archive:
_consume_member(member, archive, entries, contents, basenames, counters)
except tarfile.TarError as error:
raise EvidenceError(f"docker export produced an unreadable archive: {error}") from error
except EvidenceError as error:
failure = error
finally:
if process.stdout is not None:
process.stdout.close()
if failure is not None and process.poll() is None:
process.kill()
return_code = process.wait()
deadline.cancel()
deadline.join()
if timed_out.is_set():
raise EvidenceError("docker export timed out")
if failure is not None:
raise failure
if return_code != 0:
stderr_file.seek(0)
detail = stderr_file.read(READ_CHUNK_BYTES).decode("utf-8", "replace").strip()
raise EvidenceError(f"docker export failed for {container_id}: {detail or f'exit {return_code}'}")
return entries, contents, basenames
def read_image(image_id: str):
container_id = _docker_create(image_id)
try:
return _docker_export(container_id)
finally:
_docker_remove(container_id)
def verify_runtime(entries, contents, trivy_packages):
manifest_bytes = contents.get(RUNTIME_MANIFEST_PATH)
if manifest_bytes is None:
raise EvidenceError(f"runtime manifest {RUNTIME_MANIFEST_PATH} is missing")
status_bytes = contents.get(DPKG_STATUS_PATH)
if status_bytes is None:
raise EvidenceError(f"package status {DPKG_STATUS_PATH} is missing")
try:
manifest = parse_manifest(manifest_bytes.decode("utf-8"))
dpkg_packages = parse_dpkg_status(status_bytes.decode("utf-8"))
except UnicodeDecodeError as error:
raise EvidenceError("runtime inventory is not valid UTF-8") from error
unexpected_dpkg = set(dpkg_packages) - set(EXPECTED_PACKAGES)
unexpected_trivy = set(trivy_packages) - set(EXPECTED_PACKAGES)
if unexpected_dpkg or unexpected_trivy:
raise EvidenceError("unexpected runtime packages: " + ", ".join(sorted(unexpected_dpkg | unexpected_trivy)))
for package in EXPECTED_PACKAGES:
if package not in dpkg_packages:
raise EvidenceError(f"dpkg status is missing package {package}")
missing_trivy = [name for name in EXPECTED_PACKAGES if name not in trivy_packages]
if missing_trivy:
raise EvidenceError(
"Trivy OS package inventory is missing: " + ", ".join(missing_trivy)
)
for package in EXPECTED_PACKAGES:
if dpkg_packages[package] != trivy_packages[package]:
raise EvidenceError(f"Trivy/dpkg version mismatch for {package}")
for package, path, digest, is_hash in manifest:
actual = entries.get(path)
if actual is None:
raise EvidenceError(f"manifest file is missing from the image: {path}")
kind, value = actual
if is_hash:
if kind != "file" or value != digest:
raise EvidenceError(f"manifest hash mismatch for {path}")
elif kind != "symlink" or value != digest:
raise EvidenceError(f"manifest symlink mismatch for {path}")
declared = {path for _, path, _, _ in manifest}
undeclared = sorted(path for path, (kind, _) in entries.items()
if kind != "dir" and path not in declared and path not in POST_PACKAGE_FILES)
if undeclared:
raise EvidenceError("undeclared runtime files: " + ", ".join(undeclared[:10]))
return {
"manifest_entries": len(manifest),
"manifest_packages": sorted({entry[0] for entry in manifest}),
"dpkg_packages": len(dpkg_packages),
"trivy_packages": len(trivy_packages),
"manifest_verified": True,
}, dpkg_packages
def _is_excepted(vuln, os_info, infocmp_present, ncurses_bin_present, actual_version) -> bool:
if vuln["VulnerabilityID"] != EXPECTED_CVE:
return False
if vuln["PkgName"] != EXCEPTED_PACKAGE:
return False
if vuln["InstalledVersion"] != EXCEPTED_VERSION:
return False
if actual_version != EXCEPTED_VERSION:
return False
if not is_runtime_os(os_info):
return False
if infocmp_present is not False:
return False
if ncurses_bin_present is not False:
return False
return True
def evaluate_findings(results, os_info, basenames, dpkg_packages, image_id):
counts = {severity: 0 for severity in ALLOWED_SEVERITIES}
high_critical = []
blocking = []
exceptions = []
infocmp_present = "infocmp" in basenames if basenames is not None else None
ncurses_bin_present = (
"ncurses-bin" in dpkg_packages if dpkg_packages is not None else None
)
for result in results:
target = result.get("Target", "")
for vuln in result.get("Vulnerabilities", []) or []:
severity = vuln["Severity"].strip().upper()
counts[severity] += 1
if severity not in BLOCKING_SEVERITIES:
continue
record = {
"vulnerability_id": vuln["VulnerabilityID"],
"package": vuln["PkgName"],
"installed_version": vuln["InstalledVersion"],
"fixed_version": vuln.get("FixedVersion") or None,
"severity": severity,
"status": vuln.get("Status") or None,
"target": target,
}
actual_version = dpkg_packages.get(EXCEPTED_PACKAGE) if dpkg_packages else None
if _is_excepted(vuln, os_info, infocmp_present, ncurses_bin_present, actual_version):
record["disposition"] = "excepted"
high_critical.append(record)
exceptions.append(
{
"vulnerability_id": vuln["VulnerabilityID"],
"package": vuln["PkgName"],
"installed_version": vuln["InstalledVersion"],
"severity": severity,
"image_id": image_id,
"justification": EXCEPTION_JUSTIFICATION,
}
)
else:
record["disposition"] = "blocked"
high_critical.append(record)
blocking.append(record)
return {
"severity_counts": {severity: counts[severity] for severity in sorted(counts)},
"high_critical": high_critical,
"blocking": blocking,
"exceptions": exceptions,
}
def _sha256_file(path: Path) -> str:
hasher = hashlib.sha256()
with path.open("rb") as stream:
while True:
chunk = stream.read(READ_CHUNK_BYTES)
if not chunk:
break
hasher.update(chunk)
return hasher.hexdigest()
def _assert_distinct(decision_path: Path, report_path: Path, db_path: Path) -> None:
protected = {report_path.resolve(), db_path.resolve()}
if decision_path.resolve() in protected:
raise EvidenceError(
"--decision must not overwrite the raw report or DB metadata"
)
def compute(decision: dict, args: argparse.Namespace) -> None:
report_path = Path(args.report)
db_path = Path(args.db_metadata)
decision_path = Path(args.decision)
_assert_distinct(decision_path, report_path, db_path)
now = datetime.now(timezone.utc)
decision["db_metadata"] = load_db_metadata(db_path, now)
report = load_json(report_path, MAX_REPORT_BYTES, "scan report")
decision["report_sha256"] = _sha256_file(report_path)
os_info, results, trivy_packages = validate_report(report, args.image_id)
decision["os"] = os_info
decision["artifact_type"] = "container_image"
basenames = None
dpkg_packages = None
if is_runtime_os(os_info):
entries, contents, basenames = read_image(args.image_id)
runtime_summary, dpkg_packages = verify_runtime(
entries, contents, trivy_packages
)
runtime_summary["image_files"] = len(entries)
decision["runtime_inventory"] = runtime_summary
decision.update(
evaluate_findings(results, os_info, basenames, dpkg_packages, args.image_id)
)
def write_decision(path: Path, decision: dict) -> None:
payload = json.dumps(decision, indent=2, sort_keys=True) + "\n"
directory = str(path.parent) if str(path.parent) else "."
descriptor, temporary = tempfile.mkstemp(prefix=".decision-", dir=directory)
try:
with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
stream.write(payload)
os.replace(temporary, path)
except OSError:
try:
os.unlink(temporary)
except OSError:
pass
raise
def base_decision(args: argparse.Namespace) -> dict:
return {
"schema": "crank.image-scan.decision.v1",
"image_id": args.image_id,
"report_path": str(args.report),
"db_metadata_path": str(args.db_metadata),
"status": "error",
"exit_code": 2,
"errors": [],
}
def main(argv=None) -> int:
args = parse_args(sys.argv[1:] if argv is None else argv)
# An unsafe output path must be rejected before any error receipt is written.
try:
_assert_distinct(Path(args.decision), Path(args.report), Path(args.db_metadata))
except EvidenceError as error:
print(f"image scan gate: evidence failure: {error}", file=sys.stderr)
return 2
decision = base_decision(args)
try:
compute(decision, args)
except EvidenceError as error:
decision["status"] = "error"
decision["exit_code"] = 2
decision["errors"].append(str(error))
try:
write_decision(Path(args.decision), decision)
except OSError as write_error:
print(
f"image scan gate: cannot write decision: {write_error}",
file=sys.stderr,
)
return 2
print(f"image scan gate: evidence failure: {error}", file=sys.stderr)
return 2
blocking = decision.get("blocking", [])
if blocking:
decision["status"] = "blocked"
decision["exit_code"] = 1
else:
decision["status"] = "pass"
decision["exit_code"] = 0
try:
write_decision(Path(args.decision), decision)
except OSError as error:
print(f"image scan gate: cannot write decision: {error}", file=sys.stderr)
return 2
print(
"image scan gate: {status} ({blocked} blocking, {excepted} excepted)".format(
status=decision["status"],
blocked=len(blocking),
excepted=len(decision.get("exceptions", [])),
)
)
return decision["exit_code"]
if __name__ == "__main__":
raise SystemExit(main())
+169
View File
@@ -0,0 +1,169 @@
#!/bin/sh
# Assemble the minimal Debian runtime rootfs used by the Crank server images.
#
# The final admin-api and mcp-server images are built `FROM scratch`; this
# script runs inside the Debian package stage before the rootfs is copied into
# the scratch image. It transfers only the files owned by an explicit package
# allowlist plus three GNU coreutils programs and their copyright. No apt,
# libacl, GNU gzip, infocmp, util-linux or BusyBox files are copied.
#
# Merged-/usr: Debian exposes /bin, /sbin and /lib as symlinks into /usr. The
# package file lists still name the legacy paths (for example /bin/bash or
# /lib/x86_64-linux-gnu/libc.so.6). Before every copy the parent directory is
# resolved through those symlinks (readlink -f on the dirname only), so regular
# files and library symlinks land in their real /usr locations while the
# top-level directory symlinks (/bin -> usr/bin, /lib -> usr/lib,
# /lib64 -> usr/lib64) and file symlinks (for example /usr/bin/sh -> dash) are
# preserved unchanged.
#
# Inventory: /usr/share/crank/runtime-inventory.tsv is a tab-separated manifest
# with one row per file placed in the rootfs by this script:
#
# package<TAB>normalized absolute path<TAB>sha256 for regular files or the
# symlink target for symlinks
#
# Files generated here instead of shipped by a package use the synthetic
# package label `runtime-generated`. The scan stage cross-checks this manifest
# against the real image instead of trusting Trivy alone. The manifest path is
# fixed and cannot be overridden.
set -eu
dest="${1:-/runtime}"
case "$dest" in
/*) ;;
*)
echo "runtime rootfs destination must be an absolute path: $dest" >&2
exit 64
;;
esac
# Packages kept in the runtime image. Versions are recorded in dpkg/status.
# gcc-12-base supplies the copyright target of libgcc-s1; retaining its
# package-owned documentation preserves the license and its source version.
packages="base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils"
# shellcheck disable=SC2086
set -- $packages
expected_packages="$#"
set --
# GNU coreutils is installed only so apt resolves dependencies honestly; of the
# whole package just these files are transferred. install/cp/mv are deliberately
# left out because they pull in libacl.
coreutils_files="/bin/mkdir /bin/chmod /usr/bin/env /usr/share/doc/coreutils/copyright"
mkdir -p \
"$dest/usr/local/bin" \
"$dest/var/lib/dpkg" \
"$dest/etc" \
"$dest/tmp" \
"$dest/run/lock" \
"$dest/usr/share/crank"
# A world-writable sticky /tmp and the run-state directories match the FHS and
# the previous slim image. /run and /run/lock also give the base-files
# /var/run and /var/lock symlinks valid targets.
chmod 1777 "$dest/tmp"
chmod 0755 "$dest/run"
chmod 1777 "$dest/run/lock"
status="$dest/var/lib/dpkg/status"
inventory="$dest/usr/share/crank/runtime-inventory.tsv"
: > "$status"
: > "$inventory"
for package in $packages; do
version="$(dpkg-query -W -f='${Version}' "$package")"
printf 'runtime-package: %s %s\n' "$package" "$version"
# dpkg/status paragraph, separated from the next one by a blank line.
dpkg-query -s "$package" >> "$status"
printf '\n' >> "$status"
# shellcheck disable=SC2086
for source in $(dpkg-query -L "$package"); do
if [ "$package" = "coreutils" ]; then
allowed=0
# shellcheck disable=SC2086
for candidate in $coreutils_files; do
if [ "$source" = "$candidate" ]; then
allowed=1
break
fi
done
[ "$allowed" -eq 1 ] || continue
fi
if [ ! -f "$source" ] && [ ! -L "$source" ]; then
continue
fi
directory="$(readlink -f "$(dirname -- "$source")")"
base="$(basename -- "$source")"
if [ "$directory" = "/" ]; then
path="/$base"
parent="$dest"
else
path="$directory/$base"
parent="$dest$directory"
fi
# Several packages list the same merged-/usr symlink; keep the first
# copy and skip duplicates so the manifest has one row per path.
if [ -e "$dest$path" ] || [ -L "$dest$path" ]; then
continue
fi
mkdir -p "$parent"
cp -a --no-target-directory -- "$source" "$dest$path"
if [ -L "$source" ]; then
digest="$(readlink -- "$source")"
else
digest="$(sha256sum -- "$source")"
digest="${digest%% *}"
fi
printf '%s\t%s\t%s\n' "$package" "$path" "$digest" >> "$inventory"
done
done
# Docker mounts /etc/hosts and /etc/resolv.conf, but the image still needs the
# root account and a name-service switch policy. `hosts: files dns` is required
# for getaddrinfo to fall back to DNS for outbound requests.
printf 'root:x:0:0:root:/root:/bin/sh\n' > "$dest/etc/passwd"
printf 'root:x:0:\n' > "$dest/etc/group"
printf 'passwd: files\ngroup: files\nhosts: files dns\n' > "$dest/etc/nsswitch.conf"
for generated in /etc/passwd /etc/group /etc/nsswitch.conf; do
digest="$(sha256sum -- "$dest$generated")"
digest="${digest%% *}"
printf 'runtime-generated\t%s\t%s\n' "$generated" "$digest" >> "$inventory"
done
count="$(grep -c '^Package: ' "$status")"
if [ "$count" -ne "$expected_packages" ]; then
echo "dpkg status holds $count packages, expected $expected_packages" >&2
exit 1
fi
# Merged-/usr and shell-entrypoint contracts must hold in the assembled rootfs.
for link in bin lib lib64 sbin; do
if [ ! -L "$dest/$link" ]; then
echo "merged-/usr symlink /$link missing from runtime rootfs" >&2
exit 1
fi
done
for exe in usr/bin/sh usr/bin/mkdir usr/bin/chmod usr/bin/env usr/bin/bash; do
if [ ! -x "$dest/$exe" ]; then
echo "runtime shell or coreutils subset missing: /$exe" >&2
exit 1
fi
done
if [ "$(grep -c . "$inventory")" -eq 0 ]; then
echo "runtime inventory is empty" >&2
exit 1
fi
printf 'runtime-inventory: %s files\n' "$(grep -c . "$inventory")"
+289 -11
View File
@@ -1,4 +1,30 @@
#!/bin/sh
# Scan the built Crank server images with a pinned Trivy and fail closed.
#
# The wrapper downloads and checksum-verifies one fixed Trivy release, downloads
# one fresh vulnerability database, then scans every requested image by its
# immutable Docker id with a fully pinned policy. It never trusts a local
# trivy.yaml, .trivyignore, VEX file or skip list: --config and --ignorefile
# point at /dev/null and every inherited TRIVY_* variable is removed before
# Trivy runs. Docker context and proxy variables are preserved.
#
# Artifacts are written to the evidence directory (default
# .tmp/image-scan-evidence, relocatable only through CRANK_IMAGE_SCAN_OUTPUT_DIR)
# and are kept even when the gate is red:
#
# db/metadata.json copy of the actual downloaded Trivy DB metadata
# db-download.log database download log
# scanner.json pinned scanner version and scan policy receipt
# <NN-slug>.json raw Trivy JSON report per image
# <NN-slug>.scan.log Trivy scan log per image
# <NN-slug>.gate.log checker output per image
# <NN-slug>.decision.json checker decision per image
# receipt.json aggregate tag<->immutable id<->raw<->decision receipt
#
# Every scan is finished by the accepted checker (scripts/check-image-scan.py),
# which owns the PASS/BLOCKED/ERROR decision and the DB-age check. The wrapper
# exits 0 only when every image passed, 1 when at least one image is blocked and
# 2 on any bootstrap, scan or evidence error.
set -eu
if [ "$#" -eq 0 ]; then
@@ -6,24 +32,276 @@ if [ "$#" -eq 0 ]; then
exit 2
fi
# Strip inherited TRIVY_* overrides so neither the environment nor a local Trivy
# config can loosen the policy. Only names are read; no values are logged.
for name in $(env | sed -n 's/^\(TRIVY_[A-Za-z0-9_]*\)=.*/\1/p'); do
unset "$name"
done
script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
checker="$script_dir/check-image-scan.py"
trivy_version="0.70.0"
archive="trivy_${trivy_version}_Linux-64bit.tar.gz"
expected_sha256="8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9"
download_url="https://github.com/aquasecurity/trivy/releases/download/v${trivy_version}/${archive}"
output_dir="${CRANK_IMAGE_SCAN_OUTPUT_DIR:-.tmp/image-scan-evidence}"
if ! mkdir -p "$output_dir"; then
echo "scan-images: cannot create evidence directory $output_dir" >&2
exit 2
fi
if ! output_dir="$(CDPATH= cd -- "$output_dir" && pwd)"; then
echo "scan-images: cannot resolve evidence directory $output_dir" >&2
exit 2
fi
# Each invocation owns a fresh artifact directory. An absent new report can
# never be mistaken for a successful report left by a previous invocation.
if ! output_dir="$(mktemp -d "$output_dir/run.XXXXXX")"; then
echo "scan-images: cannot create a fresh evidence run directory" >&2
exit 2
fi
temp_dir="$(mktemp -d)"
trap 'rm -rf "$temp_dir"' EXIT HUP INT TERM
cache_dir="$temp_dir/trivy-cache"
mkdir -p "$cache_dir"
cleanup() { rm -rf "$temp_dir"; }
trap cleanup EXIT HUP INT TERM
curl --fail --silent --show-error --location \
"https://github.com/aquasecurity/trivy/releases/download/v${trivy_version}/${archive}" \
--output "$temp_dir/$archive"
printf '%s %s\n' "$expected_sha256" "$temp_dir/$archive" | sha256sum --check --status
tar -C "$temp_dir" -xzf "$temp_dir/$archive" trivy
requested="$temp_dir/requested-images.txt"
printf '%s\n' "$@" > "$requested"
records="$temp_dir/records.jsonl"
: > "$records"
# Bootstrap failures still produce a receipt naming every requested image.
fail_all() {
reason="$1"
python3 - "$output_dir/receipt.json" "$reason" "$requested" <<'PY'
import json
import sys
receipt_path, reason, requested_path = sys.argv[1:4]
with open(requested_path, encoding="utf-8") as stream:
images = [line for line in stream.read().splitlines() if line]
receipt = {
"schema": "crank.image-scan.receipt.v1",
"error": reason,
"overall": {"status": "error", "exit_code": 2},
"images": [
{"index": index + 1, "tag": tag, "status": "error", "error": reason}
for index, tag in enumerate(images)
],
}
with open(receipt_path, "w", encoding="utf-8") as stream:
json.dump(receipt, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
echo "scan-images: $reason" >&2
exit 2
}
# Download and checksum-verify the pinned scanner exactly once.
if ! curl --fail --silent --show-error --location --max-time 300 \
"$download_url" --output "$temp_dir/$archive" \
>"$output_dir/scanner-download.log" 2>&1; then
fail_all "could not download pinned Trivy ${trivy_version}"
fi
if ! printf '%s %s\n' "$expected_sha256" "$temp_dir/$archive" \
| sha256sum --check --status; then
fail_all "pinned Trivy archive checksum mismatch"
fi
trivy_bin="$temp_dir/trivy"
if ! tar -C "$temp_dir" -xzf "$temp_dir/$archive" trivy; then
fail_all "could not extract the pinned Trivy archive"
fi
if [ ! -x "$trivy_bin" ]; then
fail_all "pinned Trivy executable is missing after extraction"
fi
# Download one fresh vulnerability database; every scan reuses it read-only.
if ! "$trivy_bin" image --config /dev/null --download-db-only --cache-dir "$cache_dir" \
--no-progress --skip-version-check \
>"$output_dir/db-download.log" 2>&1; then
fail_all "could not download the Trivy vulnerability database"
fi
db_metadata="$output_dir/db/metadata.json"
mkdir -p "$output_dir/db"
if ! cp "$cache_dir/db/metadata.json" "$db_metadata"; then
fail_all "Trivy database metadata was not produced"
fi
if ! version_output="$("$trivy_bin" --config /dev/null --cache-dir "$cache_dir" --version 2>&1)"; then
fail_all "could not read pinned Trivy version"
fi
reported_version="$(printf '%s\n' "$version_output" | sed -n 's/^Version:[[:space:]]*//p' | head -n 1)"
if [ "$reported_version" != "$trivy_version" ]; then
fail_all "pinned Trivy reported an unexpected version"
fi
python3 - "$output_dir/scanner.json" "$trivy_version" "$expected_sha256" \
"$archive" "$version_output" <<'PY'
import json
import sys
path, expected, digest, archive, reported = sys.argv[1:6]
reported_version = next(
(line.strip() for line in reported.splitlines() if line.strip()), ""
)
payload = {
"schema": "crank.image-scan.scanner.v1",
"expected_version": expected,
"reported_version": reported_version,
"archive": archive,
"archive_sha256": digest,
"policy": {
"image_source": "docker",
"config": "/dev/null",
"ignorefile": "/dev/null",
"ignore_unfixed": False,
"list_all_pkgs": True,
"severities": ["UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL"],
"scanners": ["vuln"],
"skip_db_update": True,
"skip_version_check": True,
},
}
with open(path, "w", encoding="utf-8") as stream:
json.dump(payload, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
overall_rc=0
index=0
for image in "$@"; do
"$temp_dir/trivy" image \
--exit-code 1 \
--ignore-unfixed \
--severity HIGH,CRITICAL \
index=$((index + 1))
slug="$(printf '%s' "$image" \
| sed 's/[^A-Za-z0-9._-]/_/g; s/^[.-]*//; s/[.-]*$//' \
| cut -c1-80)"
[ -n "$slug" ] || slug="image"
base="$(printf '%02d' "$index")-$slug"
raw="$output_dir/$base.json"
scan_log="$output_dir/$base.scan.log"
gate_log="$output_dir/$base.gate.log"
decision="$output_dir/$base.decision.json"
image_id="$(docker image inspect --format '{{.Id}}' "$image" \
2>"$output_dir/$base.inspect.log" || true)"
image_id="$(printf '%s' "$image_id" | tr -d '[:space:]')"
scan_rc=0
if [ -z "$image_id" ]; then
scan_rc=2
printf 'scan-images: cannot resolve an immutable id for %s\n' "$image" >&2
elif "$trivy_bin" image \
--image-src docker \
--config /dev/null \
--ignorefile /dev/null \
--ignore-unfixed=false \
--list-all-pkgs=true \
--severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL \
--scanners vuln \
--format json \
--exit-code 0 \
--skip-db-update \
--cache-dir "$cache_dir" \
--no-progress \
"$image"
--skip-version-check \
--output "$raw" \
"$image_id" >"$scan_log" 2>&1; then
scan_rc=0
else
scan_rc=$?
fi
# The checker is always invoked so every image gets a decision artifact,
# even when the scan itself failed. Missing or malformed evidence is
# reported by the checker itself with exit code 2.
if gate_output="$(python3 "$checker" \
--report "$raw" \
--image-id "$image_id" \
--db-metadata "$db_metadata" \
--decision "$decision" 2>&1)"; then
gate_rc=0
else
gate_rc=$?
fi
printf '%s\n' "$gate_output" >"$gate_log"
printf '%s\n' "$gate_output"
effective_rc="$gate_rc"
if [ "$scan_rc" -ne 0 ] && [ "$effective_rc" -lt 2 ]; then
effective_rc=2
fi
if [ "$effective_rc" -gt "$overall_rc" ]; then
overall_rc="$effective_rc"
fi
case "$effective_rc" in
0) status="pass" ;;
1) status="blocked" ;;
*) status="error" ;;
esac
python3 - "$records" "$index" "$image" "$image_id" "$raw" "$scan_log" \
"$gate_log" "$decision" "$scan_rc" "$gate_rc" "$status" <<'PY'
import json
import sys
(
records_path, index, tag, image_id, raw, scan_log, gate_log, decision,
scan_exit, gate_exit, status,
) = sys.argv[1:12]
record = {
"index": int(index),
"tag": tag,
"image_id": image_id or None,
"raw": raw,
"scan_log": scan_log,
"gate_log": gate_log,
"decision": decision,
"scan_exit": int(scan_exit),
"gate_exit": int(gate_exit),
"status": status,
}
with open(records_path, "a", encoding="utf-8") as stream:
stream.write(json.dumps(record) + "\n")
PY
done
case "$overall_rc" in
0) overall_status="pass" ;;
1) overall_status="blocked" ;;
*) overall_status="error" ;;
esac
python3 - "$records" "$output_dir/receipt.json" "$db_metadata" \
"$output_dir/scanner.json" "$overall_rc" "$overall_status" "$output_dir" <<'PY'
import json
import sys
records_path, receipt_path, db_path, scanner_path, exit_code, status, out_dir = (
sys.argv[1:8]
)
with open(records_path, encoding="utf-8") as stream:
images = [json.loads(line) for line in stream if line.strip()]
with open(scanner_path, encoding="utf-8") as stream:
scanner = json.load(stream)
with open(db_path, encoding="utf-8") as stream:
db_metadata = json.load(stream)
receipt = {
"schema": "crank.image-scan.receipt.v1",
"output_dir": out_dir,
"scanner": scanner,
"database": {
"metadata_path": db_path,
"updated_at": db_metadata.get("UpdatedAt"),
},
"overall": {"status": status, "exit_code": int(exit_code)},
"images": images,
}
with open(receipt_path, "w", encoding="utf-8") as stream:
json.dump(receipt, stream, indent=2, sort_keys=True)
stream.write("\n")
PY
printf 'scan-images: %s (%s/receipt.json)\n' "$overall_status" "$output_dir"
exit "$overall_rc"
+777
View File
@@ -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()
+462
View File
@@ -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()