⚠️ Этот репозиторий перемещён. Активная разработка продолжается в ScopeBlind/scopeblind-gateway.

Этот личный форк может отставать от канонического репозитория. Пожалуйста, используйте основной репозиторий для вопросов, pull request'ов и актуального кода.

protect-mcp

Шлюз безопасности для MCP-серверов. По умолчанию работает в теневом режиме с записью журнала, поддерживает политики для каждого инструмента, опциональное локальное подписание на Ed25519 и удобный для верификации аудит.

Текущий путь CLI: обёртка любого stdio MCP-сервера в прозрачный прокси. В теневом режиме записывает каждый вызов tools/call и пропускает всё. Добавьте файл политики для применения правил для каждого инструмента. Выполните protect-mcp init для генерации локальных ключей подписи и конфигурации, чтобы шлюз также мог выдавать подписанные квитанции.

Быстрый старт

# Оборачивание существующей конфигурации OpenClaw / MCP в пригодный пакет
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Теневой режим — логировать каждый вызов инструмента, ничего не применять
npx protect-mcp -- node my-server.js

# Генерация ключей и шаблона конфигурации для локального подписания
npx protect-mcp init

# Теневой режим с включённым локальным подписанием
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Режим принуждения
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Экспорт офлайн-верифицируемого аудит-пакета
npx protect-mcp bundle --output audit.json

Что он делает

protect-mcp располагается между вашим MCP-клиентом и сервером в качестве stdio-прокси:

MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server

Он перехватывает JSON-RPC запросы tools/call и:

• Теневой режим (по умолчанию): логирует каждый вызов инструмента и пропускает всё
• Режим принуждения: применяет правила политики для каждого инструмента, такие как block, rate_limit и min_tier
• Опциональное локальное подписание: при настроенном подписании выводит подписанную квитанцию Ed25519 вместе со структурированным журналом

Все остальные сообщения MCP (initialize, tools/list, уведомления) проходят прозрачно.

Что поставляется сегодня

• Политики для каждого инструмента — блокируйте опасные инструменты, ограничивайте частоту дорогих и устанавливайте требования к минимальному уровню допуска
• Структурированные журналы решений — каждое решение выводится в stderr с пометкой [PROTECT_MCP]
• Опциональные локальные подписанные квитанции — генерируются при запуске с политикой, содержащей signing.key_path, сохраняются в .protect-mcp-receipts.jsonl и доступны по адресу http://127.0.0.1:9876/receipts
• Офлайн-верификация — проверяйте квитанции или пакеты с помощью npx @veritasacta/verify
• Без регистрации — локальные ключи, локальная политика, локальный процесс

Текущие ограничения возможностей

Это важно учитывать перед развёртыванием или обсуждением с пользователями:

• Подписание не включается автоматически на пути npx protect-mcp -- .... Этот путь логирует решения в теневом режиме. Для локального подписания выполните npx protect-mcp init, затем запустите шлюз с сгенерированным файлом политики.
• Проверки политик с учётом уровней допуска работают, но допуск манифестов не встроен в стандартный путь CLI/stdio. По умолчанию CLI устанавливает сессию в unknown, если интеграция с хостом не вызывает API допуска программно.
• Конфигурация учётных данных в настоящее время проверяет ссылки на учётные данные из переменных окружения и записывает метки учётных данных в журналы/квитанции. Универсальная инъекция в произвольные stdio-инструменты зависит от адаптера и не выполняется стандартным прокси-путём.
• Внешние адаптеры PDP и помощники по аудит-пакетам существуют как экспортируемые утилиты. Они ещё не полностью встроены в стандартный путь CLI.

Файл политики

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

Правила политики

Имена инструментов сопоставляются точно, с "*" в качестве подстановочного знака.

Конфигурация MCP-клиента

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

Та же схема — замените команду сервера на protect-mcp, оборачивающую его.

Параметры CLI

protect-mcp [options] -- <command> [args...]
protect-mcp init

Commands:
  init              Generate Ed25519 keypair + config template
  status            Show decision stats and local passport identity
  digest            Generate a local human-readable summary
  receipts          Show recent persisted signed receipts
  bundle            Export an offline-verifiable audit bundle

Options:
  --policy <path>   Policy/config JSON file
  --slug <slug>     Service identifier for logs/receipts
  --enforce         Enable enforcement mode (default: shadow)
  --verbose         Enable debug logging
  --help            Show help

Программные хуки

Библиотека также предоставляет примитивы, которые ещё не встроены в стандартный путь CLI:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

Используйте их, если хотите добавить:

• допуск манифестов до начала сессии
• внешний PDP (OPA, Cerbos или универсальный HTTP-вебхук)
• пользовательские интеграции с брокером учётных данных
• экспорт аудит-пакета вокруг собственного хранилища квитанций

Журналы решений и квитанции

Каждый вызов инструмента выводит структурированный JSON в stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

Если подписание настроено, за ним следует подписанная квитанция:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

Проверьте с помощью CLI: npx @veritasacta/verify receipt.json Проверьте в браузере: scopeblind.com/verify

Аудит-пакеты

Пакет включает помощника для самодостаточных аудит-пакетов:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

Используйте createAuditBundle() для ваших собственных собранных подписанных квитанций.

Философия

• Сначала тень. Узнайте, что делают агенты, прежде чем что-либо применять.
• Квитанции лучше, чем журналы только на панелях. Подписанные артефакты должны быть независимо проверяемыми.
• Держите утверждения сжатыми. Стандартный путь CLI пока не делает всё, что будет поддерживать долгосрочная архитектура.
• Наслаивайтесь поверх существующей аутентификации. Не вырывайте свой стек ради контроля и доказательств.

Привязанные к инцидентам пакеты политик

Поставляются с protect-mcp — каждый предотвращает реальную атаку:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

Полное соответствие OWASP Agentic Top 10: scopeblind.com/docs/owasp

BYOPE: Внешние механизмы политик

Поддерживает OPA, Cerbos, Cedar (AWS AgentCore) и универсальные HTTP-эндпоинты:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

Стандарты и интеллектуальная собственность

• IETF Internet-Draft: draft-farley-acta-signed-receipts-00 — Подписанные квитанции решений для управления доступом между машинами
• Статус патентов: 4 предварительных австралийских патента на рассмотрении (2025-2026), охватывающих квитанции решений с настраиваемым раскрытием, шлюз вызова инструментов, манифесты агентов и переносимую идентичность
• Верификация: лицензия MIT — npx @veritasacta/verify --self-test

Лицензия

MIT — свободно используйте, изменяйте, распространяйте и создавайте производные без ограничений.

scopeblind.com · npm · GitHub · IETF Draft