OPNsense Guard

opnsense-guard-mcp

A safety-first MCP server for OPNsense 26.7+.

**Read-only by default. Every write is planned, policy-checked, logged, and

auto-reverted unless you confirm it.**

Status: alpha. Tested against a live OPNsense 26.7.4 with least-privilege API users: read tools, policy file, change planning with diffs, applying changes with verification and automatic revert, crash recovery, and a hash-chained audit log, over stdio or authenticated HTTPS. See DESIGN.md.

Not affiliated with Deciso B.V. "OPNsense" is a trademark of Deciso B.V.

What makes it different

Quick start (read-only)

1. In OPNsense (System → Access → Users), create a user with a scrambled password, no group (not admins) and these privileges, then create an API key for it. Skip any that aren't installed; the matching tool just reports "forbidden".

Most OPNsense privileges are not view-only (*Firewall: Aliases* is an exception): several of these also allow edits through the API. The server only sends GET requests with this key, except a search POST to two exact endpoints (diagnostics/firewall/query_states, firewall/filter/searchRule) with a body it builds itself (current, rowCount, searchPhrase); OPNsense answers those lists properly only over POST. Still keep the list short: the privileges are what OPNsense itself enforces.

1. Install:

   pipx install opnsense-guard-mcp

1. Configure (copy .env.example to .env, or set env vars):

   OPNSENSE_URL=https://firewall.example.internal

OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... OPNSENSE_CA_BUNDLE=/path/to/firewall-ca.pem # or OPNSENSE_VERIFY_SSL=false

1. Check the config (does not contact the firewall):

   opnsense-guard-mcp --check

1. Add to your MCP client, e.g. Claude Code:

   claude mcp add opnsense -- opnsense-guard-mcp --env-file /path/to/.env

HTTP mode (shared server)

HTTP never runs without authentication. The server refuses to start if:

• there are no tokens, or
• it binds to a non-loopback address without TLS (override with MCP_ALLOW_PLAINTEXT=true only behind a TLS proxy).

1. Create a token per client. It is printed once; only its SHA-256 is stored:

   opnsense-guard-mcp token new --name laptop --scope read

token list shows names and scopes; token revoke --name laptop takes effect on the next request, no restart needed.

1. Start the server:

   MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8848 \

MCP_TLS_CERT=server.pem MCP_TLS_KEY=server.key \ opnsense-guard-mcp

1. Point the client at https:// :8848/mcp with header Authorization: Bearer .

Repeated failed logins from one IP (10 a minute) are throttled with HTTP 429.

Claude Code and a private CA: Claude Code (Node) ignores the Windows/macOS certificate store for MCP servers. Point NODE_EXTRA_CA_CERTS at your CA file in the env block of ~/.claude/settings.json, then fully quit and reopen Claude, or the connection fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Running in Docker

The image runs as a non-root user and keeps its audit log, change journal and tokens in /data.

docker build -t opnsense-guard-mcp .

stdio, for a local MCP client

docker run -i --rm --env-file .env -v guard-data:/data opnsense-guard-mcp

HTTP: create a token, then serve (put the TLS files in the volume or mount them)

docker run --rm -v guard-data:/data opnsense-guard-mcp token new --name laptop --scope read docker run -d --name opnsense-guard --env-file .env -v guard-data:/data -p 8848:8848 \ -e MCP_TRANSPORT=http -e MCP_HOST=0.0.0.0 -e MCP_ALLOWED_HOSTS=mcp.example.internal:8848 \ -e MCP_TLS_CERT=/data/tls/server.pem -e MCP_TLS_KEY=/data/tls/server.key \ opnsense-guard-mcp

Mount a policy file and set OPNSENSE_GUARD_POLICY to enable writes. Stop the container with docker stop (not kill) so unconfirmed changes are reverted.

Policy and planning

Without a policy.yaml the server is read-only. To enable planning, copy policy.example.yaml to policy.yaml (or point OPNSENSE_GUARD_POLICY at it) and edit it. Unknown keys are an error.

Planning tools (rule_plan, alias_plan) read the current state, apply every policy check, and return a diff plus the reasons for any refusal. They never change the firewall. Example result for a refused rule:

+ [wan] pass in inet any from any to any '[mcp]'

interface 'wan' is not in the allowed interfaces any -> any pass rules are forbidden inbound pass rules on WAN are forbidden every rule written by this server must have logging on

Built-in guardrails: only listed interfaces/actions/directions; every IP inside allow_networks; no any→any pass, WAN inbound pass, floating rules or rules without logging; edit only rules tagged [mcp] (unless only_modify_own: false); anti-lockout (no block rule that matches this server's own IP, and only new pass rules on the interface it reaches the API through). A new block or reject rule there is allowed when the same plan adds a pass rule with a lower sequence that provably lets every MCP host reach the API (source covers the host IP, destination any/(self)/the API IP, TCP, port covers the API port); both rules need a sequence.

Applying changes

Change tools appear only when both the policy is in write mode and a second, write-capable API user is configured:

OPNSENSE_WRITE_API_KEY=...      # a different OPNsense user than the read one

OPNSENSE_WRITE_API_SECRET=...

Give that user exactly two privileges: Firewall: Rules [new] and Firewall: Alias: Edit, no group. (Plain *Firewall: Aliases* is view-only: it allows search/get but not addItem/setItem/delItem/reconfigure.) Over HTTP, the change tools need a token with --scope write.

The flow:

1. rule_plan / alias_plan → diff + plan_id (changes nothing).
2. change_apply(plan_id) → asks the human to approve the diff (MCP elicitation where the client supports it; otherwise the tool returns the diff and must be called again with user_confirmed=true). Then it re-reads the firewall (refuses if anything drifted since planning), stores the before-state, writes, applies, reads everything back to verify, and checks the API is still reachable. Any failure → everything is reverted.
3. The change is pending: it is reverted automatically after confirm_timeout_s (default 60 s) unless change_confirm is called.
4. change_rollback undoes a pending or confirmed change. A revert never overwrites an object someone else edited meanwhile (status conflict).

Unconfirmed changes are also reverted when the server stops and, after a crash, when it starts again. Only one change can be open at a time, and max_changes_per_hour is enforced.

Limits, stated plainly

• The revert timer runs on the MCP host. If a change cuts that host off from the firewall API, the revert cannot reach it. The anti-lockout policy and the health probe right after apply exist to prevent and catch this, but they are not the same as the firewall-side savepoint older OPNsense versions had.
• Without elicitation, user_confirmed=true is the model's word that the user agreed. The audit log records which method was used.

Audit log

Every plan (allowed or refused) and server start is written to $OPNSENSE_GUARD_DATA_DIR/audit.jsonl (default ./data). Each line holds the hash of the previous one, so edits, deletions and reordering are detectable:

opnsense-guard-mcp audit verify

opnsense-guard-mcp audit tail -n 20

Credentials are never written to it.

Tools (read-only)

system_status, system_information, system_resources, service_list, posture_check, suricata_status, suricata_settings, suricata_alert_status, firewall_rules, firewall_rule_get, firewall_aliases, firewall_log, firewall_states, system_log, interfaces, arp_table, routing_table, dhcp_leases, raw_get, policy_show, security_audit.

In write mode also: rule_plan, alias_plan, plan_get, audit_tail. With write credentials also: change_apply, change_confirm, change_rollback, change_list, change_get.

firewall_rules returns one line per rule (50 by default) so a full ruleset fits in a chat; pass detail=true for the raw OPNsense rows, or use firewall_rule_get for one rule.

Over HTTP, a read token still sees the change tools in the tool list, but calling one is refused (needs a token with scope 'write').

Development

python -m venv .venv && . .venv/bin/activate

pip install -e ".[dev]" ruff check . && mypy && pytest

Security

See SECURITY.md. Please report vulnerabilities privately.

Licence

MIT. See LICENSE.