OPNsense MCP
OPNsense MCP
安全性を重視した、OPNsense の MVC API 向けリモート Model Context Protocol サーバーです。リモートエージェント向けにステートフルな Streamable HTTP を公開し、上流側では API のネイティブ HTTP Basic 認証を使用します。また、OPNsense コマンドが読み取り専用かどうかを判断できない場合は、フェイルクローズします。
1 つのサーバーインスタンスは、1 台の OPNsense ファイアウォールに対応します。ファイアウォールの URL と API 認証情報はサーバー環境内に保持され、エージェントは個別のベアラートークンで MCP に認証します。エージェントがリクエストを任意のネットワーク宛先にリダイレクトすることはできません。複数のアプライアンスを管理する場合は、ファイアウォールごとに分離したインスタンスをデプロイしてください。
アーキテクチャ
Remote agent --HTTPS + MCP bearer token--> OPNsense MCP --HTTPS + API key/secret--> OPNsenseMCP エンドポイントは、現在の Streamable HTTP トランスポートを /mcp で使用します。セッションはステートフルであるため、一度きりの変更プランはエージェントの MCP セッションにバインドされたままになります。セッションには上限があり、非アクティブ状態が続くと失効し、すべての HTTP リクエストで認証されます。
組み込みの HTTP リスナーは、TLS リバースプロキシ、イングレスコントローラー、VPN、またはプライベートオーバーレイの背後に配置することを想定しています。平文の HTTP ポートを信頼できないネットワークに直接公開しないでください。
Related MCP server: ufw-mcp
OPNsense API モデル
OPNsense は、API リクエストを次のようにルーティングします:
/api/<module>/<controller>/<command>/<parameter...>自動化で重要な動作は次のとおりです:
API キーは HTTP Basic 認証を使用します。キーがユーザー名、シークレットがパスワードとなります。
アクセスは、キー所有者の OPNsense ACL 権限によって制限されたままです。
リクエストとほとんどのレスポンスは JSON です。ダウンロードとストリームは JSON ではない場合があります。
GETとPOSTは、安全な操作と危険な操作にきれいに対応するわけではありません。一部の読み取りはPOSTを使用し、一部の変更はGETを使用します。変更可能なモデルコントローラーは、通常
get、search、add、set、del、toggleの各操作を公開します。配列モデルのレコードには UUID を使用します。UUID を指定しない
getは、多くの場合デフォルト値が入力された空のレコードを返します。モデルの変更が成功すると、通常ステージングされた設定が書き込まれます。その後の
applyまたはreconfigureで有効化されます。モデルの書き込みは、
{"result":"saved"}や{"result":"failed","validations":...}などの値を返します。HTTP 200 が返っただけでは、意味的な成功は保証されません。OPNsense の設定ロック、モデル検証、リビジョンコンテキスト、ACL チェックはサーバー側で行われ、バイパスすることはできません。
公式リファレンス:
https://docs.opnsense.org/development/frontend/controller.html
https://docs.opnsense.org/development/frontend/models_fieldtypes.html
安全性モデル
opnsense_request は、読み取りとして分類されたコマンドのみを受け入れます。分類は HTTP メソッドではなくコマンド名に基づいて行われます。
変更には 2 つのツールを使用します:
opnsense_plan_changeは、OPNsense にアクセスせずに、リクエストの正確な内容とそのリスクを報告します。opnsense_execute_changeは、5 分後に失効する一致するワンタイムトークンを必要とします。
リスククラスは、ステージングされた書き込み、有効化、サービス破壊的なサービスやファームウェア操作、および壊滅的なリセット/リストア操作などを区別します。未知のコマンドはフェイルクローズした後、変更として扱われます。
書き込みモードはエージェントの外部から制御されます:
disabledは読み取りのみ許可します。planは変更分析を許可しますが、実行トークンは作成しません。enabledは一致するトークンによる実行を許可します。
専用の OPNsense ユーザーを使用し、意図するツールに必要な有効な権限だけを付与してください。読み取り専用でデプロイする場合は、OPNsense でも System: Deny config write (user-config-readonly) を付与してください。
厳選された読み取りツール
保護された汎用クライアントは、一般的な運用タスク向けの固定読み取り専用ツールで補完されます:
opnsense_get_firewall_logsは、構造化されたパケットフィルタのイベントを読み取ります。opnsense_get_logsは、システム、configd、ゲートウェイ、VPN、DNS、DHCP、IDS、ルーティング、Web UI の各ログを含む、コアとサービスのログから制限付きページで読み取ります。opnsense_list_firewall_rulesは、自動化 API から見えるフィルタールールを読み取ります。opnsense_list_nat_rulesは、宛先、送信元、1対1、または NPT ルールを読み取ります。opnsense_get_route_tableは、実稼働中のカーネルルーティングテーブル、または設定された静的ルートの 1 つを読み取ります。
これらのツールは固定のクエリエンドポイントを直接呼び出します。ログのクリア、ステートのフラッシュ、ルールの変更、設定の適用などの他の変更動作を選択することはできません。結果は、API ユーザーの OPNsense ACL 権限の影響を引き続き受けます。
セットアップ
npm install
npm run build.env.example を参照して環境を設定してください。環境ファイルは自動的に読み込まれず、Git では無視されます。openssl rand -hex 32 で別の MCP トークンを生成してください。既存の OPNsense API 認証情報を再利用しないでください。
公開済みの信頼できる証明書を使用するか、OPNSENSE_CA_FILE にプライベート CA 証明書を設定してください。OPNSENSE_TLS_VERIFY=false は分離された開発環境専用のオプションです。
ローカル TLS リバースプロキシ用に、リモートサーバをループバックで実行します:
OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_AUTH_TOKEN=<random-token-at-least-32-characters> \
node dist/index.jsMCP URL は http://127.0.0.1:3000/mcp です。HTTPS として公開するにはリバースプロキシを経由し、トークンを次のように渡します:
Authorization: Bearer <MCP_AUTH_TOKEN>URL とカスタムヘッダーをサポートするクライアント向けのリモートクライアント設定例:
{
"mcpServers": {
"opnsense": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${MCP_AUTH_TOKEN}"
}
}
}
}クライアントの設定形式はさまざまです。トークンは設定ファイルに保存するのではなく、クライアントのシークレット機能に保存してください。
Docker Compose
compose.yaml はリバースプロキシが TLS を安全に停止できるよう、ポート 3000 をホストのループバックにバインドします。
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開発中に localhost:3000 へ直接接続する場合は、MCP_ALLOWED_HOSTS に localhost を含めてください。認証不要のヘルスエンドポイントは /health で利用でき、ターゲットや資格情報の詳細は返しません。
リモートのセキュリティ
HTTP トランスポートでの接続では
MCP_AUTH_TOKENが必須で、32 文字以上の長さが必要です。非ループバックアドレスにバインドする場合、
MCP_ALLOWED_HOSTSは必須で、Host ヘッダによる DNS リバインディングを防ぎます。ブラウザの
Originヘッダーを含む要求は、完全一致のオリジンがMCP_ALLOWED_ORIGINSに含まれていない限り拒否されます。MCP_MAX_SESSIONS、MCP_SESSION_TTL_MS、MCP_RATE_LIMIT_PER_YOUR_MINUTEは、リモートリソースの使用量を制限します。OPNSENSE_TLS_VERIFY=trueのままにしてください。内部 CA を使用する場合は、検証を無効にするのではなくOPNSENSE_CA_FILEを設定します。監視専用のデプロイメントでは、
OPNSENSE_WRITE_MODE=disabledのままにしてください。OPNsense API ユーザーは、有効な ACL 権限と、必要に応じて
user-config-readonlyに制限します。MCP エンドポイントは、HTTPS、ファイアウォールポリシーの背後、可能であれば VPN またはプライベートネットワーク内に配置してください。
MCP_ALLOW_UNAUTHENTICATED=true は、分離されたローカル開発専用に存在するもので、リモートから到達可能なリスナーには決して使用しないでください。
Stdio 互換性
ローカルクライアントは、引き続きサーバーをサブプロセスとして起動できます:
OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_TRANSPORT=stdio \
node dist/index.js設定
OPNSENSE_URL: 固定のファイアウォールのベース URL。OPNSENSE_API_KEY: 専用の OPNsense ユーザーの API キー。OPNSENSE_API_SECRET: そのキーの API シークレット。OPNSENSE_WRITE_MODE:disabled、plan、enabledのいずれか。OPNSENSE_CA_FILE: 任意のプライベート CA の PEM ファイル。OPNSENSE_TLS_VERIFY: デフォルトはtrue。MCP_TRANSPORT: デフォルトはhttp。またはstdio。MCP_HOST: リスナーアドレス。デフォルトは127.0.0.1。MCP_PORT: リスナーポート。デフォルトは3000。MCP_PATH: MCP エンドポイントのパス。デフォルトは/mcp。MCP_AUTH_TOKEN: リモートエージェント用のベアラートークン。MCP_ALLOWED_HOSTS: HTTP Host ヘッダーで許可されるカンマ区切りホスト名。MCP_ALLOWED_ORIGINS: カンマ区切りのブラウザオリジン。空の場合はブラウザ由来のリクエストを拒否します。MCP_MAX_SESSIONS: 同時セッション数の上限。デフォルトは100。MCP_SESSION_TTL_MS: アイドルタイムアウトセッションの有効期限。デフォルトは 1 時間。MCP_RATE_LIMIT_PER_MINUTE: クライアントごとの HTTP リクエスト制限。デフォルトは120。
たとえば、システムの状態を読み取る呼び出しは次のようになります:
{
"module": "core",
"controller": "system",
"command": "status"
}現在の制限事項
OPNsense は完全な OpenAPI 仕様を公開していません。生成されたリファレンスはルートと推定メソッドを示しますが、通常はリクエストボディのスキーマが省略されます。
プラグインエンドポイントは、そのパッケージがインストールされ、ACL で許可されている場合にのみ存在します。
応答の意味的検証は、まだエンドポイント固有のものではありません。
レキシカルリスク分類系は意図的に保守的です。キュレーションされたツールは、最終的には明示的なリクエスト/レスポンススキーマを含む監査済みエンドポイントマニフェストを使用すべきです。
プラントークンは偶発的または不一致な実行を減らしますが、それでも MCP ホストは破壊的なツールについては人間の承認を求めてください。
リモート認証は、現在は OAuth 認可サーバーではなくデプロイ全体の静的ベアラトークンを使用しています。エージェントごとに別々の ID が必要な場合には、別々のデプロイまたは認証用リバースプロキシを使用してください。
セッション状態はメモリ内にのみ存在し、レプリカ間では共有されません。外部セッションストレージとルーティングの固定を追加しない限り、レプリカは 1 つで実行してください。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Remote MCP for A2A caller identity, scope policy, verdict receipts, and audit history.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables cloud agents to securely operate local machine resources (files, commands, screenshots) via standard MCP protocol.MIT
- FlicenseNot gradedqualityDmaintenanceEnables least-privilege UFW firewall rule management over MCP, with safety checks to prevent silent no-op allows and audit trails tied to authenticated identity.-
- AlicenseNot gradedqualityBmaintenanceEnables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.MIT
- FlicenseNot gradedqualityBmaintenanceEnables governed MCP agent tool invocation with policy-based authorization, short-lived credentials, and audited access control.-