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

+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, остаются
открытыми и проверяются отдельно.