Firewall AIops

Firewall AIops

OPNsense および pfSense ファイアウォール向けの、ガバナンスと監査を備えた AI オペレーション — AI エージェント（MCP 経由）と人間（CLI 経由）向けです。

免責事項：コミュニティがメンテナンスするオープンソースプロジェクトです。OPNsense プロジェクト、Deciso、Netgate、または pfSense プロジェクトとの提携、承認、後援関係はありません。 OPNsense、pfSense、Netgate は、それぞれの所有者の商標です。MIT ライセンスで提供されています。

firewall-aiops は、1 つの MCP サーバーを通じて 2 つのファイアウォールプラットフォームと通信します — OPNsense （/api/... 配下の REST API、HTTP Basic 認証による API キーとシークレット）と pfSense （pfSense-pkg-RESTAPI パッケージが提供する /api/v2/... 配下の REST API v2、X-API-Key ヘッダーによる API キー） — どちらでも同じツールが動作します。設定内の各ターゲットにはそれぞれの platform が指定され、名前をキーとするプラットフォームレジストリが API 形式（認証とリソースパス）を選択するため、エージェントは接続先のファイアウォールを意識する必要がありません。

すべてのツールは、組み込みのガバナンスハーネス（同梱されており、外部依存関係はゼロ）を通じて実行されます。監査ログ、トークン／呼び出し予算と暴走を防ぐサーキットブレーカー、リスク階層を示す説明的なラベル、取り消しトークンの記録、プロンプトインジェクションのサニタイズが含まれます。

このツールがある理由

• 1 つのサーバーで両方のファイアウォールに対応 — OPNsense と pfSense が混在する環境でも、同じツール名を通じて操作できます。後から 3 つ目のファイアウォールを追加する場合も、書き換えではなく、新しいプラットフォーム記述子を追加するだけです。
• ファイアウォール全体を読み取る — ファームウェア／ヘルス状態、インターフェースとゲートウェイ、フィルタールール（ヒット数とステートテーブルを含む）、NAT（ポートフォワード／アウトバウンド／1:1）、エイリアス、VPN（WireGuard／OpenVPN／IPsec）、DHCP リースと予約、ファイアウォールログ。
• 主力の RCA 分析 — 数値を示す透明なヒューリスティックで、ブラックボックスの判定は行いません。gateway_health_rca（WAN の損失／遅延／ダウン → 原因と対処）、rule_hit_and_shadow_analysis（一度もヒットしていないルールとシャドウ／冗長ルール）、blocked_traffic_rca（ブロックされた送信元／ポートの上位 → スキャン／ブルートフォース／プローブ）。
• ガバナンスに基づく書き込み — ルールの切り替え、エイリアスエントリーの追加／削除（元に戻せるよう、取得した変更前の状態をもとに取り消し記録を作成）、ステートのフラッシュ、サービスの再起動、「本番環境へ反映」するコミット（apply_changes／reconfigure）、および reboot を、ドライランのプレビュー付きでrisk=highとして実行できます。元に戻せるかどうかにかかわらず、すべての書き込みが監査レコードに記録されます。

このツールが判断すること、しないこと

このツールは、ファイアウォールの操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続先アカウントの権限に委ねられます。OPNsense／pfSense の API ユーザーに読み取り専用ロールを付与すれば、書き込みは権限を実際に管理するサーバー側で失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何も記録されずに実行されることがないという点です。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.firewall-aiops/audit.db の監査レコードに記録され、元に戻せる書き込みでは変更前の状態も取得し、可能な場合は逆操作を記録します。

各ツールは、[READ]／[WRITE] のドキュメントタグに対応する risk_level を宣言し、説明用の階層として監査レコードに引き継ぎます。これにより、レビュー担当者は高リスクの書き込みを示すレコードをひと目で確認できます。これはラベルであり、ゲートではありません。

より小規模なモデルやローカルモデルを実行していますか？ agent-guardrails.md を参照してください。このツールが代わりに適用するガードレール（プロンプトの予算を使って繰り返し指示する必要はありません）と、残りの指示に使えるすぐに利用可能なシステムプロンプトが記載されています。

ツール一覧（35 個）

ドメイン	ツール	#	種別
システム	firmware_status, health_status, interface_status, gateway_status	4	読み取り
ルール	list_rules, rule_detail, rule_stats, rule_states	4	読み取り
NAT	nat_port_forwards, nat_outbound, nat_one_to_one	3	読み取り
エイリアス	list_aliases, alias_entries	2	読み取り
VPN	wireguard_status, openvpn_sessions, ipsec_sas	3	読み取り
DHCP	dhcp_leases, dhcp_static_mappings	2	読み取り
診断	firewall_log, states_table, top_talkers	3	読み取り
主な分析	gateway_health_rca, rule_hit_and_shadow_analysis, blocked_traffic_rca	3	読み取り
書き込み	toggle_rule, add_alias_entry, remove_alias_entry, kill_states, restart_service	5	書き込み（中）
書き込み	apply_changes, reconfigure, reboot	3	書き込み（高）
取り消し	undo_list, undo_apply	2	読み取り／書き込み

取り消し可能な書き込みでは、実際に取得した変更前の状態に基づいて逆操作を記録した 取り消し記述子 が保存されます（toggle_rule はルールの変更前の有効状態に戻し、エイリアスの追加／削除は逆の操作を行います）。apply_changes／reconfigure／reboot は dry_run に対応する高リスク操作です。reboot は取り消し不能です（監査のみ）。

インストール

uv tool install firewall-aiops        # or: pipx install firewall-aiops

クイックスタート

Claude Code プラグインとして

1 回のインストールで、エージェントにスキルと MCP サーバーの両方を導入できます。

/plugin marketplace add AIops-tools/marketplace
/plugin install firewall-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査記録から、それを書き込んだコードを特定できます。認証情報の設定には、引き続き firewall-aiops init を使用します。詳しくは以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

openclaw plugins install clawhub:@zw008/firewall-aiops
openclaw skills info firewall-aiops          # expect: Visible to model: yes

その後、プラグインを読み込むために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv で取得され、このリリースのバージョンに固定されているため、uvx が PATH 上にある必要があります。uvx がない場合、スキルはインストールされますが、Visible to model: no と表示されます。認証情報は以下の手順と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

firewall-aiops init                     # wizard: pick platform (opnsense/pfsense) + store the secret (encrypted)
firewall-aiops doctor                   # verify config, secrets, and connectivity
firewall-aiops overview                 # one-shot: version + gateway/interface health + rule count
firewall-aiops rules list               # list filter rules
firewall-aiops rules toggle <uuid> --disable   # dry-run + double-confirm governed write
firewall-aiops log --action block -n 50 # recent blocked traffic

エージェント用に MCP サーバー（stdio）を実行します。

firewall-aiops mcp                      # or: firewall-aiops-mcp

MCP クライアント設定

{
  "mcpServers": {
    "firewall-aiops": {
      "command": "uvx",
      "args": ["--from", "firewall-aiops", "firewall-aiops-mcp"],
      "env": { "FIREWALL_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

設定

~/.firewall-aiops/config.yaml（接続に関する非機密情報のみ）：

targets:
  - name: fw1
    platform: opnsense       # opnsense | pfsense
    host: 192.0.2.1
    port: 443
    username: <opnsense-api-key>   # OPNsense API key (unused for pfSense)
    verify_ssl: true         # the default; false ONLY for self-signed lab certs
  - name: edge
    platform: pfsense
    host: 192.0.2.2
    verify_ssl: true
    # scheme: http           # https is the default; http ONLY for a GUI behind a
    #                        # proxy that terminates TLS for it

シークレット — OPNsense API の シークレット（HTTP Basic 認証用のキーとペア）または pfSense の API キー — は ~/.firewall-aiops/secrets.enc に 暗号化して 保存されます（Fernet と scrypt で導出したキーを使用）。ディスク上に平文で保存されることはありません。firewall-aiops secret set <target> または init ウィザードで設定してください。ストアのロック解除には、FIREWALL_AIOPS_MASTER_PASSWORD（非対話型／MCP／CI の場合）から取得したマスターパスワード、または対話型プロンプト（TTY 上の CLI の場合）が使われます。従来の平文環境変数 FIREWALL_<TARGET>_SECRET はフォールバックとして使用されます（firewall-aiops secret migrate で移行してください）。

ガバナンス

すべての MCP ツールは @governed_tool でラップされています。

• 監査 — すべての呼び出しが ~/.firewall-aiops/audit.db に記録されます（ツール、機密情報をマスキングしたパラメーター、ステータス、所要時間、リスクティア、承認者、理由）。
• 予算／暴走防止 — プロセスごとのトークン数と呼び出し回数の上限、および繰り返し呼び出しに対するサーキットブレーカー（FIREWALL_MAX_TOOL_CALLS、FIREWALL_RUNAWAY_MAX、…）。
• リスクティアのラベル付け — 各ツールで宣言された risk_level は、説明用のティア（ラベルであり、ゲートではありません）として監査レコードに記録されます。読み取り専用の切り替え、ポリシーファイル、承認ゲートはありません。FIREWALL_AUDIT_APPROVED_BY と FIREWALL_AUDIT_RATIONALE は任意の監査注釈で、設定されている場合に記録されますが、必須ではありません。
• 取り消しの記録 — 元に戻せる書き込みでは、取得した変更前の状態から逆操作の記述子を ~/.firewall-aiops/undo.db に記録します（記録のみで、外部オーケストレーターが実行します）。
• サニタイズ — ファイアウォールから返されたすべてのテキストは、エージェントに渡す前に長さを制限し、インジェクションをサニタイズします。

プラットフォームのサポートと検証状況

• プラットフォーム：OPNsense（REST API）と pfSense（REST API v2、pfSense-pkg-RESTAPI）。
• テストカバレッジ：モックした OPNsense／pfSense の JSON レスポンスに対して動作を検証しています。すべてのモジュールをインポートし、すべての MCP ツールにガバナンスマーカーが付いていることを確認し、RCA ヒューリスティックを合成テレメトリーに対してユニットテストし、元に戻せる書き込みで正しい逆操作の記述子が記録されることを確認しています。具体的な REST パスは各プロジェクトの公開 API に基づいてモデル化されており、実稼働中のファイアウォールに対するテストはまだ行われていません。docs/VERIFICATION.md で、実機テストで満たす必要があるチェックリストを確認してください。firewall-aiops doctor（両プラットフォームのファームウェア／バージョン照会）が、最も手早く接続を確認できる方法です。どちらのプラットフォームも無料でセルフホスト可能（OPNsense は完全なオープンソース、pfSense CE は無料）なため、自宅のラボ環境が実行に最適です。
• 必要な機能がありませんか？ github.com/AIops-tools/Firewall-AIops で Issue または PR を作成してください。貢献やフィードバックを歓迎します。

ライセンス

MIT — LICENSE をご覧ください。