Русский | English
Система анализа безопасности (вредоносности) моделей и данных, используемых в ML/AI.
Проект отвечает на вопрос: безопасен ли конкретный ML/AI-артефакт, и что в нём опасного — исполняемый при загрузке код, закладки, утечки данных, неконтролируемое поведение, проблемы целостности и происхождения.
Стартовая статья (фокус, история, ссылки) —
START.md. Детальная техническая документация —docs/.
Развёрнута v3-система целиком: UI за Keycloak (OIDC) — https://mlscan.platform.rtx.local,
сервис тестирования, аналитика, интеграции (CI-gate), ops (метрики), PostgreSQL, S3 (Ceph RGW,
s3.platform.rtx.local), песочница t-mlscan-sandbox (Kata для сканов; GPU-инференс на RTX 4000).
Что актуально (сверх v2-стенда, описанного ниже):
- LLM-инференс как недоверенный движок по digest:
vLLM/SGLang/llama.cpp; связка «модель + движок + версии» фиксируется как bundle, вердикт bundle + аттестация + CI-gate. - Загрузка целых каталогов с HF: для vLLM/SGLang скачивается весь репозиторий (config/tokenizer/все
шарды); одиночный
.safetensorsиз HF автоматически догружается до полного каталога при тесте. - Полный набор вопросов (активный набор — 726 вопросов) через S3 (сняты лимиты env/ConfigMap); в «Администрировании» виден размер набора и текст предупреждений XLSX-импорта.
- SGLang 0.5.9 на Turing (sm_75) — работает на RTX 4000 через runtime-shim (
sgl-shim): torch-реализации RMSNorm/SiLU +torch_native/pytorch; для Ampere+ шим не нужен. - Job LLM-теста сам удаляется после вердикта (освобождение GPU); вердикт инференса отражается и в карточке артефакта.
- S3 — Ceph RGW; Garage выведен; oauth2-proxy устойчив к временной недоступности Keycloak.
Сквозное описание процессов, sequence-диаграммы и области наблюдения / открытые зоны и проблемы ИБ —
CrossProcess_overview.md. Статус развёртывания и процедуры —
deploy/tenant/STATUS.md.
Проект развивался инкрементально: от проверки одного формата к платформе, способной проверять произвольные ML/AI-артефакты — включая очень большие — в изолированной среде.
| Этап | Что появилось | Ключевая идея |
|---|---|---|
| 0. PoC | Один файл poc/mlscan_poc.py: статика + динамика в Docker + поведение → Markdown |
Проверить, что pickle-модель можно анализировать тремя независимыми методами |
| 1. Песочница | Kata-микро-ВМ, deception, sinkhole, NetworkPolicy, Falco | Модель = исполняемый код → запускать только в изоляции с наблюдением |
| 2. Сервис тестирования | Приём артефактов, запуск песочницы, нормализация находок, вердикт | Отделить анализ от процесса загрузки, сделать его сервисом |
| 3. Аналитика + UI | Скоринг, Policy Engine, append-only Evidence Store (hash-chain), отчёты, веб-UI | Единая точка управления, доказательная база и заключение |
| 4. Интеграции | Model Registry (SHA-256), CI/CD gate, SIEM-экспорт (NDJSON/CEF), threat-intel | Встроить проверку в конвейеры поставки |
| 5. Эксплуатация | Метрики, метрики качества (TPR/FPR), retest, red-team, PDB, аттестация | Промышленный контур: контроль качества и непрерывность |
| v2 — Волна 0 | S3-хранилище (Garage), PostgreSQL, AuthN/Z + audit, наблюдаемость + бэкап | Снять ограничения по размеру и обеспечить аудит/отслеживаемость |
| v2 — Волны 1–3 | Адаптеры форматов и детекторы (model-as-code, Keras, ONNX, HDF5, GGUF, архивы, XXE, токенизаторы, prompt-injection, agent/MCP), динамика model-as-code, retention/TTL | Расширение за пределы pickle без пересборки ядра |
flowchart LR
P["PoC<br/>1 формат, 1 файл"] --> S["Система для pickle<br/>3 компоненты (Этапы 0-5)"]
S --> V0["v2 Волна 0<br/>S3, PostgreSQL, AuthN/Z, audit"]
V0 --> V1["v2 Волны 1-7<br/>адаптеры форматов, детекторы, lifecycle"]
V1 --> T["Синтетический корпус<br/>87/87 обнаружено, 0 FP"]
Система разворачивается поэтапно: каждый уровень самодостаточен (полностью работоспособен
в рамках своих возможностей анализа), следующий только добавляет возможности и компоненты, а
незавершённость никогда не маскируется — если модуль не смог отработать, вердикт Inconclusive
с частичным результатом. Остановиться можно на любом уровне.
План и аргументация — docs/13-deployment-plan.md,
выбор уровня — deploy/README.md,
переход на следующий — deploy/upgrade.md.
flowchart LR
L0["Уровень 0 · PoC<br/>Python + Docker<br/>статика по всем форматам,<br/>динамика и поведение в Docker"]
L1["Уровень 1 · Песочница<br/>Kata microVM, сетевой запрет,<br/>honeypot; опц. Falco/eBPF"]
L2["Уровень 2 · Сервис тестирования<br/>HTTP, S3 sha256, PostgreSQL,<br/>большие файлы, дедупликация"]
L3["Уровень 3 · Аналитика и UI<br/>policy, evidence hash-chain,<br/>вход и роли, RU/EN"]
L4["Уровень 4 · Интеграции<br/>реестр, CI-gate, SIEM"]
L5["Уровень 5 · Эксплуатация<br/>метрики, TPR/FPR, retest,<br/>TTL/карантин, backup"]
L0 --> L1 --> L2 --> L3 --> L4 --> L5
| Ур. | Что даёт (анализ и сервис) | Что требует | Установка · проверка |
|---|---|---|---|
| 0 | PoC: статика по всем форматам (pickle/torch/numpy, SafeTensors, ONNX, HDF5/Keras, GGUF, архивы, ноутбуки, скрипты, конфиги/карточки, MCP, HTML/SVG, Dockerfile, датасеты, сжатые payload'ы), динамика L2 и поведение L3 в Docker, отчёт MD/JSON | Python 3.10+, Docker (только для динамики) | bash deploy/install.sh 0 · bash deploy/verify.sh 0 |
| 1 | То же, но недоверенный код исполняется в микро-ВМ (Kata): сетевой запрет, honeypot/sinkhole, RO-FS, лимиты; опционально — Falco/eBPF (хостовый мониторинг) | Kubernetes на 1 узле, RuntimeClass kata/gvisor, реестр образов |
bash deploy/install.sh 1 · bash deploy/verify.sh 1 |
| 2 | Сервис тестирования: HTTP-приём (потоково, большие модели), дедупликация в S3 (Garage) sha256/<name>, метаданные и находки в PostgreSQL, оркестрация Job, вердикт с учётом покрытия |
Уровень 1 + Garage + PostgreSQL | bash deploy/install.sh 2 · bash deploy/verify.sh 2 |
| 3 | Аналитика: скоринг, Policy Engine, append-only evidence с hash-chain, отчёты JSON/MD/SARIF, веб-UI (вход, роли, переключатель языка, /settings, баннер неполной проверки) |
Уровни 1–2 + Istio Ingress | bash deploy/install.sh 3 · bash deploy/verify.sh 3 |
| 4 | Интеграции: реестр моделей по SHA-256, CI-gate /gate (allow/block/review + exit-code), экспорт в SIEM (NDJSON/CEF), threat-intel |
Уровни 2–3 | bash deploy/install.sh 4 · bash deploy/verify.sh 4 |
| 5 | Эксплуатация: метрики Prometheus, /quality (TPR/FPR), /sla, /retest по cron, red-team Job, /alerts, retention/TTL + карантин, backup/restore с проверкой |
Уровни 3–4 | bash deploy/install.sh 5 · bash deploy/verify.sh 5 |
Команды идемпотентны: install.sh N доустанавливает всё необходимое до уровня N (можно сразу 5),
verify.sh N проверяет уровень «извне», а verify.sh N --full дополнительно прогоняет
синтетический корпус (141 образец). Форматный анализ не зависит от уровня: адаптеры едины
(poc/formats.py), поэтому и PoC, и сервис проверяют один и тот же набор форматов.
bash deploy/install.sh 3 # поставить уровни 1→2→3 (идемпотентно; можно сразу 5)
bash deploy/verify.sh 3 # проверка уровня «извне»
bash deploy/verify.sh 5 --full # + полный прогон корпуса (141 образец)Причина ровно в двух требованиях, которые плохо совмещаются «в одном скрипте на хосте»:
- Проверяемые файлы могут быть очень большими — модели достигают десятков и сотен гигабайт.
- Проверка обязана идти в изолированной среде — потому что загрузка и прогон модели так или иначе исполняют недоверенный код или разбирают недоверенные данные нативными движками инференса, а это потенциально небезопасно (см. «Следствие №2»).
- Держать модель в памяти или на диске пода нельзя: нужен S3-совместимый object store
(Garage), content-addressed ключи
sha256/name(дедупликация и иммутабельность), потоковая загрузка с подсчётом SHA-256 «на лету» и дедупликацией (повторная загрузка того же файла не передаёт данные повторно). - Метаданные, отпечатки и результаты живут отдельно от «тяжёлого» блоба — в PostgreSQL; для больших блобов действуют retention/TTL и карантин вредоносных.
- Артефакт в песочницу доставляется тем же сервисом (
:8090), поэтому сетевой доступ песочницы не расширяется.
Ключевая концепция системы: каждая проверка — это исполнение артефакта движком (engine), и результат
фиксируется неизменяемой связкой «артефакт + движок + версии» (bundle). Для pickle, скриптов и «инертных»
форматов (safetensors/ONNX/HDF5/Keras/архивы/датасеты) движком является песочный движок платформы
(Kata + harness) и он выбирается по умолчанию; для LLM движок — внешний инференс-образ (например
llama.cpp:server-cuda по digest), и его выбирает оператор обязательно (без дефолта). Так одна и та же
модель проверяется воспроизводимо, а в отчёте всегда видно, каким движком она исполнялась.
Уязвимость не сводится к pickle. Часть форматов действительно исполняет код напрямую
(pickle/dill/cloudpickle, model-as-code: .mar, trust_remote_code/auto_map,
tf.keras Lambda). Но существенно, что даже форматы, которые сами по себе код не
исполняют (SafeTensors, ONNX, GGUF, TFLite, HDF5, датасеты), не безопасны: их загрузка и
прогон выполняются движком инференса на недоверенных данных, а значит остаются пути
эксплуатации уязвимостей в самом движке и его окружении:
- Движок инференса — это нативный код с широкой attack surface. Загрузку и прогон делают
ONNX Runtime, PyTorch, TensorFlow,
ggml/llama.cpp, HDF5, protobuf/flatbuffers и т.п.; в их парсерах исторически встречаются уязвимости памяти (выход за границы, целочисленные переполнения, use-after-free), приводящие к падению, утечке данных или выполнению кода. - Custom ops / плагины / delegate-библиотеки. Модель может ссылаться на нативный код
(custom operators,
.so-плагины, TensorRT/OpenVINO extensions), который подгружается по имени/ссылке из артефакта. - External references. Внешние данные/ссылки (ONNX
external_data, HDF5 external links, конфиги) → path traversal, SSRF, подгрузка данных или кода из недоверенного источника. - Побочные эффекты при загрузке. Даже «только данные» могут привести к чтению файлов, обращению в сеть или изменению окружения, если это делает загрузчик/движок.
- Шаблоны и конфиги управляют рантаймом. Jinja
chat_template(SSTI), токенизаторы, tool/MCP-схемы меняют поведение движка — это тоже недоверенные данные, исполняемые окружением. - Структурные атаки на ресурсы. Вложенные контейнеры, огромные тензоры, decompression — отказ в обслуживании.
- Цепочка поставки окружения. Уязвимые версии движка и зависимостей, небезопасные конфигурации и плагины эксплуатируются не из модели, а из её окружения.
Итог: проверка всегда означает запуск движка на недоверенных данных, поэтому изоляция нужна не только для «исполняющих» форматов. Каждый артефакт проверяется отдельным инстансом:
- каждый запуск — микро-ВМ Kata (своё ядро), без сети (кроме sinkhole/артефакт-сервера),
read-only ФС,
drop ALL, seccomp, лимиты CPU/RAM/диска, honeypot-файлы, наблюдение (внутригостевые audit hooks — обязательно; хостовый Falco/eBPF — опционально, см.deploy/README.md) — это ограничивает и прямой payload, и эксплуатацию уязвимости движка; - среда гарантированно уничтожается после проверки, а поведение наблюдаемо (файлы,
процессы, сеть,
ctypes, измененияbuiltins/import-хуков).
Совмещение «огромные файлы + изоляция + наблюдаемость + аудит + масштаб» — это уже оркестрация, а не одиночный процесс. Kubernetes даёт ровно те примитивы, которые нужны:
| Требование | Примитив Kubernetes |
|---|---|
| Одноразовая изолированная среда на каждый артефакт | Job + runtimeClassName: kata (микро-ВМ) |
| Разделение доверенной и недоверенной зон | отдельные Namespace + Pod Security Admission restricted |
| Запрет сети из песочницы | NetworkPolicy (Calico): default-deny + только sinkhole/артефакт |
| Лимиты ресурсов и защита от DoS | cgroups v2: cpu/memory/pids/io/ephemeral-storage |
| Подъём/уборка среды | жизненный цикл Job (create → run → teardown, TTL) |
| Секреты и доступы | Secret, ServiceAccount, RBAC, монтирование без хост-томов |
| Внешний вход/выход | Ingress (Istio) + egress-allowlist |
| Периодические задачи | CronJob (retest, backup, retention) |
| Масштабирование под объём | автоподбор узлов/воркеров, пул GPU (при наличии) |
Без оркестратора пришлось бы вручную поднимать и убивать изолированные ВМ, настраивать сетевой запрет, лимиты, сбор трасс, хранение больших блобов и аудит — то есть воспроизводить эти примитивы самому. Kubernetes позволяет реализовать это декларативно и повторяемо, а контрольные плоскости (аналитика, БД, UI) при этом остаются в доверенной зоне.
Важно: артефакт никогда не исполняется в доверенной зоне — только в изолированной микро-ВМ, которая после проверки уничтожается целиком. Подробнее —
docs/03-isolation.mdиdocs/07-implemented-architecture.md.
Модели: pickle и производные (.pkl/.pickle, .joblib, .dill, .cloudpickle,
.pt/.pth/.bin/.ckpt), .npy/.npz, SafeTensors, ONNX, HDF5/.keras, GGUF, TFLite, CoreML,
TorchScript/torch.package, TF SavedModel/.pb, PMML, MLflow-модель, model-as-code (.mar,
model.py), датасеты Parquet/Arrow/Feather.
Пакеты и данные: архивы (.zip/.tar/.tar.gz/.whl), сжатые payload'ы (.gz/.bz2/.xz),
JSONL/CSV/TSV-датасеты, MessagePack, ноутбуки (.ipynb), скрипты (.sh/.ps1/.bat),
Dockerfile, HTML/SVG-документы, Jinja-шаблоны (.j2), XML/YAML/JSON-конфиги, карточки моделей,
tokenizer-артефакты, MCP/agent-манифесты, нативные библиотеки (.so/.dll/.dylib), .pth-хуки,
неподдерживаемые контейнеры (7z/rar/zstd — честное «разобрать нельзя»).
| Группа | Что обнаруживается |
|---|---|
A-*, F-* |
RCE при десериализации (os.system, subprocess, eval/exec), сеть, persistence, tampering builtins/import-хуков, утечки |
EXEC-* |
model-as-code (.mar/model.py/MLflow/auto_map/torch.package), Keras Lambda/custom_objects, ONNX external_data/custom ops, HDF5 links |
INJ-* |
Jinja chat_template (SSTI), prompt-injection в карточках и tool-схемах, HTML/JS (XSS) |
AGT-* |
MCP/agent-манифесты с запуском команд |
BD-* |
токенизаторы (переопределение спец-токенов, ReDoS-regex), веса (NaN/Inf, экстремумы) |
FMT-* |
структурные аномалии SafeTensors, архивы (traversal/bomb/symlink), XXE/unsafe-YAML, format mismatch |
INT-* |
целостность и supply chain (внешние URL, install-hooks в архивах) |
STEG-* |
скрытые каналы (trailing после EOCD, энтропийные blob, полиглот-контейнеры) |
D-* |
целостность/подпись/происхождение, «не pickle»-форматы |
SEC-* |
утечки секретов и токенов (AWS-ключи, приватные ключи, HF/GitHub/Slack-токены) |
Дополнительно: вложенные архивы разбираются рекурсивно (zip в zip), INJ-06 — формульные
инъекции в CSV, FMT-12 — дубликаты записей в архиве (p
8BD0
arser differential), EXEC-08 — нативные
библиотеки. Вердикт учитывает полноту покрытия: если модуль проверки не смог отработать
(модель не загрузилась, нет зависимости, таймаут), вместо Safe выдаётся Inconclusive с
частичным результатом — и в сервисе тестирования, и в аналитике/UI.
Образ песочницы mlscan-sandbox:v4 (сборка Kaniko) содержит библиотеки для динамического
исполнения и разбора моделей: PyTorch (CPU), numpy, safetensors, onnxruntime, onnx, h5py, gguf,
pyarrow, PyYAML, joblib, dill, cloudpickle — поэтому фактически загружаются и исполняются модели
форматов pickle, torch, numpy, model-as-code, а контейнеры safetensors/ONNX/HDF5/GGUF/Keras/
Parquet разбираются профильными библиотеками (mmap/схема).
Честный вердикт при неполной проверке. Модулей три (статика L1, динамика L2, поведение L3).
Если модуль не смог отработать — модель не загрузилась (нет зависимости), не хватило ресурсов,
таймаут, песочница не запустилась — результат не считается полноценным: вместо Safe
выдаётся Inconclusive с причиной «проверить всеми модулями не получилось (динамика:
No module named 'mymod'); частичный результат: …» и баннером в карточке. Если частичные
данные уже доказывают опасность, вердикт сохраняется, но помечается как неполный.
- L1 статика — без исполнения: опкоды/глобалы pickle, структурный разбор форматов, ссылки на код, external data, шаблоны.
- L2 динамика — исполнение в микро-ВМ Kata с полной наблюдаемостью (файлы/процессы/сеть/
ctypes, diff состояния процесса); model-as-code реально исполняется и подтверждается динамикой. - L3 поведение — интроспекция и probe загруженного объекта.
UI и сообщения сервисов локализованы (RU/EN): переключатель языка в шапке UI (cookie
mlscan_lang), ?lang=en / заголовок X-MLScan-Lang для API и глобальная настройка языка
всей системы (MLSCAN_LANG при запуске + POST /settings/language для администратора,
хранится в БД). Локализуются UI, причины вердиктов, находки (в том числе исторические) и отчёты.
Подробности — docs/12-i18n.md. Английская версия документации —
README.en.md и docs/en/.
S3-хранилище с дедупликацией и retention/карантином, PostgreSQL с hash-chain evidence,
AuthN/Z (API-ключи + RBAC + вход в UI), журнал подключений/загрузок/проверок (connections,
audit_log), Ingress/Egress-контроль, Model Registry и CI/CD gate, SIEM-экспорт, метрики и
метрики качества (TPR/FPR), непрерывный retest, red-team, бэкап БД с проверкой
восстановления.
| Мера | Как реализовано | Проверка |
|---|---|---|
| Изоляция исполнения | Kata microVM на каждый скан, egress allowlist (DNS/sinkhole/артефакт-сервер), RO-FS, drop ALL, seccomp, honeypot, default-deny NetworkPolicy |
verify.sh 1, red-team Job |
| Целостность образа | сборка Kaniko публикует digest; Job запускается только как image@sha256:…; Kyverno-политика требует kata + digest + безопасный securityContext |
verify.sh 1; Job с чужим образом отклоняется admission |
| Egress платформы | сервисам разрешены только PG/S3/DNS и адрес K8s API (ClusterIP и узел); чужие сервисы и произвольные порты блокируются; манифесты VirtualService/egress разложены по уровням | verify.sh 3 |
| Квоты и лимиты | ResourceQuota/LimitRange namespace песочницы; rate limit загрузок (30/мин → 429 + Retry-After); лимит 5 сканов «в работе» |
flood-тест: 30×202, 10×429 |
| Честность вердикта | неполнота покрытия → Inconclusive + баннер; лимит находок (500) с пометкой об усечении |
корпус; verify.sh 2 |
| Защита от подмены результата | harness печатает маркеры со нонсом скана; сервис принимает только свои маркеры и сверяет summary/result | образец-спуфер vuln_result_spoof.pkl → подделка игнорируется |
| Целостность кода/конфигурации | digest ConfigMap'ов кода и правил передаётся в env; сервис сверяет при старте и работает fail-closed (503) |
/healthz → integrity: true; тест подмены ConfigMap |
| Evidence | append-only (файл + триггеры БД), hash-chain + HMAC-подписи (ключ в Secret, вне БД/PVC), проверка по генерациям, single-writer (PG advisory lock) | /api/evidence/verify → ok/signed/generations; неверный ключ → HMAC mismatch |
| Аттестация | CronJob mlscan-attest (каждые 6 ч) + результат проверки в POST /retest и в метриках mlscan_evidence_ok/signed/entries |
Job succeeded, лог ATTEST {…} |
| Доступы | API-ключи с expires_at (истёкший → 401), пользователи UI (PBKDF2, 200k), HMAC-сессии 12 ч, роли admin/ci-reader/service, аудит в audit_log |
тест истёкшего ключа |
Полный разбор сценариев атак и план доработок — docs/14-security-review.md
(статус: P0 и P1 реализованы; открыты P0-4 — мгновенный Reject для сети песочницы, P1-2 — DNS-политика,
P1-8 — аудит изменений, P2).
Синтетический корпус — tests/vulnerabilities/: 141 образец
(87 с закладками + 54 безопасных), генераторы, прогонщик и отчёт. Помимо pickle-семейства —
ноутбуки, скрипты, TorchScript/torch.package, MLflow, TF SavedModel, TFLite, CoreML, PMML,
датасеты Parquet/Arrow, ONNX external_data, внешние ссылки HDF5, safetensors-метаданные.
Безопасная часть — реальные файлы этих форматов и пять образцов ~198 МБ, генерируемых
на лету и загружаемых сразу в сервис тестирования. Результат: 87/87 обнаружено, 0 пропусков, 0/54 ложных срабатываний; крупные
модели — Safe с полным покрытием; метрики качества по форматам TPR=1.0, FPR=0.0. Быстрый прогон корпуса на развёрнутом стенде —
bash deploy/verify.sh <уровень> --full; генерация и детали — в README корпуса.
Актуальный стенд: UI за Keycloak (OIDC) — https://mlscan.platform.rtx.local (роли берутся из
групп Keycloak, напр. mlscan-admins → admin). Разделы: Сканы · Загрузка · История операций ·
Настройки · Администрирование. Снимки ниже сделаны с боевого тенанта (tests/ui/screenshots.js).
Сканы — список проверенных артефактов с вердиктами (в т.ч. Inconclusive при неполной
проверке), фильтрами и статистикой по вердиктам/объёму; виден движок инференса:
Карточка артефакта (LLM + инференс) — Qwen3-1.7B, формат safetensors: покрытие
(статика/динамика/поведение), находки, сенсор и раздел «Связи» — по одному вердикту на каждый
движок (bundle) с аттестацией: engine-sglang:v0.5.9 → Needs review, engine-vllm:v0.9.2:
Загрузка — Модели (локальные артефакты, в т.ч. большие; формат определяется по расширению):
Загрузка — Тест bundle (прогон набора вопросов на выбранном движке инференса):
Загрузка — Движки инференса (реестр образов движков по digest, подпись/SBOM):
Загрузка — Модель с HF — фоновые загрузки с докачкой; для vLLM/SGLang скачивается весь каталог модели; прогресс, статус и вердикт по каждой загрузке:
История операций — журнал действий и загрузок:
Настройки — язык системы и параметры:
Администрирование — активный набор вопросов и его размер (вопросов 726), сопоставление
домен → класс policy (auto/overrides), импорт XLSX, rate-limit, квоты HF/egress, проверка
цепочки вердиктов:
Архив (v2-стенд, прежний UI). Снимки ниже — с прежней установки (
analytics.mlscan.local); сохранены как иллюстрация классических карточек не-LLM артефактов: вход/сессия, дашборд, неполная проверка (Inconclusive), крупная torch-модель и model-as-code (.mar).
Снять свои снимки: bash tests/ui/run_ui_tests.sh или
MLSCAN_UI_URL=http://127.0.0.1:18081 node tests/ui/screenshots.js (port-forward к
mlscan-analytics; сервис доверяет заголовкам oauth2-proxy X-Forwarded-User/Groups).
Три компоненты (Компоненты 1–3), развёрнутые в отдельных namespace:
- Sandbox — изоляция и запуск моделей, полное наблюдение за поведением (Kata-микро-ВМ).
- Testing Service — подача артефактов в песочницу и безопасное получение результатов.
- Analytics Engine + UI — управление процессом, скоринг, Policy Engine, Evidence Store, отчёты и веб-UI. Плюс Integrations (registry/gate/SIEM) и Ops (метрики/качество/retest).
См. docs/05-architecture.md, Concept.md,
docs/07-implemented-architecture.md (as-built),
docs/11-target-architecture-v2.md (v2).
| Путь | Что это |
|---|---|
START.md |
Стартовая статья: фокус проекта, история, масштабируемость архитектуры |
tests/vulnerabilities/ |
Синтетический корпус уязвимостей + процедура + отчёт о детекции |
deploy/README.md |
Выбор уровня развёртывания (0–5), матрица возможностей и команд |
deploy/install.sh |
Установка выбранного уровня (идемпотентно, с проверкой предпосылок) |
deploy/verify.sh |
Сквозная проверка уровня (--full — прогон корпуса) |
deploy/upgrade.md |
Переход N → N+1: компоненты, миграции, откат |
poc/mlscan_poc.py |
PoC (уровень 0) — один Python-файл: статика по всем форматам + динамика/поведение в Docker |
poc/formats.py |
Адаптеры форматов (stdlib) — единый модуль для PoC и сервиса тестирования |
poc/scan/ |
Демонстрационные данные (pickle + formats/) и генераторы |
deploy/stage1/ |
Этап 1 (уровень 1): песочница Kata, deception, sinkhole, NetworkPolicy; Falco — опционально (60-falco.sh) |
deploy/stage2/ |
Этап 2: сервис тестирования |
deploy/stage3/ |
Этап 3: аналитический движок + UI |
deploy/stage4/ |
Этап 4: интеграции (registry/CI-gate/SIEM/threat-intel) |
deploy/stage5/ |
Этап 5: эксплуатация (метрики/качество/retest/red-team) |
deploy/sandbox-image/ |
Образ песочницы mlscan-sandbox (torch CPU), сборка Kaniko |
deploy/i18n/ |
Модуль локализации RU/EN (UI, сообщения сервисов, находки) |
deploy/ingress/ |
Ingress (Istio) и egress-allowlist |
deploy/v2/ |
v2: S3 (Garage), PostgreSQL, AuthN/Z+audit, наблюдаемость, бэкап, lifecycle, детекторы форматов |
docs/ |
Детальная документация (01–13) |
docs/en/ |
Английская версия документации (01–13) |
README.en.md |
English version of this page |
docs/01чеклист опасностей (A–I) ·docs/02стратегия тестирования L0–L4 ·docs/03изоляцияdocs/04обработка результатов и решения ·docs/05архитектураdocs/06план реализации (реализован) ·docs/07as-built архитектура ·docs/08тест-гайдdocs/09анализ других форматов/закладок ·docs/10план расширения (волны) ·docs/11целевая архитектура v2docs/12локализация UI и сообщений (RU/EN) —docs/12-i18n.mddocs/13план поэтапного развёртывания (уровни 0–5) —docs/13-deployment-plan.mddocs/14анализ ИБ архитектуры и кода + план доработок —docs/14-security-review.mddocs/15анализ большого файла модели: пошагово —docs/15-large-model-analysis.md- английские версии —
docs/en/
Требования: Python 3.10+ (только stdlib) и Docker — только для динамического этапа.
PoC уже умеет статически проверять все поддерживаемые форматы (наш «второй глаз» для
расширенного списка — poc/README.md):
python3 poc/mlscan_poc.py poc/scan/evil0.pkl --out report.md # статика + динамика + поведение
python3 poc/mlscan_poc.py model.safetensors --static-only # SafeTensors: только статика
python3 poc/mlscan_poc.py payload.ipynb --static-only --lang en # ноутбук, отчёт на английском
python3 poc/mlscan_poc.py arch/model.zip --image localhost:32000/mlscan-sandbox:v4 # динамика с библиотеками
cat model.pkl | python3 poc/mlscan_poc.py - --name model.pkl # ввод из stdin (без файла на диске)Артефакт передаётся в контейнер без расшаренных каталогов (stdin + base64-бутстрап harness,
результат — в stdout); вердикт учитывает полноту покрытия (Inconclusive + причина, если модуль
не смог отработать).
Реализованы и проверены: PoC, система для pickle (Этапы 0–5), целевая архитектура v2
(Волна 0: S3/PostgreSQL/AuthN+audit/наблюдаемость+бэкап; волны форматов 1–3: адаптеры и
детекторы, динамика model-as-code; retention/TTL и карантин), метрики качества по форматам
(TPR=1.0, FPR=0.0), синтетический корпус (87/87, 0 FP) и харденинг платформы — P0/P1 из ИБ-обзора
(docs/14). UI и сообщения
сервисов локализованы RU/EN, есть глобальная настройка языка.
Контекст: deploy/v2/README.md, план — docs/10-plan-new-formats.md,
целевая архитектура — docs/11-target-architecture-v2.md.
MIT — см. LICENSE.
Документация разделена по версиям (живой код deploy/, poc/, tests/ — в корне):
| Каталог | Версия | Содержание |
|---|---|---|
PoC/ |
v0 | Концепция, риски pickle, стратегия тестирования, изоляция, решения |
Arch_v1/ |
v1 | Рабочий MVP: сервис+песочница+Kata+Ingress, форматы, i18n, развёртывание, ИБ |
Arch_v2/ |
v2 | S3 (Garage), PostgreSQL, ingest, большой файл, описание работы и анализ ограничений v2 |
Arch_v3/ |
v3 | Целевая архитектура для 1 ТБ+ + реализация (as-built): фазы P0–P10 и L0–L4 выполнены на стенде (см. статус) |
Arch_v4/ |
v4 | Унифицированная Kata-песочница: все движки инференса и артефакты — внутри микро-ВМ (включая GPU-в-Kata), обязательные ловушки и наблюдение; движки/тесты — данные; управляемая скоринговая политика вердикта |
Сводный индекс — ARCHITECTURES.md. Дальнейшая разработка ведётся по v3.
Старые пути docs/NN-*.md оставлены заглушками-редиректами (совместимость ссылок).
- Текущий стенд (тенант): namespace
t-mlscan-app/t-mlscan-sandbox; UI за Keycloak —https://mlscan.platform.rtx.local; API-ингресс —https://mlscan-api.platform.rtx.local; S3 — Ceph RGW (s3.platform.rtx.local); PostgreSQL; ops/metrics(скрейпится Prometheus), integrations/gate. Деплой через ArgoCD (Gitea) + Harbor (immutable digest). Подробности и процедуры —deploy/tenant/STATUS.md. - v2-линия (сервис + Kata + аналитика, Garage, отдельные
mlscan-*namespace и UIanalytics.mlscan.local:30217) сохранена как предыдущий стенд и в основном перенесена в тенант.
- Data-plane/ingest: range-read, общий пул
objects/<sha…>+object_refs(дедуп), TLS-egress S3, прототип 3×Garage RF=2 (долговечность при выводе узла); server-side copy//objects/import, квоты ingest (403/429), resume после рестарта, fair-share веса. - Aнализ: потоковая index-driven статика из S3 для safetensors/GGUF/ONNX; обход архивов (zip CD/tar) по range с depth-бюджетом, zip-slip/bomb; детерминированный selector срезов, план динамики фиксируется в скане.
- Control plane: приоритетная очередь
tasks(SKIP LOCKED), orchestrator, подписанная политика fail-closed, регистр версий детекторов, tenants. - Безопасность: evidence HMAC-цепочка + WORM-анкор, per-tenant KMS (fail-closed); реестр образов по digest (allowlist/admission), подпись/SBOM-запись.
- Наблюдаемость:
/v3/metrics(per-tenant) и/v3/slo; per-tenant метрики в ops/metrics; single-writer/leader-election (PG advisory-lock). - LLM: UI-типизация (
kind) + бейдж «Engine image» + импорт образа; классификатор LLM (авто для GGUF); единая Kata-среда (model-fetcher+engine+tetragon+probe), Job проходит Kyverno, ресурсныйprecheck; события eBPF →LLM-B-01..05(нонс); XLSX-наборquestions_v9→ БД/версии, правила+judge+допуск 90/75/50, редактор «домен→класс»; вердикт bundle + аттестация и CI-gate (/gate?image&model); фоновые HF-загрузки с докачкой (не зависят от браузера, mock-HF); CPU-инференс llama.cpp: E2E «HF → llama.cpp → 10 случайных вопросов заказчика → score» (total=10, passed=5, safety_fail=5, pass_rate=0.5). - Миграция v2→v3: копия в пул + refs + reconcile + readiness (идемпотентно).
- 190 unit (
tests/v3167,tests/s322,tests/formats1), 6 браузерных (puppeteer), 42 e2e-скрипта на реальных Garage/PostgreSQL/кластере — все зелёные. - Запуск:
python3 -m unittest discover -s tests/v3·bash tests/ui/run_ui_tests.sh·bash tests/e2e/<name>.sh.
- In-guest eBPF/Tetragon в тенанте (RuntimeClass
kata-btf+ ConfigMapmlscan-ebpf-agent): сейчас сенсор выключен (SANDBOX_EBPF/LLM_TEST_EBPF=0), поэтомуLLM-B-01..05не срабатывают — это главная «слепая зона» наблюдения (см.CrossProcess_overview.md§8). - LLM-тесты вне Kata: идут на
runtimeClassName: nvidia(хостовое ядро, GPU); нужна Kata+GPU (или иной микро-ВМ) для изоляции недоверенного движка/модели. - Harbor + cosign/SBOM, Vault/TSA/WORM, mTLS, multi-node HA/DR, GitOps-контроллер, доверенная judge-модель, HDF5-адаптер, перф-замеры 1 ТБ.
- HF-воркер: редкий случай
EntityTooSmallна multipart для мелких последних частей (наблюдалось наsshleifer/tiny-gpt2в списке загрузок) — поправить порог/размер части.
Интернет у узла есть; egress подов ограничен нашей NetworkPolicy (mlscan-egress) — поэтому HF/ghcr
недоступны из подов, но pull образов делает kubelet (вне политик) — так получен образ llama.cpp.
Guest-ядро Kata по умолчанию без BTF (host-ядро — с BTF).
Сводный статус фаз — Arch_v3/15-implementation-plan.md §7 и
Arch_v3/19-implementation-as-built.md.
- На узле: 2× Quadro RTX 4000 (8 ГБ) + GTX 1050 (драйвер 580.178, toolkit 1.20.1).
- Инференс на GPU работает через
runtimeClassName: nvidia+ hostPath/dev; образ llama.cpp CUDA (server-cuda,-ngl 99) выдаёт ответы на RTX 4000 (подтвержденоnvidia-smi). - E2E: 10 случайных вопросов заказчика на GPU —
passed=6/10,~23.9 tok/s(tests/e2e/llama_cpp_gpu_e2e.sh). nvidia.com/gpuвключён: официальныйnvidia/k8s-device-pluginv0.17.0 собран из исходников (kaniko) и опубликован в локальный реестр; pod’ы получают GPU черезresources.limits."nvidia.com/gpu"+runtimeClassName: nvidia.- MIG на этих GPU не поддерживается (
mig.mode.current=[N/A]; нужны A100/A30/H100). - Две карты:
nvidia.com/gpu=2(обе RTX 4000); проверены (A) запуск небольшой модели на второй карте и (B) двухкарточный инференс 3B-модели (--tensor-split 1,1) — обе карты заняты (nvidia-smi 40–45%, ~1.1–1.3 ГБ), 10 вопросовpassed=10/10. - Инструкция оператору (проверка моделей, сценарии/данные/интерпретация) —
Arch_v3/20-operator-guide.md