Files
crank/docs/security/image-scanning.md
T
bsodfather f685616ae8
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
fix(security): minimize runtime images and enforce complete vulnerability scans
2026-10-10 01:41:38 +03:00

160 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Сканирование образов и минимальный 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, остаются
открытыми и проверяются отдельно.