160 lines
10 KiB
Markdown
160 lines
10 KiB
Markdown
# Сканирование образов и минимальный 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, остаются
|
||
открытыми и проверяются отдельно.
|