pfsense mcp
pfSense的双向AI代理。两个组件，一个包：用于Claude Code控制的MCP服务器，以及在网络需要帮助时激活的紧急大脑。
状态： 规划 作者 克劳德(claude@arktechnwa.com)+梅尔德雷 许可证： 麻省理工学院 组织机构： ArktechNWA
______________________________________________________________________
为什么？
你的人工智能助手可以帮助配置防火墙，但它对你的网络健康状况视而不见。它无法查看您的广域网是否已关闭，无法检查DHCP租约，无法重新启动卡住的接口。
更糟糕的是：当你的网络中断时，你完全无法访问你的人工智能助手。
pfclaude解决了这两个问题：
- 正常模式：Claude Code通过MCP控制pfSense——全可见性、全功能
- 应急模式：当无法访问Claude Code时，pfSense的机载大脑会激活——诊断、通知、自主恢复
______________________________________________________________________
哲学
- 最大能力 --暴露pfSense能做的一切
- 用户控制曝光 --复选框权限，而非硬编码限制
- 最大可用性 --多个传输通道，优雅的回退
- 轻量级应急大脑 --资源使用最少，自适应监控
- 双向通信 --即使网络中断，电子邮件命令也能正常工作
______________________________________________________________________
建筑
┌─────────────────────────────────────────────────────────────────┐
│ 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: - 需要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 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数据库，占用空间\m` |在过去的N分钟里发生了什么变化|
| logs |最后N行记录| | diagnose |运行完整的诊断套件| | restart |重新启动界面（如果允许）| | 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": "..."
}有效负载：\ 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密钥验证** --没有未经身份验证的访问
1. **需要HTTPS** --加密传输
1. **IP白名单** --仅限于已知的Claude IP
1. **速率限制** --防止暴力
1. **电子邮件PIN** --对入站命令进行身份验证
1. **权限矩阵** --用户控制曝光
1. **审计日志** --记录所有操作
1. **无默认危险权限** --用户必须启用
______________________________________________________________________
## 学分
由Claude创建(claude@arktechnwa.com)与Meldrey合作。
部分 [ArktechNWA MCP工具库](https://github.com/ArktechNWA).
之所以构建防火墙，是因为它应该能够在需要时呼叫帮助。