Firewall AIops

防火墙 AIops

面向 OPNsense 和 pfSense 防火墙的可治理、可审计 AI 运维——供 AI Agent（通过 MCP）和人类（通过 CLI）使用。

免责声明：由社区维护的开源项目。与 OPNsense 项目、Deciso、Netgate 或 pfSense 项目均无关联，也未获其认可或赞助。 OPNsense、pfSense 和 Netgate 是其各自所有者的商标。本项目采用 MIT 许可。

firewall-aiops 通过一个 MCP 服务连接两种防火墙平台——OPNsense （/api/... 下的 REST API，通过 HTTP Basic 身份验证使用 API 密钥和密钥）和 pfSense （来自 pfSense-pkg-RESTAPI 软件包的 /api/v2/... 下的 REST API，通过 X-API-Key 标头传递 API 密钥）——两者使用相同的工具。配置中的每个目标都会指定自己的 platform；按名称索引的平台注册表会选择 API 格式 （身份验证和资源路径），因此 Agent 无需了解自己正在与哪种防火墙通信。

每个工具都会通过内置治理机制运行（随附 vendored 代码，不依赖外部组件）：审计日志、令牌/调用预算与失控熔断机制、描述性风险级别标签、撤销令牌记录，以及提示词注入清理。

为什么要开发这个项目

• 一个服务，两种防火墙——在混合环境中使用 OPNsense 和 pfSense，通过相同的工具名称进行操作。以后添加第三种防火墙，只需新增平台描述符，无需重写。
• 读取整个防火墙——固件/运行状况、接口和网关、过滤规则（包括命中次数和状态表）、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，并提供试运行预览。每项写入操作，无论是否可撤销，都会写入一条审计记录。

此工具能做什么，以及不会替你决定什么

此工具能够准确、高效地执行防火墙操作——读取和写入，并记录每一项操作。它不会决定是否允许执行某项写入操作。该决定取决于 Agent 的判断，或你连接所用账户的权限：为 OPNsense/pfSense API 用户分配只读角色，写入操作就会在服务器上失败——因为权限实际由服务器控制。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一保证的是没有任何操作会悄无声息：通过 MCP 或 CLI 发起的每次调用，都会在 ~/.firewall-aiops/audit.db 中写入一条审计记录；可撤销的写入操作仍会捕获其先前状态，并在存在逆向操作时记录该操作。

每个工具都会声明一个 risk_level，与其 [READ]/[WRITE] 文档标签相对应，并作为描述性级别写入审计记录——审查者可以一眼看出某条记录对应高风险写入操作。这只是标签，不是关卡。

使用较小的本地模型？请参阅 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 插件

安装一次，即可为 Agent 同时提供技能和 MCP 服务：

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

MCP 服务通过 uv 获取，并固定为此插件声明的软件包版本，因此可以追溯审计记录对应的写入代码。仍需使用 firewall-aiops init 配置凭据——见下文。

作为 OpenClaw 插件

同一套插件包发布在 ClawHub 上，安装一次即可同时获得技能和 MCP 服务：

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

之后重启 OpenClaw 网关以加载插件。MCP 服务通过 uv 获取，并固定为此确切版本，因此 uvx 必须位于 PATH 中——否则技能仍会安装，但会报告 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

为 Agent 运行 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 secret（与用于 HTTP Basic 身份验证的 key 配对），或 pfSense API key——会以加密形式存储在 ~/.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（仅记录；由外部编排器执行）。
• 净化 — 所有防火墙返回的文本在传递给 Agent 之前，都会经过长度限制和注入净化。

平台支持与验证状态

• 平台：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。