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

Этот личный форк может отставать от канонического репозитория. Пожалуйста, используйте основной репозиторий для сообщений об ошибках, запросов на слияние (pull requests) и получения актуального кода.

protect-mcp

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

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

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

# Wrap an existing OpenClaw / MCP config into a usable pack
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Generate keys + config template for local signing
npx protect-mcp init

# Shadow mode with local signing enabled
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Enforce mode
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Export an offline-verifiable audit bundle
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"
    }
  }
}

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

Имена инструментов должны совпадать точно, "*" используется как подстановочный знак (wildcard).

Конфигурация 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