leonuz/pfchat
GitHub: leonuz/pfchat
PfChat 是一个 OpenClaw 技能，通过 pfSense REST API 实时查询和分析防火墙状态，让 AI 助手能够智能监控网络设备、连接状态和安全事件。
Stars: 0 | Forks: 0
# PfChat
[](https://github.com/leonuz/pfchat/releases)
[](LICENSE)
[](https://docs.openclaw.ai)
PfChat 是一个 OpenClaw 技能，用于通过 pfSense REST API 实时查询和分析 pfSense 防火墙。
它是模型无关的：该技能从 pfSense 获取实时数据，并让当前的 OpenClaw agent 对其进行分析，而不是将工作流锁定到特定的 LLM 提供商。
## 功能
- 当 API 暴露 ARP/DHCP 数据时，使用 ARP/DHCP 查询已连接的设备
- 当 ARP/DHCP 不可用时，回退到从 `firewall/states` 推断的活动主机
- 检查活动的防火墙状态和实时连接
- 查看最近的防火墙活动
- 检查接口、网关和系统状态
- 审查防火墙规则
- 构建用于安全分类的实时快照
- 在快照内添加精简的 `summary` 层，以便更快地生成答案和报告
- 从实时 OpenAPI schema 发现支持的功能
- 在本地缓存 OpenAPI schema 以减少重复获取
## pfSense 前置条件
在 PfChat 工作之前，pfSense REST API 包必须已安装在防火墙上并可访问。
### 1. 安装 pfSense REST API 包
PfChat 依赖于上游的 **pfSense-pkg-RESTAPI** 包。
参考层级结构：
- 官方上游项目（规范源）：
- 发布的安装指南：
上游文档中的典型安装命令：
在 pfSense CE 上安装：
```
pkg-static add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-2.8.1-pkg-RESTAPI.pkg
```
在 pfSense Plus 上安装：
```
pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/latest/download/pfSense-25.11-pkg-RESTAPI.pkg
```
重要提示：
- 选择与您的 pfSense 版本匹配的包构建版本。
- pfSense 升级后，非官方包可能会被移除，因此可能需要重新安装 REST API 包。
- PfChat 已在本项目中针对暴露 `/api/v2/schema/openapi` 的真实 pfSense 安装进行了验证。
### 2. 在 pfSense 中配置 REST API
安装后，请在 pfSense 中验证以下项目：
- webConfigurator 中存在 `System -> REST API`
- REST API 已根据需要启用/配置
- 允许您选择的认证方法
- 用于 API key 的账户拥有您想查询的 endpoint 所需的权限
### 3. 创建 API key
PfChat 默认通过 `X-API-Key` 标头使用 **API key 认证**。
根据上游文档，API key 可以从以下位置创建：
- `System -> REST API -> Keys`
重要提示：
- API key 继承创建它们的用户的权限。
- 像保护密钥一样保护 API key。
- 如果 key 曾经泄露，请立即撤销并创建新的 key。
### 4. 在使用 PfChat 之前验证 API
在归咎于 PfChat 之前，进行一些有用的检查：
- 确认 API 在 `https:///api/v2/...` 响应
- 确认您的 API key 有效
- 确认实时 OpenAPI schema 可访问：
- `/api/v2/schema/openapi`
- 确认您关心的 endpoint 存在于该 schema 中
如果 `/api/v2/schema/openapi` 正常工作，PfChat 可以使用具备 schema 感知的发现功能，并更好地适应该安装环境。
## 快速开始
### 1. 配置 pfSense 访问
```
cp .env.example .env
```
示例：
```
PFSENSE_HOST=192.168.0.254
PFSENSE_API_KEY=replace-me
PFSENSE_VERIFY_SSL=false
```
注意：
- `PFSENSE_VERIFY_SSL=false` 保持 HTTPS 启用；它仅禁用证书信任验证。
- 当 pfSense 使用自签名证书或客户端主机上未安装的内部 CA 时，这是正常的。
- CLI 会根据脚本路径回退到项目本地的 `pfchat/.env`，这有助于从其他通道或工作目录调用技能时生效。
- `PFSENSE_HOST` 必须仅是主机名或 IP。不要包含 `https://` 或 URL 路径。
- `PFSENSE_API_KEY` 必须是真实的 key，而不是示例占位符。
- `PFSENSE_VERIFY_SSL` 接受 `true/false`、`1/0`、`yes/no` 或 `on/off`。
- 不要提交真实的 API key。
### 2. 运行直接查询
```
python3 pfchat/scripts/pfchat_query.py capabilities
python3 pfchat/scripts/pfchat_query.py devices
python3 pfchat/scripts/pfchat_query.py health
python3 pfchat/scripts/pfchat_query.py snapshot --limit 150
python3 pfchat/scripts/pfchat_query.py --once compact
python3 pfchat/scripts/pfchat_query.py --once wan
python3 pfchat/scripts/pfchat_query.py --once blocked
```
### 3. 从 OpenClaw 使用
典型提示：
- "check what devices are connected to pfSense"（检查连接到 pfSense 的设备）
- "see if there is anything suspicious on my firewall"（查看我的防火墙上是否有可疑内容）
- "what is iphoneLeo doing right now?"（iphoneLeo 现在正在做什么？）
- "what is my WAN address?"（我的 WAN 地址是什么？）
- "show me firewall rules related to OpenVPN"（显示与 OpenVPN 相关的防火墙规则）
## 示例输出
### 功能
```
{
"openapi_available": true,
"capabilities": {
"devices_arp": true,
"devices_dhcp": true,
"connections": true,
"logs_firewall": true,
"rules": true,
"interfaces": true,
"system_status": true,
"gateways": true
}
}
```
### 健康 / WAN
```
{
"gateways": [
{
"name": "WAN_DHCP",
"srcip": "142.197.33.220",
"monitorip": "142.197.33.1",
"status": "online"
}
],
"interfaces": [
{
"name": "wan",
"descr": "WAN",
"ipaddr": "142.197.33.220",
"gateway": "142.197.33.1",
"status": "up"
}
]
}
```
## 仓库布局
```
pfchat/
├── README.md
├── README.es.md
├── TODO.md
├── TODO.es.md
├── CHANGELOG.md
├── CHANGELOG.es.md
├── LICENSE
├── .gitignore
├── .env.example
├── dist/
│ └── pfchat.skill
└── pfchat/
├── SKILL.md
├── scripts/
│ ├── pfchat_query.py
│ └── pfsense_client.py
└── references/
├── endpoints.md
├── upstream-notes.md
└── investigation-patterns.md
```
## 自动化预设
PfChat 现在包含用于脚本编写和自动化的一次性预设：
- `--once compact` → 紧凑快照摘要
- `--once triage` → 更广泛的快照摘要
- `--once wan` → 聚焦 WAN 的健康输出
- `--once blocked` → 最近的拦截日志视图
有用的精简视图：
- `--view summary`
- `--view wan`
- `--view highlights`
示例：
```
python3 pfchat/scripts/pfchat_query.py --once compact
python3 pfchat/scripts/pfchat_query.py --once triage
python3 pfchat/scripts/pfchat_query.py --once wan
python3 pfchat/scripts/pfchat_query.py snapshot --limit 150 --view highlights
```
## 辅助 CLI
从仓库根目录运行：
```
python3 pfchat/scripts/pfchat_query.py capabilities
python3 pfchat/scripts/pfchat_query.py devices
python3 pfchat/scripts/pfchat_query.py connections --limit 200
python3 pfchat/scripts/pfchat_query.py connections --limit 100 --host 192.168.0.95
python3 pfchat/scripts/pfchat_query.py connections --limit 100 --port 443
python3 pfchat/scripts/pfchat_query.py logs --limit 200 --action block --interface vtnet1
python3 pfchat/scripts/pfchat_query.py logs --limit 200 --host 80.94.95.226
python3 pfchat/scripts/pfchat_query.py interfaces
python3 pfchat/scripts/pfchat_query.py health
python3 pfchat/scripts/pfchat_query.py rules
python3 pfchat/scripts/pfchat_query.py rules --filter descr__contains=OpenVPN
python3 pfchat/scripts/pfchat_query.py snapshot --limit 150
```
## Telegram 使用
如果 OpenClaw 已连接到 Telegram，您不需要在 PfChat 内部使用单独的 bot。您可以从 Telegram 与 OpenClaw 对话，并让它在后台使用 PfChat 查询 pfSense。
有关建议的提示、推荐的工作流程和告警基准，请参阅 `TELEGRAM.md`。
## 每日邮件摘要
当 OpenClaw 配置了 Resend 时，PfChat 可以生成每日防火墙摘要并通过电子邮件发送。
包含的本地脚本：
- `scripts/send_daily_summary.py`
在此主机上，cron 任务和隔离会话继承全局变量的正确方法是通过 `EnvironmentFile` 从 `openclaw-gateway.service` 单元加载它们。
PfChat 报告应优先使用本地清单（`TOOLS.md`）中的设备名称。如果不存在本地映射，它们可以使用反向查找，并仅将 IP 作为回退细节保留。
## 测试
使用 Python 标准库运行当前的测试套件：
```
python3 -m unittest discover -s tests -v
```
该套件包括：
- 用于解析、配置验证、schema 缓存和摘要逻辑的单元测试
- 用于设备清单和快照流程的模拟集成测试，无需真实的 pfSense 实例
## 参考文档
其他参考资料：
- `pfchat/references/output-shapes.md` — 每个命令的高级 JSON 输出结构
- `pfchat/references/investigation-examples.md` — 实际调查工作流程和示例命令
- `pfchat/references/endpoints.md` — endpoint 和回退说明
- `pfchat/references/upstream-notes.md` — 上游 pfrest/OpenAPI 说明
## 当前状态
PfChat 已涵盖实时 API 工作流。目前的重点是健壮性、版本兼容性和运维完善。
有关待办事项、最近更改和使用模式，请参阅 `TODO.md`、`TODO.es.md`、`CHANGELOG.md`、`CHANGELOG.es.md`、`TELEGRAM.md` 和参考文档。
## 许可证
MIT
标签：LLM Agent, OpenAPI, OpenClaw, pfSense, REST API, 后渗透, 安全态势感知, 开源, 技能插件, 插件系统, 无线安全, 系统分析, 系统状态检测, 网络分析, 网络可见性, 网络安全, 网络安全审计, 网络流量, 网络设备, 自动化运维, 进程隐藏, 逆向工具, 防火墙, 防火墙规则, 隐私保护