MCPGuard-Lab

Экспериментальный проект по безопасности вызова инструментов MCP, основанный на реальном SDK mcp==2.0.0. Он не зависит от внешних больших языковых моделей или API-ключей, реализуя белый список инструментов, проверку параметров, границы файлов, защиту от SSRF, подтверждение чувствительных операций, десенсибилизацию вывода, обнаружение отравления описания инструментов и аудит JSONL с помощью детерминированных стратегий, а также использует регрессионные тесты для проверки того, что защита не нарушена последующими изменениями.

Границы использования: данный проект предназначен только для локальных экспериментов, авторизованного тестирования и исследований защиты и не содержит функций атак на неавторизованные цели.

Реализованные возможности

• Полноценное тестирование взаимодействия между сервером MCP 2.0 stdio и реальным клиентом.

• Шесть демонстрационных инструментов: безопасные вычисления, чтение файлов в корневом каталоге, запрос заметок, запрос к публичным URL, проверка метаданных инструмента, запись заметки после подтверждения.

• Белый список инструментов и строгая проверка JSON Schema с отклонением дополнительных параметров.

• Нормализация путей к файлам с отклонением абсолютных путей, обхода каталогов и выхода за пределы корневого каталога.

• Проверка протокола URL, информации о пользователе, порта, результатов разрешения DNS с отклонением адресов loopback, частных сетей, link-local и других непубличных адресов.

• Контроль доступа для операции записи confirmed=true.

• Явная маркировка вывода из ненадежных инструментов; рекурсивная десенсибилизация паролей, токенов, API-ключей и учетных данных Bearer.

• Обнаружение сигналов внедрения с высоким риском в именах/описаниях инструментов.

• Запись каждого решения в JSONL: идентификатор запроса, время, инструмент, параметры, разрешено/отклонено, причина и результат.

• Модульные/интеграционные тесты pytest и повторяемый отчет о регрессии атак.

Related MCP server: meok-mcp-injection-scan-mcp

Архитектура

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

Основной принцип — «сначала решение, затем выполнение, затем очистка вывода, полное отслеживание». Текст подсказки не получает дополнительных привилегий; привилегии определяются белым списком и стратегией в коде.

Быстрый запуск (Windows)

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

Также можно запустить напрямую:

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

Отчеты создаются в:

• reports/regression-report.md

• reports/regression-report.json

• reports/regression-audit.jsonl

Пример конфигурации MCP-клиента

Сначала выполните pip install -e ., затем замените следующую структуру на абсолютный путь текущего репозитория:

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

Реальные границы

• Обнаружение отравления описания инструмента представляет собой уровень правил с высоким уровнем сигнала и не может заменить ручную проверку и фиксированный белый список.

• confirmed=true — это явный контроль доступа для подтверждения в локальном эксперименте; в производственной среде следует использовать учетные данные подтверждения, выданные хост-интерфейсом/системой идентификации, которые не могут быть подделаны моделью.

• В настоящее время URL-инструмент отключает перенаправления, чтобы избежать перехода на внутреннюю сеть после прохождения проверки первого перехода; производственная версия должна также ограничивать размер ответа, тип контента и исходящую сеть.

• Маркировка ненадежного контента может снизить риск «использования данных в качестве инструкций», но конечный хост-агент по-прежнему должен соблюдать границы доверия.

• Регрессионные данные представляют только фиксированные тестовые примеры в репозитории и не гарантируют блокировку всех инъекций подсказок или всех рисков MCP.

Содержание

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

Ссылки

• SDK протокола контекста модели на Python

• AgentDojo