OPNsense Guard

opnsense-guard-mcp

OPNsense 26.7+ 向けの、安全性を最優先した MCP サーバーです。

デフォルトでは読み取り専用です。書き込みはすべて計画され、ポリシーによるチェックとログ記録が行われ、確認されない限り自動的に元に戻されます。

ステータス：アルファ版。 最小権限の API ユーザーを使い、稼働中の OPNsense 26.7.4 で、読み取りツール、ポリシーファイル、差分を含む変更計画、検証と自動ロールバックを伴う変更適用、クラッシュリカバリー、ハッシュチェーン監査ログを、stdio または認証済み HTTPS でテスト済みです。詳しくは DESIGN.md を参照してください。

Deciso B.V. とは無関係です。「OPNsense」は Deciso B.V. の商標です。

他との違い

	opnsense-guard-mcp
デフォルトモード	読み取り専用
読み取りパス	GET、および正確に 2 つの検索エンドポイント（states、rules）への POST。本文は固定の 3 フィールド。パス許可リスト、動詞拒否リストを使用し、トラバーサルやエンコーディングは拒否、リダイレクトには追従しません
書き込み	専用 API ユーザー、正確なエンドポイント許可リスト、計画 → ポリシーチェック → 人による承認 → 適用 → 検証 → 確認されない限り自動ロールバック
26.7+ でのロールバック	独自のオブジェクトレベルのスナップショットとロールバック（26.7 ではセーブポイント API が廃止されています）。再起動後も動作します
ガードレール	許可リスト形式のポリシーファイル：インターフェース、ネットワーク、ルール制限、ロックアウト防止
監査	ハッシュチェーン付き JSONL（audit verify で編集を検出）。syslog は対応予定
トランスポート	stdio、またはベアラートークンが必須の Streamable HTTP。TLS / mTLS はオプション
危険なツール	存在しません：再起動、ファームウェア、サービス制御、SSH、XML 編集はありません

クイックスタート（読み取り専用）

1. OPNsense の System → Access → Users で、ランダムなパスワードを設定し、グループなし（admins ではない）で以下の権限を持つユーザーを作成し、そのユーザーの API キーを作成します。インストールされていない項目は省略してください。該当するツールは「forbidden」と報告します。

   権限	使用ツール
   Firewall: Rules [new]	firewall_rules、firewall_rule_get、計画
   Firewall: Aliases (view-only)	firewall_aliases、計画
   Status: Interfaces	interfaces
   Status: Services	service_list
   Diagnostics: ARP Table	arp_table
   Diagnostics: Routing tables	routing_table
   Diagnostics: Show States	firewall_states
   Diagnostics: Logs: Firewall: Live View	firewall_log
   Diagnostics: Logs: System	system_log
   Lobby: Dashboard	system_information、system_resources、ヘルスプローブ
   Services: Intrusion Detection	suricata_*
   Services: DHCP: Kea(v4) / Services: Dnsmasq DNS/DHCP: Settings / Status: DHCP leases (ISC)	dhcp_leases：使用するもの 1 つのみ
   System: Firmware (オプション)	system_status。更新のインストールも可能になるため、必要な場合を除き設定しないでください。

   OPNsense の権限のほとんどは読み取り専用ではありません（Firewall: Aliases は例外です）。これらの権限のいくつかでは、API 経由で編集もできます。このサーバーはこのキーを使って GET リクエストのみを送信します。ただし、2 つの正確なエンドポイント（diagnostics/firewall/query_states、firewall/filter/searchRule）への検索 POST は例外です。本文（current、rowCount、searchPhrase）はサーバーが独自に作成します。これらのリストを正しく返すのは OPNsense が POST の場合のみです。それでも権限は必要最小限にしてください。OPNsense 自身が適用するのはこれらの権限です。

2. インストールします。

   pipx install opnsense-guard-mcp
   

3. 設定します（.env.example を .env にコピーするか、環境変数を設定します）。

   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
   

4. 設定を確認します（ファイアウォールには接続しません）。

   opnsense-guard-mcp --check
   

5. MCP クライアント（例：Claude Code）に追加します。

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

HTTP モード（共有サーバー）

HTTP は認証なしでは実行できません。次の場合、サーバーは起動を拒否します。

• トークンがない場合、または
• TLS なしでループバック以外のアドレスにバインドする場合 （TLS プロキシの背後でのみ、MCP_ALLOW_PLAINTEXT=true で上書きできます）。

1. クライアントごとにトークンを作成します。トークンは一度だけ表示され、SHA-256 のみが保存されます。

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

   token list には名前とスコープが表示されます。token revoke --name laptop は次のリクエストから有効になり、再起動は不要です。

2. サーバーを起動します。

   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
   

3. クライアントの接続先を https://<host>:8848/mcp に設定し、ヘッダーに Authorization: Bearer <token> を指定します。

変数	デフォルト	用途
MCP_HOST / MCP_PORT	127.0.0.1 / 8848	リッスンアドレス
OPNSENSE_GUARD_TOKENS_FILE	./tokens.json	トークンハッシュ
MCP_TLS_CERT / MCP_TLS_KEY	–	HTTPS を提供
MCP_TLS_CLIENT_CA	–	クライアント証明書を必須にする（mTLS）
MCP_ALLOWED_HOSTS	ポート上の localhost/127.0.0.1/MCP_HOST	許可する Host ヘッダー（DNS リバインディング対策）
MCP_ALLOWED_ORIGINS	なし	許可するブラウザーオリジン。それ以外の Origin は拒否されます
MCP_RATE_LIMIT_PER_MIN	120	トークンごとの1分あたりのリクエスト数
MCP_ALLOW_PLAINTEXT	false	ループバック以外のアドレスでプレーン HTTP を許可

同一 IP からのログイン失敗が繰り返された場合（1分間に10回）、HTTP 429 でスロットリングされます。

Claude Code とプライベート CA： Claude Code（Node）は、MCP サーバーに対して Windows/macOS の証明書ストアを無視します。~/.claude/settings.json の env ブロックで NODE_EXTRA_CA_CERTS に CA ファイルを指定し、Claude を完全に終了してから再度開いてください。そうしないと、接続時に UNABLE_TO_VERIFY_LEAF_SIGNATURE が発生します。

Docker での実行

イメージは root 以外のユーザーとして実行され、監査ログ、変更ジャーナル、トークンを /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

ポリシーファイルをマウントし、OPNSENSE_GUARD_POLICY を設定して書き込みを有効にします。確定されていない変更を取り消すには、kill ではなく docker stop でコンテナーを停止してください。

ポリシーとプランニング

policy.yaml がない場合、サーバーは読み取り専用です。プランニングを有効にするには、policy.example.yaml を policy.yaml にコピーする（または OPNSENSE_GUARD_POLICY で指定する）うえで、編集してください。不明なキーがあるとエラーになります。

プランニングツール（rule_plan、alias_plan）は現在の状態を読み取り、すべてのポリシーチェックを適用して、差分と拒否理由を返します。ファイアウォールを変更することはありません。 拒否されたルールの結果例：

+ [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

組み込みのガードレール：リストに記載されたインターフェース／アクション／方向のみを許可します。すべての IP は allow_networks の範囲内でなければなりません。any→any の pass、WAN の inbound pass、floating rules、ログ記録のないルールは禁止されます。編集できるのは [mcp] タグが付いたルールのみです（only_modify_own: false の場合を除く）。アンチロックアウト対策として、このサーバー自身の IP に一致する block ルールは禁止され、API への接続に使われるインターフェースでは新しい pass ルールのみ許可されます。そのインターフェースで新しい block または reject ルールを許可するには、同じプランに、それより低い sequence を持ち、すべての MCP ホストから API への到達を確実に許可する pass ルールを含める必要があります（送信元がホスト IP を含み、宛先が any/(self)/API IP、TCP を使用し、ポートが API ポートを含むこと）。両方のルールに sequence が必要です。

変更の適用

変更ツールは、ポリシーが書き込みモードであり、かつ書き込み可能な2つ目のAPIユーザーが設定されている場合にのみ表示されます。

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

そのユーザーには、Firewall: Rules [new] と Firewall: Alias: Edit の2つの権限だけを付与し、グループは設定しないでください。（通常の Firewall: Aliases は表示専用です。検索／取得はできますが、addItem/setItem/delItem/reconfigure は実行できません。）HTTP 経由の場合、変更ツールには --scope write のトークンが必要です。

処理の流れ：

1. rule_plan / alias_plan → 差分と plan_id を返します（何も変更しません）。
2. change_apply(plan_id) → 差分の承認をユーザーに求めます（クライアントが対応している場合は MCP エリシテーションを使用します。対応していない場合は、ツールが差分を返し、user_confirmed=true を指定して再度呼び出す必要があります）。続いて、ファイアウォールを再読み込みします（計画後に何かが変わっていた場合は処理を拒否します）。変更前の状態を保存し、書き込み、適用した後、すべてを再読み込みして検証し、API への接続が引き続き可能か確認します。いずれかの処理に失敗した場合は、すべて元に戻します。
3. 変更は保留中になります。change_confirm が呼び出されない場合、confirm_timeout_s（デフォルトは60秒）の経過後に自動で元に戻されます。
4. change_rollback は、保留中または確定済みの変更を取り消します。元に戻す際に、他のユーザーがその間に編集したオブジェクトを上書きすることはありません（ステータスは conflict）。

未確定の変更は、サーバーの停止時にも元に戻されます。また、クラッシュが発生した場合は、サーバーの再起動時にも元に戻されます。同時に開ける変更は1つのみで、max_changes_per_hour による制限も適用されます。

制限事項について

• 元に戻すタイマーは MCP ホスト上で動作します。変更によってそのホストからファイアウォール API に接続できなくなった場合、変更を元に戻すことはできません。ロックアウト防止ポリシーと適用直後のヘルスプローブは、こうした事態の防止と検出を目的としていますが、古いバージョンの OPNsense にあったファイアウォール側のセーブポイントとは異なります。
• エリシテーションを使用しない場合、user_confirmed=true は、ユーザーが同意したというモデルの申告です。監査ログには、使用した確認方法が記録されます。

監査ログ

許可または拒否されたすべての計画とサーバーの起動は、$OPNSENSE_GUARD_DATA_DIR/audit.jsonl（デフォルトは ./data）に記録されます。各行には1つ前の行のハッシュが含まれるため、編集、削除、並べ替えを検出できます。

opnsense-guard-mcp audit verify
opnsense-guard-mcp audit tail -n 20

認証情報が監査ログに書き込まれることはありません。

ツール（読み取り専用）

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。

書き込みモードでは、さらに rule_plan、alias_plan、plan_get、audit_tail を利用できます。 書き込み用の認証情報がある場合は、さらに change_apply、change_confirm、change_rollback、 change_list、change_get を利用できます。

firewall_rules はルールごとに1行を返します（デフォルトは50件）。チャット内にルールセット全体を収めるには、detail=true を指定して生の OPNsense 行を取得するか、1つのルールを取得する firewall_rule_get を使用してください。

HTTP 経由の場合、読み取り用トークンでもツール一覧に変更ツールが表示されますが、呼び出しは拒否されます（needs a token with scope 'write'）。

開発

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check . && mypy && pytest

セキュリティ

SECURITY.md を参照してください。脆弱性は非公開で報告してください。

ライセンス

MIT。LICENSE を参照してください。