ToolFence

Ein lokaler, fail-closed Firewall für MCP-Toolaufrufe.

ToolFence setzt Least-Privilege-Richtlinien und menschliche Genehmigung zwischen KI-Agenten und stdio-MCP-Server. Es erlaubt sichere Operationen, blockiert gefährliche und fragt, bevor es Aufrufe weiterleitet, die eine menschliche Entscheidung benötigen – ohne dass Codeänderungen am MCP-Client oder -Server erforderlich sind.

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

Warum ToolFence

• Semantische Richtlinien: normalisieren gängige Filesystem-, Shell-, Git- und HTTP-Toolaufrufe in Operationen wie fs.read, shell.exec, git.write und net.request und gleichen dann Pfade, exakte Befehlsargumente, Hosts und HTTP-Methoden ab.

• Deterministische Durchsetzung: deny überschreibt andere Übereinstimmungen, Multi-Ressourcen-Anfragen werden als Einheit ausgewertet und unbekannte oder mehrdeutige Aktionen schlagen mit 'fail closed' fehl.

• Menschliche Genehmigung: Verwenden Sie einen authentifizierten lokalen Broker für einmalige oder Sitzungsentscheidungen; Sitzungsgenehmigungen sind an das Tool-Schema gebunden und werden ungültig, wenn sich dieses Schema ändert.

• Datenschutzbewusste Prüfung: Zeichnen Sie Tool-Identität, betroffene Ressourcen, Richtlinienentscheidungen und Ergebnishashes auf, ohne rohe Argumente oder Ergebnisse zu speichern.

• Richtlinien, die Sie testen können: Generieren, validieren, erklären und regressionstesten Sie YAML-Richtlinien über die CLI.

Related MCP server: cordon

Status

Version 0.2.0 ist die erste stabile Open-Source-Veröffentlichung. Sie enthält abbrechbare Genehmigungen über einen lokalen Broker, konservative Filesystem-/Shell-/Git-/HTTP-Adapter, Befehle zur Richtlinienerstellung und -entwicklung, schemagebundene Sitzungsgenehmigungen und echte MCP-Integrationstests.

ToolFence ist keine Sandbox für einen böswilligen MCP-Serverprozess: Der vorgelagerte Prozess läuft weiterhin mit den Betriebssystemberechtigungen des aktuellen Benutzers.

Da ToolFence benutzerkonfigurierte Prozesse startet und Shell-, Git- und HTTP-Fähigkeiten vermittelt, wird das npm-Paket transparent als Dual-Use deklariert. Siehe DISCLOSURE für den beabsichtigten legitimen Gebrauch und die Sicherheitsgrenze.

Installation

Der npm-Paketname ist toolfence-mcp; der Befehl ist toolfence.

npm install -g toolfence-mcp

Für die lokale Entwicklung:

npm install
npm run build
npm link

Schnellstart

Erstellen Sie eine konservative Startrichtlinie, überprüfen Sie sie und wickeln Sie dann einen beliebigen stdio-MCP-Server mit wrap ein:

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

Die generierte Datei ersetzt niemals eine vorhandene Richtlinie. Ein umfassenderes kommentiertes Beispiel finden Sie unter examples/policy.yaml.

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

Eine MCP-Client-Konfiguration sieht wie folgt aus:

{
  "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 reserviert stdout für MCP-JSON-RPC-Nachrichten. Diagnose und vorgelagerter stderr bleiben auf stderr. Starten Sie den benutzerspezifischen Broker und das Genehmigungsterminal in separaten Terminals:

toolfence broker
toolfence approvals

wrap verwendet standardmäßig den Broker. Wenn er fehlt, inkompatibel, nicht authentifiziert, getrennt oder zeitüberschreitend ist, schlägt eine ask-Entscheidung mit 'fail closed' fehl. Verwenden Sie --approval tty nur, wenn eine direkte /dev/tty-Genehmigung gewünscht wird. toolfence status überprüft die Broker-Konnektivität, Protokollversion und Socket-Berechtigungen.

Richtlinie

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]

Regeln werden deterministisch ausgewertet:

1. Jede übereinstimmende deny-Regel überschreibt alle anderen Übereinstimmungen. Eine Deny-Ressourcenregel stimmt überein, wenn eine angeforderte Ressource geschützt ist.

2. Andernfalls gewinnt die erste übereinstimmende Regel.

3. Wenn nichts übereinstimmt, wird default verwendet.

Allow- und Ask-Ressourcenregeln erfordern, dass jede angeforderte Ressource übereinstimmt, sodass ein Multi-Datei-Aufruf nicht einen erlaubten Pfad verwenden kann, um einen nicht autorisierten Pfad zu transportieren.

Dateisystempfade werden vor dem Abgleich kanonisiert, einschließlich vorhandener symbolischer Links. Für erlaubte Befehle wird exakter argv-Abgleich verwendet; zusammengesetzte oder in Anführungszeichen gesetzte Shell-Strings werden nicht als sichere argv behandelt und fallen auf die Standardentscheidung zurück.

Unterstützte v0.2-Operationen sind fs.read, fs.write, fs.delete, shell.exec, git.read, git.write, git.remote, net.request und unknown. Mehrdeutige Git-Befehle, ungültige URLs und nicht erkannte Tools schlagen mit 'fail closed' über shell.exec oder unknown fehl.

Richtlinienentwicklung

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 erstellt eine konservative Richtlinie, ohne eine vorhandene Datei zu überschreiben. check validiert YAML, strenge Schema-Regeln, Variablen, doppelte IDs und ungültige Netzwerk-Feld-Kombinationen. explain gibt übereinstimmende Regeln und die endgültige Entscheidung aus. test führt deklarative Fälle aus und beendet sich mit einem Nicht-Null-Exitcode bei jeder Abweichung.

Audit-Log

Die Standard-Audit-Datei ist .toolfence/audit.jsonl im Arbeitsbereich. Sie zeichnet Operationsnamen, betroffene Pfade, Tool-Identität, endgültige Richtlinienentscheidungen und SHA-256-Hashes der vorgelagerten Ergebnisse auf. Rohe Tool-Argumente, Befehlsargumente und rohe Ergebnisse werden absichtlich weggelassen, um die Offenlegung von Geheimnissen zu reduzieren.

Verwenden Sie --audit /path/to/audit.jsonl, um einen anderen Pfad auszuwählen.

Sicherheitsgrenze

ToolFence v0.2 reduziert versehentlichen oder prompt-injizierten Tool-Missbrauch, wenn der Tool-Aufruf diesen Proxy durchläuft. Es verhindert nicht, dass der vorgelagerte Serverprozess direkt Dateien, Umgebungsvariablen oder das Netzwerk liest. Prozessisolierung, Umgebungsfilterung und Netzwerkkontrollen gehören zu einer späteren Sandbox-Phase.

Zusätzliche aktuelle Einschränkungen:

• nur stdio-Transport

• Lokale Broker-Unterstützung ist nur POSIX; Windows bleibt nicht interaktiv und schlägt mit 'fail closed' fehl

• JSON-RPC-Batch-Nachrichten werden abgelehnt

• noch keine Schwärzung von Ausgabegeheimnissen; rohe Ergebnisse werden unverändert weitergeleitet

• Ein HTTP-MCP-Adapter muss ein Weiterleitungsziel (z. B. als redirectUrl) bereitstellen, damit ToolFence es neu bewerten kann

Entwicklung

Die Architektur, das Bedrohungsmodell, die Sicherheitsinvarianten und der Implementierungsplan für v0.2 werden im Entwicklungsleitfaden verwaltet.

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

Die vollständige Validierungsstrategie finden Sie in TESTING.md, und der Aufzeichnungen zu Veröffentlichungen/Sicherheitsüberprüfungen finden Sie in REVIEW.md. Lesen Sie CONTRIBUTING.md, SECURITY.md, CHANGELOG.md und RELEASING.md, bevor Sie einen Beitrag leisten, eine Sicherheitslücke melden oder eine Veröffentlichung herausgeben.

Lizenz

MIT