# Сканирование образов и минимальный runtime Документ описывает, как устроены конечные серверные образы Crank, как сокращён состав окружения и как CI блокирует неподтверждённые результаты проверки. Он относится к одной конкретной проблеме безопасности и **не закрывает оставшиеся NFR-риски**: это только часть работы, а не полное подтверждение соответствия NFR. ## Минимальный runtime `admin-api` и `mcp-server` собираются `FROM scratch`: в финальный слой попадает не Debian slim, а заранее собранный минимальный rootfs. Его формирует `scripts/prepare-runtime-rootfs.sh` во время package stage Dockerfile (`apps/admin-api/Dockerfile`, `apps/mcp-server/Dockerfile`). В rootfs переносятся только файлы явного allowlist-набора из **десяти** Debian пакетов: ```text base-files libc6 libgcc-s1 gcc-12-base bash dash libtinfo6 libselinux1 libpcre2-8-0 coreutils ``` - `gcc-12-base` добавлен, чтобы copyright-файл, на который ссылается `libgcc-s1`, существовал вместе со своим пакетом-владельцем. - От `coreutils` переносятся только `mkdir`, `chmod`, `env` и их copyright. Полный GNU coreutils, `apt`, `libacl`, GNU `gzip`, `util-linux`, `infocmp` и BusyBox сознательно не попадают в образ. - Сохраняются Rust 1.96.1/glibc, CA-сертификаты, мигратор, порты, readiness, shell healthcheck, cold storage-init с правами 0700 и проверки путей. ### Учёт файлов и лицензии Вместе с файлами rootfs создаётся проверяемая опись: - `/usr/share/crank/runtime-inventory.tsv` — TSV из трёх колонок: `packagenormalized absolute pathsha256` для обычного файла либо target симлинка. Сгенерированные самим helper-ом файлы (`/etc/passwd`, `/etc/group`, `/etc/nsswitch.conf`) помечены синтетическим пакетом `runtime-generated`. Путь фиксирован и не настраивается. - `/var/lib/dpkg/status` — десять параграфов с реальными версиями пакетов. Сам файл и inventory в TSV намеренно не перечисляются. - Лицензии ориентируются на фактические `copyright`-файлы перенесённых пакетов; версия каждого пакета берётся из dpkg, а не из внешнего списка. Инвентарь содержит около 355 записей и проверяется не по декларации, а по реальному immutable образу (см. ниже). ## Что делает обёртка сканирования `scripts/scan-images.sh IMAGE [IMAGE ...]` — единственная точка входа для CI: 1. Однократно скачивает и проверяет по SHA256 зафиксированную версию Trivy 0.70.0 (`8b4376d5d6befe5c24d503f10ff136d9e0c49f9127a4279fd110b727929a5aa9`). 2. Однократно скачивает свежую vulnerability DB в изолированный cache. 3. Для каждого образа получает immutable id через `docker image inspect` и сканирует **именно id**, а не тег. 4. Завершает каждый скан вызовом checker: `scripts/check-image-scan.py --report ... --image-id ... --db-metadata ... --decision ...`. Политика сканирования жёстко зашита и не читает локальную конфигурацию: ```text --image-src docker --config /dev/null --ignorefile /dev/null --ignore-unfixed=false --list-all-pkgs=true --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL --scanners vuln --format json --exit-code 0 --skip-db-update --cache-dir --no-progress --skip-version-check ``` Перед запуском Trivy обёртка удаляет все унаследованные переменные `TRIVY_*` (имена читаются, значения не логируются), поэтому окружение не может подменить severity, config, ignorefile, skip-files или VEX. Наследуемые Docker context и proxy-переменные сохраняются. ## Артефакты и коды выхода Результаты каждого запуска сохраняются в отдельном каталоге `.tmp/image-scan-evidence/run.XXXXXX` (расположение можно изменить только переменной `CRANK_IMAGE_SCAN_OUTPUT_DIR`, не фильтрами) и **сохраняются даже при красном результате**: ```text db/metadata.json копия фактических метаданных Trivy DB db-download.log лог загрузки базы scanner.json версия сканера и применённая политика .json сырой JSON-отчёт Trivy по образу .scan.log лог сканирования .gate.log вывод checker .decision.json решение checker по образу receipt.json агрегированная квитанция tag<->immutable id<->raw<->decision ``` Сырой отчёт никогда не перезаписывается решением. Коды выхода: - `0` — PASS: все образы прошли, неразрешённых High/Critical нет. - `1` — BLOCKED: есть High/Critical без точечного обоснованного исключения. - `2` — ERROR: bootstrap/скан/evidence неполны, испорчены, просрочены или не совпадают с реальным образом. Обёртка не останавливается на красном образе и обрабатывает оставшиеся; итоговый код ненулевой, если хотя бы один образ не PASS. Сбой загрузки сканера или базы также даёт ненулевой код и error-квитанцию для каждого запрошенного образа. ## Единственное исключение Проверяющий скрипт допускает только одну конкретную неприменимую находку и только при одновременном выполнении всех условий: - CVE — `CVE-2025-69720`; - пакет — `libtinfo6`, `InstalledVersion == 6.4-4`; - дистрибутив — Debian 12; - реальная версия `libtinfo6` в dpkg/status — `6.4-4`; - `infocmp` отсутствует среди **всех** basename экспортированного образа; - `ncurses-bin` отсутствует в dpkg/status. Уязвимость относится к front-end `infocmp` из ncurses, поэтому проверяется не только имя/версия из отчёта Trivy, но и фактическая файловая система и dpkg/status реального immutable образа. Любое другое имя, версия, дистрибутив или наличие `infocmp`/`ncurses-bin` запрещает исключение и блокирует сборку. Исходная находка остаётся в отчёте; в decision попадают `justification` и `image_id`. Первичный источник: Debian Security Tracker — . Предыдущий разбор применимости CVE и доказательства сохранены в [задаче Gitea #92](https://git.itexp.me/bsodfather/crank/issues/92). ## Почему fail-closed - Отсутствие `Results`, `Packages` или целого отчёта не считается «пустым корректным» результатом: это ошибка evidence, а не PASS. - `Metadata.ImageID` обязан точно совпадать с immutable id, а OS, DB `UpdatedAt` и версии пакетов сверяются с реальностью. - DB старше 24 часов или из будущего более чем на 5 минут отклоняется. - Отсутствие `infocmp` берётся из реального экспорта, а не из самого Trivy отчёта: отчёту нельзя доверять в этом вопросе. - Любая ошибка docker/tar/IO трактуется как отказ. ## Повторная проверка Воспроизвести контроль локально: ```sh scripts/scan-images.sh crank/admin-api:ci crank/mcp-server:ci crank/ui:ci python3 -m unittest discover -s tests/unit -p 'test_scan_images.py' python3 -m unittest discover -s tests/unit -p 'test_check_image_scan.py' ``` Решение по каждому образу — в `.decision.json`, агрегированный итог и связь тега с immutable id и артефактивами — в `receipt.json`. В CI полные результаты публикуются отдельными artifact-ами даже при красном gate (`image-scan-evidence` в Community Image Smoke и `deploy-image-scan-evidence` в Deploy). ## Границы Документ не утверждает, что все NFR выполнены. Остальные CONCERNS, не относящиеся к перечню уязвимых компонентов и скрывающему фильтру CI, остаются открытыми и проверяются отдельно.