AI导哈

pfSense AI代理

一个双向AI代理，用于pfSense防火墙，提供MCP服务器控制和网络紧急情况下的自主恢复功能。

  • by ArkTechNWA
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ArkTechNWA/pfsense-mcp

使用说明

pfsense mcp

pfSense的双向AI代理。两个组件，一个包：用于Claude Code控制的MCP服务器，以及在网络需要帮助时激活的紧急大脑。

状态： 规划 作者 克劳德(claude@arktechnwa.com)+梅尔德雷 许可证： 麻省理工学院 组织机构： ArktechNWA

为什么？

你的人工智能助手可以帮助配置防火墙，但它对你的网络健康状况视而不见。它无法查看您的广域网是否已关闭，无法检查DHCP租约，无法重新启动卡住的接口。

更糟糕的是：当你的网络中断时，你完全无法访问你的人工智能助手。

pfclaude解决了这两个问题：

  1. 正常模式：Claude Code通过MCP控制pfSense——全可见性、全功能
  2. 应急模式：当无法访问Claude Code时，pfSense的机载大脑会激活——诊断、通知、自主恢复

哲学

  1. 最大能力 --暴露pfSense能做的一切
  2. 用户控制曝光 --复选框权限，而非硬编码限制
  3. 最大可用性 --多个传输通道，优雅的回退
  4. 轻量级应急大脑 --资源使用最少，自适应监控
  5. 双向通信 --即使网络中断，电子邮件命令也能正常工作

建筑

┌─────────────────────────────────────────────────────────────────┐
│ Claude Code (workstation)                                       │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfsense-mcp                                                 │ │
│ │  - Full pfSense API passthrough                             │ │
│ │  - All operations: firewall, NAT, DHCP, VPN, logs, etc.     │ │
│ │  - Authenticated over HTTPS                                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
           ↕ HTTPS + API Key (primary)
           ↕ SSH (fallback)
┌─────────────────────────────────────────────────────────────────┐
│ pfSense Router                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfClaude Package                                            │ │
│ │                                                             │ │
│ │  NORMAL MODE          │  EMERGENCY MODE                     │ │
│ │  ─────────────        │  ──────────────                     │ │
│ │  API Server           │  Watchdog Daemon                    │ │
│ │  ↕ MCP talks here     │  ↳ Health monitors                  │ │
│ │                       │  ↳ Trigger detection                │ │
│ │  Full pfSense ops     │  ↳ Decision engine                  │ │
│ │  Auth'd requests      │  ↳ Autonomous actions               │ │
│ │                       │  ↳ Notification dispatch            │ │
│ │                       │                                     │ │
│ │  ───────────────────────────────────────────────────────── │ │
│ │  SHARED INFRASTRUCTURE                                      │ │
│ │  • Permission matrix (checkboxes)                           │ │
│ │  • SMTP client (outbound alerts)                            │ │
│ │  • Email parser (inbound commands)                          │ │
│ │  • Cloud beacon (optional status sync)                      │ │
│ │  • Local knowledge base (patterns, history)                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

认证

API身份验证

简单、经过验证的安全性：

{
  "auth": {
    "api_key": "randomly-generated-64-char-key",
    "require_https": true,
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.5"],
    "rate_limit": 100,
    "lockout_threshold": 5,
    "lockout_duration": 900
  }
}
  • 标头中传输的API密钥： X-PfClaude-Key: <key>
  • 需要HTTPS（使用pfSense的现有证书）
  • 可选IP白名单（仅接受已知的Claude IP）
  • 速率限制：默认100个请求/分钟
  • 身份验证锁定失败：5次失败→ 15 民办

电子邮件身份验证

对于入站电子邮件命令：

Subject: [PFCLAUDE:1234] status
  • 发件人必须在白名单中
  • PIN必须与配置值匹配
  • 时间戳验证（如果超过5分钟，则拒绝）
  • 速率限制：10个命令/小时

触发条件

具有可配置阈值的分层检测：

第1层：监控（始终打开，超轻）

检查 描述 默认值
接口链路状态 物理链路是否正常？ ✓
心跳接收 克劳德代码登记了吗？ ✓
网关可达性 我们可以ping默认网关吗？ ✓
广域网连接 我们能连接到外部IP吗？ ✓

第2级：关注（触发加强监控）

检查 描述 默认值
丢包率>10% 网络性能下降 ✓
延迟峰值>3x 有东西堵塞了 ✓
DNS解析失败 名称查找中断 ✓
DHCP没有响应 客户端无法获取IP ✓
异常流量 5倍正常（攻击？循环？） ✓

第3级：紧急情况（激活自主响应）

检查 描述 默认值
LAN接口故障 物理链路丢失 ✓
连续N次心跳未命中 默认值：3 ✓
网关在N秒内无法访问 默认值：60 ✓
广域网已启动，但局域网无法连接 非对称故障 ✓
所有受监控的主机都无法访问 局域网总故障 ✓

健康检查设计

轻量级、自适应、CPU感知：

┌─────────────────────────────────────────────────────────────────┐
│ ADAPTIVE FREQUENCY                                              │
│                                                                 │
│ State: HEALTHY     → Check every 60s                            │
│ State: CONCERNED   → Check every 15s                            │
│ State: DEGRADED    → Check every 5s                             │
│ State: EMERGENCY   → Check every 2s (active response mode)      │
│                                                                 │
│ CPU AWARENESS                                                   │
│ • If system load > 80%, halve check frequency                   │
│ • If memory < 10% free, disable non-critical checks             │
│ • Never consume > 2% CPU for monitoring                         │
│                                                                 │
│ HYSTERESIS                                                      │
│ • Each check returns: OK (0), WARN (1), FAIL (2)                │
│ • Aggregate score determines state transition                   │
│ • Need 3 consecutive same-state readings to transition          │
└─────────────────────────────────────────────────────────────────┘

自主行动

用户配置pfClaude无需询问即可执行的操作：

始终安全（默认：启用）

动作 描述
在本地记录事件 始终打开
发送电子邮件通知 提醒用户
更新云信标状态 外部可见性
捕获诊断快照 保留状态

诊断（默认：启用）

动作 描述
运行连接测试 ping、traceroute
捕获接口统计信息 计数器、错误
收集最近的日志条目 诊断上下文
检查服务状态 什么正在运行/停止
查询ARP/NDP表 谁在网络上

恢复性（默认：禁用）

动作 描述
重新启动特定接口 经常修复链接问题
刷新连接状态表 清除卡住的连接
重新启动DHCP服务 修复租约问题
重新启动DNS解析器 修复解析问题
清除ARP缓存 修复过时条目
重新启动特定服务 可配置列表

故障转移（默认：禁用）

动作 描述
切换到备份广域网网关 重大网络更改
启用/禁用接口 重大影响
应用应急规则集 预配置的安全规则
触发CARP故障转移 HA环境

防御（默认：禁用）

动作 描述
阻止IP超过阈值 反DoS
启用紧急速率限制 保护资源
激活锁定规则集 最高安全级别
禁用非必要服务 减少攻击面

地方情报

模式存储器

{
  "pattern_memory": {
    "enabled": true,
    "database": "/var/db/pfclaude/patterns.db",
    "max_size_mb": 10,
    "retention_days": 90
  }
}
  • 商店：“上次X发生时，Y是原因”
  • 学习：“界面重启修复了3/4次”
  • 轨迹：正常基线（流量、延迟、错误）
  • SQLite数据库，占用空间<10MB

Haiku批量分析（可选）

{
  "haiku_analysis": {
    "enabled": true,
    "schedule": "0 3 * * *",
    "api_key_env": "PFCLAUDE_ANTHROPIC_KEY",
    "sanitize": ["ip", "mac", "hostname"],
    "max_log_lines": 1000
  }
}
  • 夜间批处理：将经过消毒的原木发送给Anthropic
  • 俳句分析模式、异常、建议
  • 结果以“学习见解”的形式存储在本地
  • 成本：典型家庭网络约0.01美元/天

通知渠道

用户配置自己的升级路径：

{
  "notifications": {
    "email": {
      "enabled": true,
      "smtp_server": "smtp.gmail.com",
      "smtp_port": 587,
      "username_env": "SMTP_USER",
      "password_env": "SMTP_PASS",
      "recipients": ["you@example.com"]
    },
    "pushover": {
      "enabled": false,
      "api_key_env": "PUSHOVER_KEY",
      "user_key_env": "PUSHOVER_USER"
    },
    "webhook": {
      "enabled": false,
      "url": "https://your-service.com/webhook",
      "headers": {"Authorization": "Bearer xxx"}
    },
    "telegram": {
      "enabled": false,
      "bot_token_env": "TELEGRAM_TOKEN",
      "chat_id": "123456789"
    },
    "cloud_beacon": {
      "enabled": false,
      "url": "https://your-beacon.com/status",
      "shared_secret_env": "BEACON_SECRET"
    }
  }
}

升级级别

级别 操作
信息 仅日志
注意 日志+云信标
警告 日志+云+电子邮件
关键 日志+云+电子邮件+推送+webhook
紧急 所有频道+重复警报，直到确认

电子邮件命令

当广域网工作但局域网不工作时，电子邮件成为控制渠道：

命令格式

To: pfclaude@your-pfsense.com
Subject: [PFCLAUDE:1234] status
Body: (optional context)

可用命令

命令 描述
status 当前状态摘要
changes <N>m 在过去的N分钟里发生了什么变化
logs <N> 最后N行记录
diagnose 运行完整的诊断套件
restart <iface> 重新启动界面（如果允许）
help 列出可用命令

示例响应

Subject: Re: [PFCLAUDE:1234] status

pfClaude Status Report
Generated: 2025-12-29 15:42:00 UTC

SYSTEM: DEGRADED (score: 4/10)

Interfaces:
  WAN  (igb0): UP - 98.2.1.45 - 12ms latency
  LAN  (igb1): UP - 192.168.1.1 - NO TRAFFIC 5min  ← Problem
  OPT1 (igb2): DOWN - disabled

Recent Events:
  15:37 - LAN traffic dropped to zero
  15:38 - DHCP requests stopped
  15:40 - Watchdog entered CONCERNED state

Recommended: Check switch connectivity to LAN port

云信标（可选）

从任何地方检查路由器状态：

{
  "cloud_beacon": {
    "enabled": true,
    "url": "https://your-beacon-server.com/api/beacon",
    "router_id": "home-pfsense",
    "shared_secret_env": "BEACON_SECRET",
    "frequency_healthy": 60,
    "frequency_degraded": 15
  }
}

自托管选项

为运行自己的信标接收器提供的Docker镜像：

docker run -d -p 8080:8080 \
  -e BEACON_SECRET=your-secret \
  arktechnwa/pfclaude-beacon

特征：

  • 从pfSense接收状态信标
  • 存储最近的日志（可配置保留）
  • 用于状态检查的Web仪表板
  • 可以将命令中继回pfSense

信标协议

POST /beacon
{
  "router_id": "home-pfsense",
  "timestamp": "2025-12-29T15:42:00Z",
  "state": "healthy",
  "score": 9,
  "interfaces": {
    "wan": {"status": "up", "ip": "98.2.1.45", "latency_ms": 12},
    "lan": {"status": "up", "ip": "192.168.1.1", "clients": 15}
  },
  "recent_events": [],
  "hmac": "..."
}

有效负载：<2KB，专为最小带宽而设计。

MCP工具

pfSense可以做的一切，通过MCP公开：

系统

工具 描述 权限
pf_system_info 主机名、版本、正常运行时间、资源 read
pf_system_status 总体健康摘要 阅读
pf_system_reboot 重启pfSense 危险
pf_system_shutdown 关闭pfSense 危险
pf_system_config_backup 导出配置XML 读取

接口

工具 描述 权限
pf_interface_list 所有状态为 read的接口
pf_interface_status 一个的详细状态 已读
pf_interface_stats 流量计数器，错误 读取
pf_interface_restart 重新启动接口 服务
pf_interface_enable 启用接口 config
pf_interface_disable 禁用接口 config

防火墙

工具 描述 权限
pf_firewall_rules 列出规则（过滤器、nat等） 读取
pf_firewall_rule_add 添加规则 config
pf_firewall_rule_delete 删除规则 config
pf_firewall_rule_modify 修改规则 config
pf_firewall_states 连接状态表 已读
pf_firewall_states_flush 清除状态表 服务
pf_firewall_aliases 管理别名 config

网络地址转换

工具 描述 权限
pf_nat_rules 端口转发，出站NAT 读取
pf_nat_rule_add 添加NAT规则 config
pf_nat_rule_delete 删除NAT规则 config
pf_nat_rule_modify 修改NAT规则 config

动态主机配置协议

工具 描述 权限
pf_dhcp_leases 当前租约 阅读
pf_dhcp_static_mappings 保留IP 已读
pf_dhcp_config DHCP服务器配置 config
pf_dhcp_service_restart 重新启动DHCP 服务

域名系统

工具 描述 权限
pf_dns_resolver_config 未绑定配置 config
pf_dns_forwarder_config dnsmasq配置 配置
pf_dns_override_add 添加主机覆盖 config
pf_dns_override_delete 删除主机覆盖 config
pf_dns_service_restart 重新启动DNS 服务

虚拟专用网络

工具 描述 权限
pf_vpn_openvpn_status OpenVPN连接 读取
pf_vpn_ipsec_status IPsec SA 读取
pf_vpn_wireguard_status WireGuard同行 阅读
pf_vpn_disconnect 断开客户端/隧道 服务

路由

工具 描述 权限
pf_routes_table 路由表 已读
pf_routes_static 静态路由 config
pf_gateway_status 网关运行状况 已读
pf_gateway_switch 切换默认网关 config

交通

工具 描述 权限
pf_traffic_graphs 带宽图数据 读取
pf_traffic_totals 界面总计 已读
pf_traffic_top 热门演讲者 阅读

日志

工具 描述 权限
pf_logs_system 系统日志 已读
pf_logs_firewall 防火墙日志 已读
pf_logs_dhcp DHCP日志 已读
pf_logs_vpn VPN日志 已读
pf_logs_search 在所有日志中搜索 阅读

包裹

工具 描述 权限
pf_packages_installed 已安装的软件包 已读
pf_packages_available 可用软件包 阅读
pf_packages_install 安装软件包 危险
pf_packages_remove 删除包裹 危险

服务

工具 描述 权限
pf_services_list 所有服务状态 已读
pf_services_start 启动服务 服务
pf_services_stop 停止服务 服务
pf_services_restart 重新启动服务 服务

诊断

工具 描述 权限
pf_diag_ping 来自pfSense的Ping 阅读
pf_diag_traceroute 来自pfSense的跟踪路由 读取
pf_diag_dns_lookup 从pfSense进行DNS查找 读取
pf_diag_arp_table ARP表 读取
pf_diag_ndp_table IPv6邻居表 已读
pf_diag_sockets 打开插座 读取
pf_diag_pftop 实时状态表 已读

权限矩阵

通过pfSense WebGUI进行精细控制：

权限级别

级别 描述
read 查看状态、日志、配置
service 重新启动服务，刷新缓存
config 修改配置
dangerous 重启、关机、包管理

WebGUI配置

┌─────────────────────────────────────────────────────────────────┐
│ pfClaude > Settings > Permissions                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ MCP API Permissions                                             │
│ ─────────────────────────────────────────────────────────────── │
│                                                                 │
│ READ OPERATIONS                          [Select All] [Clear]   │
│ ☑ System info & status                                         │
│ ☑ Interface status & stats                                     │
│ ☑ Firewall rules (view)                                        │
│ ☑ DHCP leases                                                  │
│ ☑ Logs (all)                                                   │
│ ☑ Diagnostics (ping, traceroute, etc)                          │
│                                                                 │
│ SERVICE CONTROL                          [Select All] [Clear]   │
│ ☐ Restart interfaces                                           │
│ ☐ Restart services (DHCP, DNS, etc)                            │
│ ☐ Flush state table                                            │
│ ☐ Clear caches                                                 │
│                                                                 │
│ CONFIGURATION CHANGES                    [Select All] [Clear]   │
│ ☐ Modify firewall rules                                        │
│ ☐ Modify NAT rules                                             │
│ ☐ Modify DHCP settings                                         │
│ ☐ Add/remove static routes                                     │
│                                                                 │
│ DANGEROUS OPERATIONS                     [Select All] [Clear]   │
│ ☐ System reboot                                                │
│ ☐ System shutdown                                              │
│ ☐ Install/remove packages                                      │
│ ☐ Gateway failover                                             │
│                                                                 │
│ ─────────────────────────────────────────────────────────────── │
│ ☐ BYPASS ALL PERMISSIONS (danger mode)                         │
│                                                                 │
│                                    [Save] [Reset to Defaults]   │
└─────────────────────────────────────────────────────────────────┘

储存与卫生

{
  "storage": {
    "email_queue": {
      "max_messages": 100,
      "max_age_days": 10,
      "cleanup_schedule": "0 4 * * *"
    },
    "logs": {
      "pfclaude_events_days": 7,
      "diagnostic_snapshots_days": 3
    },
    "pattern_memory": {
      "persistent": true,
      "compact_schedule": "0 5 * * 0"
    },
    "total_footprint_mb": 50
  }
}

安装

pfSense软件包

System > Package Manager > Available Packages > pfClaude

或手动：

pkg add https://github.com/ArktechNWA/pfsense-mcp/releases/latest/pfsense.pkg

MCP服务器（克劳德代码端）

npm install -g @arktechnwa/pfsense-mcp

Claude代码集成

{
  "mcpServers": {
    "pfsense": {
      "command": "pfsense-mcp",
      "env": {
        "PFSENSE_HOST": "192.168.1.1",
        "PFSENSE_API_KEY": "your-api-key"
      }
    }
  }
}

需求

pfSense侧

  • pfSense 2.7+或pfSense Plus 23.09+
  • 50MB可用存储空间
  • 网络连接（显然）

克劳德代码端

  • Node.js 18+
  • pfSense的网络访问

可选的

  • 无烟煤API键（用于Haiku批次分析）
  • SMTP服务器（用于电子邮件通知）
  • 自托管信标服务器（用于云状态）

安全考虑

  1. API密钥验证 --没有未经身份验证的访问
  2. 需要HTTPS --加密传输
  3. IP白名单 --仅限于已知的Claude IP
  4. 速率限制 --防止暴力
  5. 电子邮件PIN --对入站命令进行身份验证
  6. 权限矩阵 --用户控制曝光
  7. 审计日志 --记录所有操作
  8. 无默认危险权限 --用户必须启用

学分

由Claude创建(claude@arktechnwa.com)与Meldrey合作。 部分 ArktechNWA MCP工具库.

之所以构建防火墙，是因为它应该能够在需要时呼叫帮助。

相关 MCP