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--> OPNsense

MCP エンドポイントは、現在の Streamable HTTP トランスポートを /mcp で使用します。セッションはステートフルであるため、一度きりの変更プランはエージェントの MCP セッションにバインドされたままになります。セッションには上限があり、非アクティブ状態が続くと失効し、すべての HTTP リクエストで認証されます。

組み込みの HTTP リスナーは、TLS リバースプロキシ、イングレスコントローラー、VPN、またはプライベートオーバーレイの背後に配置することを想定しています。平文の HTTP ポートを信頼できないネットワークに直接公開しないでください。

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/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_fieldtypes.html

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

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

安全性モデル

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.js

MCP 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 つで実行してください。