secubox-openwrt/package/secubox/secubox-mcp-server/README.zh.md

English | Francais | 中文

SecuBox MCP 服务器

SecuBox 的模型上下文协议（MCP）服务器。通过 stdio 上的 JSON-RPC 2.0 向 AI 助手（Claude Desktop、Cursor、VS Code）公开设备安全数据。

版本：1.0.0

概述

MCP（模型上下文协议）是 Anthropic 的开放协议，允许 AI 助手访问本地数据源。该服务器为 AI 工具提供 SecuBox 安全数据，用于：

• 实时威胁情报分析
• CVE 漏洞查询和缓解建议
• WAF 过滤规则建议
• 安全态势评估
• 网络和系统监控

安装

opkg install secubox-mcp-server

可用工具

安全工具

工具	描述
crowdsec.alerts	获取活跃的 CrowdSec 安全警报
crowdsec.decisions	获取活跃的阻止决策
waf.logs	从 mitmproxy 获取 WAF 威胁事件

网络工具

工具	描述
network.flows	获取网络流量摘要
wireguard.status	获取 VPN 隧道状态
dns.queries	获取 DNS 查询统计

系统工具

工具	描述
system.metrics	获取 CPU、内存、磁盘、温度
uci.get	读取 OpenWrt UCI 配置
uci.set	写入 UCI 配置（默认禁用）

AI 工具（需要 LocalAI）

工具	描述
ai.analyze_threats	AI 分析 CrowdSec 警报并提供建议
ai.cve_lookup	CVE 漏洞分析和缓解建议
ai.suggest_waf_rules	AI 建议的 mitmproxy/WAF 过滤模式
ai.explain_ban	解释为什么某个 IP 被封禁
ai.security_posture	安全态势评估

Claude Desktop 集成

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "secubox": {
      "command": "ssh",
      "args": ["root@192.168.255.1", "/usr/bin/secubox-mcp"]
    }
  }
}

然后重启 Claude Desktop。提问示例：

• "我的路由器上当前有什么安全威胁？"
• "分析 CVE-2024-1234 并建议缓解措施"
• "我的网络流量摘要是什么？"
• "根据最近的攻击建议 WAF 规则"

配置

UCI 配置：/etc/config/mcp-server

config mcp-server 'main'
    option enabled '1'

    # 工具白名单 - 只有这些工具可以被调用
    list allowed_tool 'crowdsec.alerts'
    list allowed_tool 'crowdsec.decisions'
    list allowed_tool 'waf.logs'
    list allowed_tool 'dns.queries'
    list allowed_tool 'network.flows'
    list allowed_tool 'system.metrics'
    list allowed_tool 'wireguard.status'
    list allowed_tool 'uci.get'
    # list allowed_tool 'uci.set'  # 默认禁用

    # AI 工具（需要 LocalAI）
    list allowed_tool 'ai.analyze_threats'
    list allowed_tool 'ai.cve_lookup'
    list allowed_tool 'ai.suggest_waf_rules'
    list allowed_tool 'ai.explain_ban'
    list allowed_tool 'ai.security_posture'

    # 数据主权分类
    option classification 'local_only'

启用/禁用工具

# 启用 uci.set（注意 - 允许配置更改）
uci add_list mcp-server.main.allowed_tool='uci.set'
uci commit mcp-server

# 禁用工具
uci del_list mcp-server.main.allowed_tool='ai.security_posture'
uci commit mcp-server

测试

本地测试协议

# 初始化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /usr/bin/secubox-mcp

# 列出工具
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /usr/bin/secubox-mcp

# 调用工具
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"system.metrics","arguments":{}}}' | /usr/bin/secubox-mcp

通过 SSH 测试

ssh root@192.168.255.1 '/usr/bin/secubox-mcp' <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"crowdsec.alerts","arguments":{"limit":10}}}
EOF

LocalAI 集成

AI 工具需要设备上运行 LocalAI：

# 安装并启动 LocalAI
opkg install secubox-app-localai
localaictl install
localaictl model-install tinyllama
uci set localai.main.enabled=1
uci commit localai
/etc/init.d/localai start

AI 工具将自动使用 http://127.0.0.1:8081 上的 LocalAI 进行分析。

安全考虑

1. 工具白名单：只有 UCI 配置中列出的工具可以被调用
2. uci.set 禁用：默认禁用写访问
3. 敏感数据阻止：uci.get 阻止 password/secret/key 字段
4. 需要 SSH：MCP 通过 SSH 运行 - 需要密钥认证
5. 数据分类：所有数据默认标记为 LOCAL_ONLY
6. 无云端升级：服务器完全在设备上运行

文件

文件	描述
/usr/bin/secubox-mcp	主 MCP 服务器
/usr/lib/secubox-mcp/protocol.sh	JSON-RPC 协议处理器
/usr/lib/secubox-mcp/tools/*.sh	工具实现
/etc/config/mcp-server	UCI 配置

依赖

• jsonfilter — JSON 解析（OpenWrt 原生）
• cscli — CrowdSec CLI（用于 crowdsec 工具）
• wg — WireGuard 工具（用于 wireguard 工具）
• secubox-app-localai — LocalAI（用于 AI 工具）

协议

MCP 使用 stdio 上的 JSON-RPC 2.0：

• 传输：stdin/stdout
• 协议版本：2024-11-05
• 方法：initialize、tools/list、tools/call、ping

许可证

MIT

参考

• 模型上下文协议规范
• Claude Desktop MCP 指南
• SecuBox 文档