ToolFence

Un cortafuegos local que falla cerrado para llamadas a herramientas MCP.

ToolFence sitúa políticas de mínimo privilegio y aprobación humana entre agentes de IA y servidores MCP stdio. Permite operaciones seguras, bloquea las peligrosas y solicita permiso antes de reenviar llamadas que requieren decisión humana—sin necesidad de modificar el código del cliente o servidor MCP.

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

Por qué ToolFence

• Políticas semánticas: normaliza llamadas comunes de los sistemas Filesystem, Shell, Git y HTTP en operaciones como fs.read, shell.exec, git.write y net.request, y luego compara rutas, argumentos exactos de comandos, hosts y métodos HTTP.

• Aplicación determinista: deny prevalece sobre otras coincidencias; las solicitudes de múltiples recursos se evalúan en conjunto; acciones desconocidas o ambiguas fallan cerradas.

• Aprobación humana: utiliza un Broker local autenticado para decisiones de una sola vez o de sesión; las aprobaciones de sesión están vinculadas al Esquema de la herramienta y se invalidan cuando ese Esquema cambia.

• Auditoría respetuosa con la privacidad: registra la identidad de la herramienta, los recursos afectados, las decisiones de política y los hashes de los resultados sin almacenar argumentos ni resultados en bruto.

• Políticas comprobables: genera, valida, explica y hace pruebas de regresión de políticas YAML desde la CLI.

Related MCP server: cordon

Estado

La versión 0.2.0 es la primera versión estable de código abierto. Incluye aprobaciones cancelables mediante un Broker local, adaptadores conservadores para Filesystem/Shell/Git/HTTP, comandos para creación y desarrollo de políticas, aprobaciones de sesión vinculadas al Esquema y pruebas de integración reales con MCP.

ToolFence no es un entorno aislado para un proceso de servidor MCP malicioso: el proceso ascendente sigue ejecutándose con los permisos del sistema operativo del usuario actual.

Debido a que ToolFence inicia procesos configurados por el usuario y media capacidades de Shell, Git y HTTP, el paquete npm se declara transparentemente como de doble uso. Consulte DISCLOSURE para conocer el uso legítimo previsto y el límite de seguridad.

Instalar

El nombre del paquete npm es toolfence-mcp; el comando es toolfence.

npm install -g toolfence-mcp

Para desarrollo local:

npm install
npm run build
npm link

Inicio rápido

Cree una política inicial conservadora, revísela y luego envuelva cualquier servidor MCP stdio:

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

El archivo generado nunca reemplaza una política existente. Para un ejemplo anotado más amplio, consulte examples/policy.yaml.

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

Una configuración de cliente MCP tiene este aspecto:

{
  "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 reserva stdout para mensajes JSON-RPC de MCP. Los diagnósticos y el stderr ascendente permanecen en stderr. Inicie el Broker por usuario y el terminal de aprobación en terminales separadas:

toolfence broker
toolfence approvals

wrap utiliza el Broker por defecto. Si falta, es incompatible, no está autenticado, está desconectado o supera el tiempo de espera, una decisión ask falla cerrada. Use --approval tty solo cuando se desee aprobación directa por /dev/tty. toolfence status verifica la conectividad del Broker, la versión del protocolo y los permisos del Socket.

Política

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]

Las reglas se evalúan de forma determinista:

1. Toda regla deny que coincida anula todas las demás coincidencias. Una regla de recurso deny coincide cuando cualquier recurso solicitado está protegido.

2. De lo contrario, gana la primera regla que coincida.

3. Si nada coincide, se usa el default.

Las reglas de recursos allow y ask requieren que cada recurso solicitado coincida, por lo que una llamada de varios archivos no puede usar una ruta permitida para arrastrar una ruta no autorizada.

Las rutas del sistema de archivos se canonican antes de la comparación, incluidos los enlaces simbólicos existentes. Se usa coincidencia exacta de argv para comandos permitidos; las cadenas de shell compuestas o entrecomilladas no se tratan como argv seguras y recurren a la decisión por defecto.

Las operaciones compatibles con v0.2 son fs.read, fs.write, fs.delete, shell.exec, git.read, git.write, git.remote, net.request y unknown. Los comandos Git ambiguos, las URL no válidas y las herramientas no reconocidas fallan cerradas a través de shell.exec o unknown.

Desarrollo de políticas

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 crea una política conservadora sin sobrescribir un archivo existente. check valida YAML, reglas estrictas del Esquema, variables, IDs duplicados y combinaciones inválidas de campo de red. explain muestra las reglas coincidentes y la decisión final. test ejecuta casos declarativos y sale con código distinto de cero en caso de discrepancia.

Registro de auditoría

El archivo de auditoría predeterminado es .toolfence/audit.jsonl bajo el espacio de trabajo. Registra nombres de operación, rutas afectadas, identidad de la herramienta, decisiones de política finales y hashes SHA-256 de los resultados ascendentes. Los argumentos brutos de la herramienta, los argumentos de comandos y los resultados brutos se omiten intencionadamente para reducir la fuga de secretos.

Use --audit /path/to/audit.jsonl para seleccionar una ruta diferente.

Límite de seguridad

ToolFence v0.2 reduce el uso indebido accidental o inducido por inyección de instrucciones de la herramienta cuando la llamada cruza este proxy. No evita que el proceso del servidor ascendente lea directamente archivos, variables de entorno o la red. El aislamiento de procesos, el filtrado de entorno y los controles de red pertenecen a una fase de sandbox posterior.

Limitaciones adicionales actuales:

• solo transporte stdio

• el soporte del Broker local es solo POSIX; Windows permanece no interactivo y falla cerrado

• los mensajes JSON-RPC por lotes se rechazan

• aún no hay redacción de secretos en la salida; los resultados brutos se reenvían sin cambios

• un adaptador MCP HTTP debe exponer un destino de redirección (por ejemplo, como redirectUrl) para que ToolFence lo reevalúe

Desarrollo

La arquitectura, el modelo de amenazas, los invariantes de seguridad y el plan de implementación de v0.2 se mantienen en la guía de desarrollo.

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

La estrategia de validación completa está en TESTING.md, y el registro de versiones/revisiones de seguridad está en REVIEW.md. Consulte CONTRIBUTING.md, SECURITY.md, CHANGELOG.md y RELEASING.md antes de contribuir, reportar una vulnerabilidad o publicar una versión.

Licencia

MIT