mcpsafetywarden

MCP Safety Warden — это прокси-сервер, который оборачивает любой MCP-сервер и добавляет к его инструментам поведенческое профилирование, сканирование безопасности, контроль рисков и безопасное выполнение.

Содержание

• Обзор
• Предварительные требования
• Установка
• Конфигурация
• Интеграция с MCP
• Справочник CLI
• Дополнительные интеграции
• Разработка
• Тестирование
• Дополнительная информация

[!IMPORTANT] Безопасность MCP — активная область исследований. Недавние обзоры каталогизируют множество категорий угроз, специфичных для протокола, включая отравление инструментов, инъекции подсказок, атаки rug-pull, компрометацию цепочки поставок, кражу учётных данных и композиционные атаки на протяжении всего жизненного цикла сервера. См. Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv) и MCP-38 Taxonomy (arXiv).

Обзор

Используйте как прокси для добавления контроля безопасности к любому MCP-серверу или направьте его на сервер, которым вы не владеете, и выполните полный аудит безопасности без единого вызова инструмента.

Рис. 1. Два режима работы: прокси и аудит

Поведенческое профилирование: Класс эффекта, безопасность повторных попыток, деструктивность. С помощью LLM (Anthropic, OpenAI, Gemini, Ollama) с резервным правиловым режимом. Наблюдаемая статистика (латентность p50/p95, доля отказов, размер вывода) обновляется после каждого проксированного вызова.

Сканирование безопасности: mcpsafety+ пятиэтапный конвейер (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (анализ метаданных). Интеграции с Kali и Burp Suite обогащают конвейер реальными данными сети и HTTP-зондированием. Сканирование исходного кода из GitHub с обнаружением энтропии, AST, потоков заражения и атак rug-pull.

Рис. 2. Пятиэтапный конвейер mcpsafety+, запускаемый при полном аудите безопасности любого MCP-сервера

Безопасное выполнение: Сканирование аргументов (более 20 категорий атак, второй проход с LLM). Двухуровневое сканирование инъекций вывода. Контроль рисков с альтернативами и политиками для каждого инструмента. Обнаружение отклонений при каждом вызове и отдельной проверке.

Рис. 3. Конвейер безопасного выполнения: пять проверок, через которые проходит каждый проксированный вызов инструмента

CLI: 24 подкоманды, интерактивное меню рисков, флаг --json для каждой команды, --yes для CI.

Что он обнаруживает

• Инъекции подсказок (prompt injection): попытки перехвата агента через вывод инструмента: перехват роли, jailbreak, поддельные системные подсказки, переопределение инструкций. Обнаруживает 11 методов обфускации, включая символы, похожие на Unicode, символы нулевой ширины и полезные нагрузки, закодированные в base64.
• Вредоносные метаданные инструментов: описания, содержащие строки инъекций, жёстко закодированные секреты, подозрительные URL загрузки, подражание инструментам (shadowing), прямое финансовое выполнение, модификация системных служб и ненадёжные внешние зависимости. Подтверждается 19 проверками Snyk.
• Инъекции аргументов: более 20 категорий атак проверяются перед каждым вызовом инструмента до его пересылки: SSRF на конечные точки облачных метаданных (AWS, GCP, Azure, Alibaba), обход путей, доступ к файлам учётных данных (.aws, .ssh, .kube, .env), инъекция команд, SQL/NoSQL/LDAP/XPath, XXE, инъекция шаблонов (SSTI), CRLF, нулевой байт, десериализация (Java, Python pickle, PHP, .NET), атаки Windows UNC/ADS и варианты всего вышеперечисленного, обфусцированные base64.
• Риски исходного кода: извлекает исходный код сервера из GitHub и выполняет 6 уровней анализа: сканирование энтропии для жёстко закодированных секретов, отслеживание потока заражения через AST (от параметра к опасному получателю), несоответствие описания и реализации, SAST с помощью Bandit и Semgrep, а также кросс-функциональное рассуждение LLM. Поддерживает Python и TypeScript/JavaScript.
• Rug-pull и отклонения: сохраняет SHA-256 хеш исходного кода сервера при первом сканировании и предупреждает об изменениях. Обнаруживает замены описаний, изменения схем и удаление инструментов в реальном времени через защиту от отклонений при каждом вызове.
• Аномалии поведения: классифицирует каждый инструмент по классу эффекта, деструктивности и 7 тегам риска: раскрытие учётных данных, произвольное выполнение, утечка данных, доступ к файловой системе, боковое перемещение, повышение привилегий и поверхность инъекций подсказок.
• Композиционные атаки: анализирует наборы инструментов на предмет цепочек риска: цепочки IDOR, пары чтение-запись, эксплуатация потоков аутентификации, последовательности запись-затем-выполнение и пути накопления данных с утечкой через несколько инструментов.
• Сетевые и хост-риски: при зарегистрированном MCP Kali Linux: открытые порты, запущенные службы, отпечаток ОС через nmap. При зарегистрированном MCP Burp Suite: активное HTTP-зондирование и слепая SSRF через внешние обратные вызовы.
• Раскрытие учётных данных в выводах: скрывает секреты из ответов инструментов перед сохранением. Ответы, отмеченные как инъекции, помещаются в карантин и не возвращаются вызывающему агенту — сохраняются под идентификатором запуска для судебной проверки.

Предварительные требования

• Python 3.10 или новее
• Хотя бы один обёрнутый MCP-сервер для проксирования (stdio, SSE или streamable_http)
• Рекомендуется: ключ API LLM (Anthropic, OpenAI или Gemini)

Без ключа обёртка работает только в правиловом режиме: классификация инструментов с меньшей уверенностью, проверка инъекций только по регулярным выражениям, отсутствие альтернатив в контроле риска, отсутствие конвейера mcpsafety+. Для полностью локальной настройки запустите Ollama, установите OLLAMA_MODEL и явно передайте --provider ollama (Ollama не определяется автоматически).

[!NOTE] Серверы stdio, требующие локальной настройки (серверы stdio, которые требуют локальной конфигурации перед запуском — отсутствующие конфигурационные файлы, учётные данные, каталоги данных или OS-зависимые зависимости) не могут быть проверены обёрткой — обнаружение инструментов завершится ошибкой, и 0 инструментов будет сохранено. Вы всё ещё можете выполнить полное сканирование исходного кода без запуска сервера, передав --github-url командам scan / onboard или параметр github_url для security_scan_server. Конвейер mcpsafety+ извлечёт и проанализирует исходный код напрямую из GitHub. Серверы sse и streamable_http не затрагиваются.

Установка

pip install mcpsafetywarden

Со всеми дополнительными опциями:

pip install "mcpsafetywarden[all]"

Или с выбранными опциями:

pip install "mcpsafetywarden[anthropic,snyk]"

Из исходников:

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

База данных SQLite создаётся автоматически при первом запуске в каталоге пользовательских данных платформы (~/.local/share/mcpsafetywarden/ в Linux, ~/Library/Application Support/mcpsafetywarden/ в macOS, %APPDATA%\mcpsafetywarden\ в Windows). Переопределить с помощью MCP_DB_PATH.

Защита учётных данных (автоматически, не требует действий)

Секретные значения, передаваемые в register_server или onboard_server (токены Bearer, ключи API в headers или env), автоматически обнаруживаются и заменяются непрозрачными идентификаторами cref_ до того, как что-либо коснётся контекста модели. Реальные учётные данные хранятся зашифрованными в базе данных и разрешаются незаметно при подключении. Модель, история разговоров и журналы видят только cref_<id>.

Опционально: шифрование хранящихся учётных данных

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Установите полученный ключ как MCP_DB_ENCRYPTION_KEY перед запуском сервера. Это шифрует как учётные данные сервера, так и значения cref_ в состоянии покоя.

Конфигурация

Вся конфигурация осуществляется через переменные окружения.

Замечание по безопасности: Никогда не сохраняйте ключи API или ключ шифрования в репозитории. Обёртка удаляет свои собственные секреты из окружения дочерних процессов перед запуском stdio-серверов.

Интеграция с MCP

Подключение к Claude Desktop

Добавьте обёртку в claude_desktop_config.json:

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<generated_fernet_key>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

Зарегистрируйте каждый сервер в обёртке перед использованием:

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'

Для настройки обязательного шлюза, когда все вызовы инструментов должны проходить через обёртку, см. docs/DEPLOYMENT.md.

Доступные инструменты MCP

Полный справочник инструментов см. в docs/TOOLS.md.

Справочник CLI

24 подкоманды, охватывающие все 25 инструментов MCP. Каждая команда поддерживает --json для машинного вывода и --yes / -y для пропуска запросов подтверждения.

Полный справочник с флагами и примерами см. в docs/CLI.md.

Дополнительные интеграции инструментов безопасности

Kali Linux MCP, Burp Suite MCP и Snyk интегрируются автоматически после регистрации. Kali обогащает этап Recon и ping_server реальными данными nmap/traceroute. Burp добавляет сырое HTTP-зондирование, внешние обратные вызовы и доказательства прокси. Snyk анализирует метаданные инструментов на наличие строк инъекций, подражания инструментам, жёстко закодированных секретов и 16 других проверок.

Инструкции по настройке см. в docs/INTEGRATIONS.md.

Разработка

Установка в редактируемом режиме:

pip install -e ".[all]"

Запуск сервера и просмотр журналов:

mcpsafetywarden-server 2>server.log

Каждый модуль использует logging.getLogger(__name__). Сервер не вызывает logging.basicConfig сам — настройте логирование в точке входа перед импортом.

Тестирование

pytest tests/ -v

Установите ключ API LLM, чтобы включить тесты с помощью LLM; без него они автоматически пропускаются. Пошаговую проверку классификации, сканирования инъекций, контроля риска и применения политик см. в docs/TESTING.md.

Дополнительная информация

Участие в разработке

Стандарты кода и рекомендации по pull request см. в CONTRIBUTING.md.

Лицензия

Лицензия Apache 2.0. Подробнее см. в LICENSE.