ToolFence

Локальный межсетевой экран с отказоустойчивым закрытием для вызовов инструментов MCP.

ToolFence помещает политики минимальных привилегий и одобрение человека между AI-агентами и stdio-серверами MCP. Он разрешает безопасные операции, блокирует опасные и запрашивает разрешение перед передачей вызовов, требующих человеческого решения — без необходимости изменять код клиента или сервера MCP.

ALLOW  Read ./src/index.ts
DENY   Read ~/.ssh/id_rsa
ASK    Run npm install
DENY   Run sudo rm -rf ...

Зачем нужен ToolFence

• Семантические политики: нормализуют распространённые вызовы инструментов Filesystem, Shell, Git и HTTP в операции, такие как fs.read, shell.exec, git.write и net.request, а затем сопоставляют пути, точные аргументы команд, хосты и HTTP-методы.

• Детерминированное применение: deny переопределяет другие совпадения, многозапросные запросы оцениваются как единое целое, а неизвестные или неоднозначные действия завершаются с отказом (fail closed).

• Одобрение человека: используйте аутентифицированный локальный Broker для одноразовых или сессионных решений; сессионные одобрения привязаны к схеме инструмента и аннулируются при её изменении.

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

• Политики, которые можно тестировать: создавайте, проверяйте, объясняйте и проводите регрессионное тестирование YAML-политик из командной строки.

Related MCP server: cordon

Статус

Версия 0.2.0 — первый стабильный релиз с открытым исходным кодом. Он включает отменяемые одобрения через локальный Broker, консервативные адаптеры Filesystem/Shell/Git/HTTP, команды создания и разработки политик, сессионные одобрения, привязанные к схеме, и реальные интеграционные тесты MCP.

ToolFence не является песочницей для вредоносного процесса сервера MCP: вышестоящий процесс по-прежнему работает с правами текущего пользователя операционной системы.

Поскольку ToolFence запускает настраиваемые пользователем процессы и управляет возможностями Shell, Git и HTTP, npm-пакет прозрачно объявлен как двойного назначения. См. DISCLOSURE для информации о предполагаемом легитимном использовании и границах безопасности.

Установка

Имя npm-пакета — toolfence-mcp; команда — toolfence.

npm install -g toolfence-mcp

Для локальной разработки:

npm install
npm run build
npm link

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

Создайте консервативную начальную политику, просмотрите её, затем оберните любой stdio-сервер MCP:

toolfence policy init
toolfence policy check --policy ./toolfence.yaml

Сгенерированный файл никогда не заменяет существующую политику. Более широкий аннотированный пример см. в examples/policy.yaml.

toolfence wrap \
  --policy ./toolfence.yaml \
  --server filesystem \
  --workspace "$PWD" \
  -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

Конфигурация клиента MCP выглядит так:

{
  "mcpServers": {
    "filesystem": {
      "command": "toolfence",
      "args": [
        "wrap",
        "--policy", "/absolute/path/policy.yaml",
        "--server", "filesystem",
        "--workspace", "/absolute/path/project",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/project"
      ]
    }
  }
}

ToolFence резервирует stdout для сообщений MCP JSON-RPC. Диагностика и stderr вышестоящего процесса остаются на stderr. Запустите персональный Broker и терминал одобрения в отдельных терминалах:

toolfence broker
toolfence approvals

wrap по умолчанию использует Broker. Если он отсутствует, несовместим, не аутентифицирован, отключён или истекло время ожидания, решение ask завершается с отказом. Используйте --approval tty только когда требуется прямое одобрение через /dev/tty. toolfence status проверяет подключение к Broker, версию протокола и права доступа к сокету.

Политика

version: 1
default: ask

rules:
  - id: deny-dotenv
    effect: deny
    operations: [fs.read, fs.write]
    resources: ["**/.env", "**/.env.*"]

  - id: allow-workspace-read
    effect: allow
    operations: [fs.read]
    resources: ["${workspace}/**"]

  - id: allow-tests
    effect: allow
    operations: [shell.exec]
    commands:
      - [npm, test]

  - id: allow-git-inspection
    effect: allow
    operations: [git.read]

  - id: allow-read-api
    effect: allow
    operations: [net.request]
    hosts: ["api.example.com", "*.internal.example.com"]
    methods: [GET, HEAD]

Правила оцениваются детерминированно:

1. Каждое совпадающее правило deny переопределяет все остальные совпадения. Правило ресурса deny срабатывает, когда любой запрошенный ресурс защищён.

2. В противном случае побеждает первое совпавшее правило.

3. Если ничего не совпало, используется default.

Правила ресурсов allow и ask требуют совпадения каждого запрошенного ресурса, поэтому многозапросный вызов не может использовать один разрешённый путь для проведения несанкционированного пути.

Пути файловой системы канонизируются перед сопоставлением, включая существующие символические ссылки. Для разрешённых команд используется точное сопоставление argv; составные или заключённые в кавычки строки оболочки не считаются безопасными argv и возвращаются к решению по умолчанию.

Поддерживаемые операции v0.2: fs.read, fs.write, fs.delete, shell.exec, git.read, git.write, git.remote, net.request и unknown. Неоднозначные команды Git, недействительные URL и нераспознанные инструменты завершаются с отказом через shell.exec или unknown.

Разработка политик

toolfence policy init [--policy ./toolfence.yaml]
toolfence policy check --policy ./examples/policy.yaml
toolfence policy explain --policy ./examples/policy.yaml --action ./action.json
toolfence policy test --policy ./examples/policy.yaml --cases ./policy-cases.yaml

init создаёт консервативную политику, не перезаписывая существующий файл. check проверяет YAML, строгие правила схемы, переменные, дублирующиеся ID и недопустимые комбинации полей сети. explain выводит совпавшие правила и окончательное решение. test запускает декларативные тесты и завершается с ненулевым кодом при любом несовпадении.

Журнал аудита

Файл аудита по умолчанию — .toolfence/audit.jsonl в рабочей области. Он записывает имена операций, затронутые пути, идентификатор инструмента, окончательные решения политик и SHA-256 хеши результатов вышестоящего процесса. Исходные аргументы инструмента, аргументы команд и исходные результаты намеренно опущены для уменьшения утечки секретов.

Используйте --audit /path/to/audit.jsonl для выбора другого пути.

Границы безопасности

ToolFence v0.2 снижает случайное или вызванное внедрением в промпт неправильное использование инструментов, когда вызов инструмента проходит через этот прокси. Он не предотвращает прямое чтение файлов, переменных окружения или сети процессом вышестоящего сервера. Изоляция процессов, фильтрация окружения и сетевые контроли относятся к более поздней фазе песочницы.

Дополнительные текущие ограничения:

• только транспорт stdio

• поддержка локального Broker только для POSIX; Windows остаётся неинтерактивным и с отказоустойчивым закрытием

• пакетные сообщения JSON-RPC отклоняются

• редактирование секретов в выводе пока отсутствует; исходные результаты передаются без изменений

• адаптер HTTP MCP должен предоставлять адрес перенаправления (например, как redirectUrl), чтобы ToolFence мог переоценить его

Разработка

Архитектура, модель угроз, инварианты безопасности и план реализации v0.2 поддерживаются в руководстве по разработке.

npm run typecheck
npm test
npm run build
npm pack --dry-run
npm audit --omit=dev

Полная стратегия проверки находится в TESTING.md, а запись проверки релиза/безопасности — в REVIEW.md. См. CONTRIBUTING.md, SECURITY.md, CHANGELOG.md и RELEASING.md перед внесением вклада, сообщением об уязвимости или публикацией релиза.

Лицензия

MIT