OPNsense MCP

Ein sicherheitsorientierter Remote-Server für das Model Context Protocol für die MVC-API von OPNsense. Er stellt zustandsbehaftetes Streamable HTTP für Remote-Agents bereit, verwendet die native HTTP-Basic-Authentifizierung der API und greift im Fehlerfall auf das Fail-Closed-Prinzip zu, wenn nicht festgestellt werden kann, ob ein OPNsense-Befehl schreibgeschützt ist.

Eine Serverinstanz repräsentiert eine OPNsense-Firewall. Die Firewall-URL und die API-Anmeldedaten bleiben in der Serverumgebung; Agents authentifizieren sich mit einem eigenen Bearer-Token am MCP und können Anfragen nicht auf beliebige Netzwerkziele umleiten. Stellen Sie bei der Verwaltung mehrerer Appliances eine isolierte Instanz pro Firewall bereit.

Architektur

Remote agent --HTTPS + MCP bearer token--> OPNsense MCP --HTTPS + API key/secret--> OPNsense

Der MCP-Endpunkt verwendet den aktuellen Streamable-HTTP-Transport unter /mcp. Die Sitzungen sind zustandsbehaftet, sodass einmalige Mutationspläne an die Sitzung des erzeugenden Agents gebunden bleiben. Sitzungen sind begrenzt, verfallen nach Inaktivität und werden bei jeder HTTP-Anfrage authentifiziert.

Der eingebaute HTTP-Listener ist dafür vorgesehen, hinter einem TLS-Reverse-Proxy, einem Ingress Controller, einem VPN oder einem privaten Overlay zu laufen. Setzen Sie seinen unverschlüsselten HTTP-Port nicht direkt einem nicht vertrauenswürdigen Netzwerk aus.

OPNsense-API-Modell

OPNsense routet API-Anfragen so:

/api/<module>/<controller>/<command>/<parameter...>

Die für die Automatisierung wichtigen Eigenschaften:

• API-Schlüssel verwenden HTTP-Basic-Authentifizierung: Der Schlüssel ist der Benutzername, das Secret das Passwort.

• Der Zugriff bleibt weiterhin durch die OPNsense-ACL-Berechtigungen des Schlüsselinhabers eingeschränkt.

• Anfragen und die meisten Antworten sind JSON. Downloads und Streams können davon abweichen.

• GET und POST sind nicht eindeutig sicheren und unsicheren Operationen zuzuordnen. Manche Lesevorgänge nutzen POST, manche Schreibvorgänge GET.

• Änderbare Modell-Controller stellen üblicherweise get, search, add, set, del und toggle bereit.

• Datensätze vom Typ Array verwenden UUIDs. Ein get ohne UUID liefert oft einen leeren Datensatz.

• Eine erfolgreiche Modell-Mutation legt die Änderung meist nur in der Staging-Konfiguration ab; erst ein eigener apply- oder reconfigure-Aufruf aktiviert sie.

• Modell-Schreibzugriffe geben Werte wie {"result":"saved"} oder {"result":"failed","validations":...} zurück; HTTP 200 allein bedeutet keinen semantischen Erfolg.

• Konfigurationssperre, Modellvalidierung, Revisionskontext und ACL-Prüfungen passieren serverseitig und sind nicht zu umgehen.

Offizielle Referenzen:

• https://docs.opnsense.org/development/api.html

• https://docs.opnsense.org/development/how-tos/api.html

• https://docs.opnsense.org/development/architecture.html

• https://docs.opnsense.org/development/frontend/controller.html

• https://docs.opnsense.org/development/frontend/models_field.html

• https://github.com/Opnsense/core

• https://github.com/opnsense/plugins

Sicherheitsmodell

opnsense_request akzeptiert nur Befehle, die als Lesen klassifiziert sind. Die Klassifizierung erfolgt anhand des Befehls, nicht der HTTP-Methode.

Für Mutationen sind zwei Werkzeuge vorgesehen:

• opnsense_plan_change meldet die konkrete Anfrage und ihr Risiko, ohne OPNsense zu kontaktieren.

• opnsense_execute_change erfordert ein passendes Einmal-Token, das nach fünf Minuten abläuft.

Risikoklassen unterscheiden zwischen Staging-Schreibzugriffen, Aktivierung, einschneidenen Dienst- oder Firmware-Operationen sowie nicht wiedergutzumachenden Reset-/Restore-Operationen. Unbekannte Befehle werden im Fail-Closed-Fall als Mutationen behandelt.

Der Schreibmodus wird außerhalb des Agents konfiguriert:

• disabled erlaubt nur Lesezugriffe.

• planZKähl erlaubt die Mutationsanalyse, erzeugt aber nie ein Ausführungstoken.

• enabled erlaubt die Ausführung mit einem passenden Token.

Verwenden Sie einen eigenen OPNsense-Benutzer und geben Sie diesem nur die effektiven Berechtigungen, die die vorgesehenen Werkzeuge wirklich benötigen. Für reine Lese-Deployments vergeben Sie in OPNsense zusätzlich System: Deny config write (user-config-readonly).

Kuratierte Reads Tools

Der geschützte generische Reads wird durch feste Nur-Lese-Resourcen für übliche Betriebsaufgaben ergänzt:

• opnsense_get_firewall_logsliest strukturierte Paketfilter-Ereignisse.

• opnsense_get_logs liest fensterweise Seiten aus Core- und C-Protokollen, darunter System, config, Gateways, VPN, DNS, DHCP, IDS, Routing und Web-UI-Logs.

• opnsense_list_firewall_rules liest die in der Automations-API sichtbaren Filterregeln.

• opnsense_list_nat_rules liest Destination-, Source-, One-to-One- und NPT-Regeln.

• opnsense_get_route_table liest entweder die aktive Kern-Routing-Tabelle oder die konfigurierten richtigen Routen.

Diese Werkzeuge rufen direkt fest definierte Query-Endpunkte auf. Sie können nicht auf mutierende Gegenstücke wie Log-Löschen, State-Flushes, Regeländerungen oder das Anwenden von Änderungen ausweichen. Die Ergebnisse bleiben an die fD des API-Benutzers freigegebenen OPNsense-ACL-Berechtigungen gebunden.

Einrichtung

npm install
npm run build

Konfigurieren Sie die Umgebung anhand von .env.example. Umgebungsdateien werden nicht automatisch geladen und von Git ignoriert. Erzeugen Sie einen separaten MCP-Token mit openssl rand -hex 32; verwenden Sie dafür nicht ein OPNsense-API-Life.

Bevorzugen Sie ein öffentlich vertrauenswürdiges Zertifikat oder setzen Sie OPNsense_CA_FILE auf das Zertifikat der privaten CA. OPNSENSE_TLS_VERIFY=false ist nur für eine isolierte Entwicklung gedacht.

Führen Sie den Remote-Server auf loopback hinter einem lokalen TLS-Reverse-Proxy aus:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_AUTH_TOKEN=<random-token-at-least-32-characters> \
node dist/index.js

Die nur über http://127.0.0.1:3000/mcp. Veröffentlichen Sie sie über den Reverse-Proxy als HTTPS und übergeben Sie den Token so:

Authorization: Bearer <MCP_AUTH_TOKEN>

Beispielkonfiguration für einen Remote-Client, weil URLs und eigene Header unterstützt:

{
  "mcpServers": {
    "opnsense": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Die Formate für Client-Konfigurationen sind unterschiedlich. Legen Sie das Token in der Secret-Verwaltung des Clients ab, nicht in die Konfigurationsdatei.

Docker Compose

compose.yaml bindet Port 3000 an den Host-Loopvelop, damit ein Reverse-Proxy TLS sicher beenden kann.

export OPNSENSE_URL=https://firewall.example
export OPNSENSE_API_KEY=...
export OPNSENSE_API_SECRET=...
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export MCP_ALLOWED_HOSTS=mcp.example.com
docker compose up -d --build

Wenn Sie sich während der Entwicklung direkt mit localhost:3000 verbinden, nehmen Sie localhost in MCP_ALLOWED_HOSTS auf. Der nicht authentifizierte Health-Endpunkt ist unter /health verfügbar und verrät weder Ziel- noch Zugangsdaten.

Remote-Sicherheit

• MCP_AUTH_TOKEN ist für den HTTP-Transport Pflicht und muss aus mindestens 32 Zeichen bestehen.

• MCP_ALLOWED_HOSTS ist Pflicht beim Binden an eine Nicht-Loopback-Adresse und unterbindet Host-Header-DNS-Rebinding.

• Anfragen mit einem Browser-Origin-Header werden abgewiesen, es sei denn, exact diese Origin steht in MCP_ALLOWED_ORIGINS.

• MCP_MAX_SESSIONS, MCP_SESSION_TTL_MS und MCP_RATE_LIMIT_PER_MINUTE begrenzen die Ressourcennutzung im Remote-Betrieb.

• Behalten Sie OPNSENSE_TLS_VERIFY=true bei. Verwenden Sie für eigene CAs OPNSENSE_CA_FILE, statt die Prüfung abzuschalten.

• Behalten Sie OPNSENSE_WRITE_MODE=disabled für reine Monitoring-DDeployments bei.

• Schränken Sie den OPNsense-API-Benutzer auf effektive ACL privileges ein, einschließlich user-config-readonly, wo angebracht.

• Setzen Sie den MCP-Endpunkt hinter HTTPS, eine Firewallregel und idealerweise hinter VPN oder Privatsnetz.

MCP_ALLOW_UNAUTHEENTICATED=true existiert nur für die isolierte lokale Entwicklung und darf niemals für einen remote Exposed Listener verwendet werden.

Stdio-Kompatibilität

Lokale Clients können den Server weiterhin als Subprozess starten:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_TRANSPORT=stdio \
node dist/index.js

Schrift sprache

• OPNSENSE_URL: feste Basis URL der Firewall.

• OPNSENSE_API_KEY: API-Schlüssel für den dedizierten OPNsense-Benutzer.

• OPrpSENSE_API_SECRET: API-Secret key des Schlüssels.

• OPNsense_WRITE_MODE: disabled, plan oder enabled.

• OPNSENSE_CA_FILE: optionale PEM-Datei der privaten CA.

• OPNsense_TLS_VERIFY: Standard true.

• MCP_TRANSPORT: standard http, alternativ stdio.

• MCP_HOST: Listener-Adresse, Standard 127.0.0.1.

• MCP_PORT: Listener-Port, Standard 3000.

• MCP_PATH: Pfad des MCP-Endpunkts, Standard /mcp.

• MCP_AUTH_TOKEN: Bearer Token für das MCP-Remote-Agents.

• MCP_ALLOWED_HOSTS: kommgetrennte Hostnames für den HTTP-Host-Header.

• MCP_ALLOWED_ORIGINS: kommgesepararte Browser-Origins; leer verurteilt Anfragen von Browser.

• MCP_MAX_SESSIONS: maximale Parallelsitzungen, Standard 100.

• MCP_SESSION_TTL_MS: Lebensdauer inaktiveres Sitzung, Standard eine Stunde.

• MCP_RATE_LIMIT_PER_MINUTE: HTTP-Anfragelimit pro Client, Standard 120.

Ein Lesezugriff auf den Systemstatus sieht z. B. so aus:

{
  "module": "core",
  "controller": "system",
  "command": "status"
}

Aktuelle Grenzen

• OPNsense veröffentlicht keinen vollständigen OpenAPI-Vertrag. Die generierte Referenz zeigt Routen und vermutliche Methoden, aber oft keine Body-Schemas.

• Plugin-Endpunkte existieren nur, wenn die entsprechenden Pakete installiert und ACL autorisiert sind.

• Die semantische Antwortvalidierung ist noch nicht endpunktspezifisch.

• Die lexikalische Risikoklassifikation ist absichtlich konservativ. Die kuratierten Werkzeuge sollten später einen auditurten Endpunkt-Katalog erklären mit expliziten Request- und Response-Schemata.

• Pläne verringern versehentliche oder angeletterte Ausführungen, aber MCP-Hosts sollten Beschädigungsbestätigungen Menschen weiterfallen lassen.

• Remote-Authentifizerung verwendet derzeit ein statisches, deploymentweites Bearer-Tokenmusiationsserver. Verwenden Sie getrennte Deployments oder authentifizierende Reverse-Proxys, wenn Agents unterschiedliche Identitäten brauchen.

• Der Sitzungszustand liegt im Arbeitsspeicher und wird nicht über Replicas verteilt. Betreiben Sie eine einzelne Replica, sofern kein externer Sitzungsstorage und Routing-Affinität vorhanden sind.