Пошаговое руководство по курсу

Для кого: разработчики, защищающие MCP-агентов до (или параллельно с) ARGUS / AI-Factory.
Язык лаб: COURSE_LANG=en|ru|es|fr|zh · строки UI в i18n/ · этот гайд на русском. English · Español · Français · 中文

Сверка с текущей экосистемой

После проверки учебных данных сравните архивные определения инструментов в HISTOR и записи LEGION. Запишите время наблюдений и классифицируйте изменения имён, описаний или схем. Совпадение относится к тому, что увидели оба журнала. Перед загрузкой инструментов изучите текущие определения и проверяйте утверждённый файл блокировки WARDEN в CI.

Зачем этот курс

MCP (Model Context Protocol) подключает агента к внешним серверам инструментов — но каждое описание инструмента и каждая JSON-схема это текст, контролируемый атакующим, который модель читает как доверенную инструкцию. Курс учит строить модель угроз этой поверхности, статически сканировать отравленные определения инструментов, ранжировать серверы графовым доверием (LUMEN), включать fail-closed allowlist владельца и собирать всё в gate WARDEN, который блокирует вредоносный typosquat-сервер. Каждый примитив это запускаемый, без LLM, Python-порт боевого MCP-firewall ARGUS WARDEN — то, что вы изучаете, ложится прямо на реальный код.

Выбор трека

Трек	Модули	Время	Оракулы
Базовый	M1 → M2 → M3 → M4	~2 ч	LUMEN (только M3)
Продвинутый	Базовый + M5 capstone	+30 мин	LUMEN + полная цепочка WARDEN
Мост к Factory	После M4 или M5	+30 мин	Реальный ARGUS + Hub

Каждая лаба печатает блок Trace — относитесь к нему как к журналу аудита лабы.

Установка (10 минут)

Шаг 1 — Клон и установка

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/mcp-security-course
pip install -e ".[oracles,dev]"

Из монорепозитория aicom (рекомендуется для контрибьюторов):

cd courses/mcp-security-course
pip install -e ".[oracles,dev]"

LUMEN подтягивается автоматически из oracles/oracles/lumen при запуске внутри монорепозитория.

Отдельный клон без соседнего монорепозитория:

git clone --depth 1 https://github.com/alexar76/oracles.git _deps/oracles
pip install -e _deps/oracles/oracles/lumen
pip install -e ".[oracles,dev]"

Шаг 2 — Тесты

pytest -q

Ожидается: паритет i18n, статическое сканирование WARDEN, PageRank LUMEN, упражнения, smoke-импорты лаб.

Шаг 3 — Язык интерфейса лаб (опционально)

export COURSE_LANG=ru   # или es, по умолчанию en
python labs/lab01_threat_model.py

Шаг 4 — Google Colab

Откройте сайт курса → Open in Colab на любой лабе.
Выполните setup-ячейку (clone + pip + срез oracles).
При необходимости задайте os.environ["COURSE_LANG"] = "ru" в setup.
Запустите ячейку лабы.

M1 — Модель угроз MCP

Концепция: внедрение промптов, отравление инструментов и каналы утечки данных в MCP.
Лаба: labs/lab01_threat_model.py · ~15 мин · установка завершена

Шаги

Прочитайте docstring в начале labs/lab01_threat_model.py.
Запустите локально:
```
python labs/lab01_threat_model.py
```
Разберите два сценария:
- Prompt injection — текст атакующего, спрятанный в описании инструмента.
- Tool poisoning — поля схемы, запрашивающие секреты или exfil-URL.
Прочитайте блок trace — каждая поверхность атаки логируется как событие.
Бегло просмотрите courselib/warden.py — найдите INJECTION_PATTERNS, EXFIL_PATTERNS, SECRET_PATTERNS (5 мин).

Самопроверка

[ ] Объясняете, почему описания инструментов это текст атакующего, которому модель доверяет
[ ] Видите разницу между injection в промпте пользователя и отравлением определения инструмента

M2 — Статическое сканирование и политика

Концепция: ловим вредоносные схемы инструментов до того, как агент их вызовет.
Лаба: labs/lab02_static_scan.py · ~20 мин · нужен M1

Шаги

python labs/lab02_static_scan.py
Сравните блоки сканирования benign vs malicious:
- benign → высокая оценка, ноль или низкая критичность срабатываний;
- malicious → низкая оценка, TOOL_DEF_INJECTION, TOOL_DEF_EXFIL, TOOL_DEF_SECRET_REQUEST.
Прочитайте сообщения срабатываний — какой haystack совпал (description vs JSON-схема).
Откройте warden/src/static-scan.ts в монорепозитории — сравните паритет регулярок с courselib/warden.py.
Упражнение: python labs/run_exercises.py --module m2

Самопроверка

[ ] Статическое сканирование идёт по описанию и по тексту JSON-схемы
[ ] Одно критическое срабатывание обрушивает оценку gate, но в одиночку не всегда даёт фатальную блокировку

M3 — Оценка доверия LUMEN

Концепция: репутация на графе — кто-кому-доверяет PageRank по MCP-серверам.
Лаба: labs/lab03_lumen_score.py · ~20 мин · нужен [oracles] (numpy + lumen)

Шаги

Подтвердите установку: pip install -e ".[oracles,dev]".
python labs/lab03_lumen_score.py
Посмотрите рёбра графа доверия: hub → официальные серверы; typosquat изолирован.
Изучите ранжированные оценки — hub и официальные серверы должны обгонять offical-mcp-drainer.
Прочитайте courselib/lumen.py — demo_mcp_trust_graph() и score_servers().
Опционально: откройте oracles/oracles/lumen/lumen/pagerank.py — ядро EigenTrust.
Упражнение: python labs/run_exercises.py --module m3

Самопроверка

[ ] Оценки в сумме дают 1 (распределение вероятностей)
[ ] Транзитивное доверие поднимает узлы, которым доверяют доверенные узлы

M4 — Owner-lock и fail-closed

Концепция: привязка агентов к спискам инструментов, одобренным владельцем (аналог Telegram owner-lock).
Лаба: labs/lab04_owner_lock.py · ~15 мин · нужен M2

Шаги

python labs/lab04_owner_lock.py
Разрешённые инструменты (read_file, search_docs) проходят; exec_shell, transfer_funds блокируются.
Обратите внимание на демо с пустым allowlist — fail-closed, каждый инструмент запрещён.
Прочитайте OwnerLock в courselib/warden.py — check_tool() и OwnerLockGate.
Доп. чтение: argus/docs/channels.md § Telegram owner-lock.
Упражнение: python labs/run_exercises.py --module m4

Самопроверка

[ ] Allowlist явный — неизвестные инструменты запрещаются, а не молча разрешаются
[ ] Пустой allowlist это fail-closed (нулевое доверие по умолчанию)

M5 — Capstone: вредоносный сервер

Концепция: полная цепочка gate WARDEN блокирует отравленный typosquat MCP-сервер.
Лаба: labs/lab05_warden_capstone.py · ~30 мин · нужны M1–M4

Шаги

python labs/lab05_warden_capstone.py
Сравните вердикты:
- Benign официальный сервер → allowed, высокая составная оценка;
- Poisoned typosquat → blocked, decided_by называет провалившийся gate.
Порядок gate в учебном порте: static-scan → threat-feed → reputation (LUMEN) → owner-lock → pinning.
Изучите список срабатываний — до блокировки могут отметиться несколько gate.
Прочитайте Warden.vet() в courselib/warden.py — составная оценка это произведение оценок gate.
Упражнение: python labs/run_exercises.py --module m5

Самопроверка

[ ] Threat feed ловит id typosquat-сервера (offical-mcp-drainer)
[ ] Static-scan ловит injection + exfil в определениях инструментов
[ ] Низкая репутация LUMEN вносит вклад при allow_unknown_servers=False

Упражнения и сертификат

После лаб запустите DIY-проверки:

python labs/run_exercises.py
python labs/run_exercises.py --certificate "Иван Петров" --lang ru

Откроется certificate.html — Print → Save as PDF в браузере. ID удостоверения выводится из имени + даты.

Модуль	Проверка упражнения
M1	Сигнатура injection обнаружена в отравленном инструменте
M2	Benign-инструменты не дают критических срабатываний
M3	Hub обгоняет typosquat на графе доверия
M4	Owner-lock запрещает инструменты вне списка
M5	Полный WARDEN блокирует вредоносный capstone-сервер

Наблюдаемость в каждой лабе

Концепция: каждая лаба логирует решения в Trace — это ваш аудит-след событий безопасности.

Шаги (повторять после каждой лабы)

Прокрутите к секции trace в выводе лабы.
Сопоставьте события со stdout: срабатывания, оценки доверия, решения owner-lock, вердикты WARDEN.
В M5 сопоставьте события warden_finding с напечатанным списком срабатываний.

Самопроверка

[ ] Trace это «превью SIEM» для безопасности агента
[ ] Можете указать на gate, заблокировавший подключение

Мост: от курса к ARGUS WARDEN

Цель: связать концепции курса с боевым ARGUS (~30 мин).

Прочитайте документацию WARDEN — argus/docs/security-warden.md

Сопоставление курс → ARGUS

Курс	ARGUS
M2 static-scan	`warden/src/static-scan.ts`
M3 LUMEN	`ReputationGate` + оракул LUMEN
M4 owner-lock	Owner-lock канала + allowlist egress
M5 capstone	Цепочка gate `Warden.create()`

Запустите ARGUS (опционально, из монорепозитория):
```
cd argus && npm install && npm test -- warden
```
Безопасность supply в Hub — aimarket-hub/docs/supply-security.md

Чеклист самопроверки

После базового трека вы умеете:

[ ] Запускать lab01–lab04 локально и в Colab
[ ] Называть три семейства сигнатур static-scan (injection, exfil, secrets)
[ ] Объяснять PageRank-доверие на графе MCP-серверов
[ ] Описывать fail-closed allowlist владельца
[ ] Читать блок Trace и находить заблокированный инструмент или gate

После продвинутого трека добавьте:

[ ] Запустить lab05 и объяснить, какой gate заблокировал typosquat-сервер
[ ] Открыть warden/src/index.ts и найти боевой порядок gate

Типичные проблемы

Проблема	Решение
`ModuleNotFoundError: courselib`	Запуск из корня репозитория; лабы добавляют родительский путь в `sys.path`
`ImportError: Oracle package 'lumen'`	Установите срез oracles или запускайте из монорепозитория aicom
Нет `numpy`	`pip install -e ".[oracles,dev]"`
Пустые строки RU/ES	Задайте `COURSE_LANG`; ключи `i18n/ru.json` должны совпадать с `en.json`
Падение pytest по i18n	Добавьте недостающие ключи во все три JSON-файла
M5 блокирует benign-сервер	Проверьте, что allowlist owner-lock включает имена benign-инструментов
Старый код в Colab	Перезапустите setup-ячейку; закрепите ветку `main`

Проблемы с ARGUS: argus/README.md

Пересборка сайта и ноутбуков

После правок лаб или i18n:

python3 scripts/build_course_assets.py
python3 scripts/labs_to_notebooks.py

Гайды в docs/ правятся вручную — сначала EN, затем зеркала RU/ES.