本文档说明 ServerProbe 的信任模型、敏感数据处理、外部输入校验与漏洞报告渠道。安全模型发生变化时应同步更新本文档。
现状声明:项目尚未发布、未经生产环境验证,仅 1.21.4 Paper 单端真机验证。本文档忠实描述当前代码与配置的实际行为,不代表已经过独立安全审计或专业加固。
ServerProbe 的首要安全原则是 「只读优先,绝不成为事故源」:探针主体只做只读采集(纯 API + JMX + 平台原生 API + 采样),不修改运行时状态。在此前提下,对外暴露的几处出口构成信任边界:
| 出口 | 信任边界 | 默认状态 |
|---|---|---|
跨插件只读 API(ProbeReadApi / ServerProbeApi / MetricStore SPI) |
仅暴露查询(最新快照 / 历史区间 / 启动画像 / 聚合),不暴露任何写入或控制能力。第三方插件只能读取探针数据,无法借此改动服务器或探针自身。 | 随插件加载即可用 |
Prometheus /metrics 端点(FR4.2) |
默认关闭;开启后默认仅绑定本机回环 127.0.0.1;鉴权采用 token(Authorization: Bearer)+ IP 白名单双重校验(两者叠加生效)。 |
enabled: false,host: 127.0.0.1,allowed-ips: [127.0.0.1] |
游戏内命令 /probe … |
权限受控,经权限节点门控;告警游戏内通道仅推送给在线 OP 或持 serverprobe.alert 权限的玩家。 |
随插件加载,受权限节点约束 |
可选启动期 agent(-javaagent,FR1.7) |
需运维手动在启动命令中加 -javaagent:plugins/ServerProbe.jar 才生效;走标准 premain 入口(非运行时 self-attach),顶层 catch(Throwable) 兜底,启用失败一律静默降级,绝不崩 JVM。 |
不加参数则纯插件模式,agent 不生效 |
| 告警 Webhook 通道(FR5) | 默认关闭;开启后把告警以 JSON POST 到运维自配的外部地址。 | alert.enabled: false 且 webhook.enabled: false |
攻击面概览:在默认配置下,ServerProbe 不开放任何网络监听端点、不向外发起请求(可选 agent 的 HTTP/TCP 外呼监控为只读拦截、不主动外呼),对外仅有受权限约束的游戏内命令与只读 API。需要远程抓取(Prometheus)或外部投递(Webhook)时,均须运维显式开启并自行配置鉴权,默认不「裸奔」对外。
以下敏感项写在 plugin/src/main/resources/config.yml,由运维自行填写与保管:
metrics.token:Prometheus 端点鉴权 token(留空则不启用 token 鉴权,仅靠 IP 白名单)。alert.channels.webhook.url:告警 Webhook 回调地址,可能本身含 token,请勿外泄。
约定:
- 仓库内的示例 / 默认配置中,上述敏感项保持留空,不应填入任何真实 token、真实 Webhook 地址或内网地址。
- 不应将真实密钥硬编码进代码、注释、日志或提交信息。
- 修改后的含真实密钥的
config.yml属运维侧机密,不应入库。
- 探针自身日志不输出路径 / token:Webhook 地址即便含 token,探针也绝不将其写入日志(见
config.yml内注释说明)。 - HTTP/TCP 外呼监控的 agent 侧脱敏(M5,需
-javaagent启用):- URL 查询串与请求头中的
Authorization/Cookie/token等敏感项,由 agent 侧打码为***后才记录。 - 请求体不在捕获范围(从不读取、从不落盘对外请求的 body)。
- 采用有界环形缓冲,防止记录无限增长导致内存与数据泄漏。
- 外呼日志默认不附带请求头(
http-monitor.log-headers: false);即便开启,附带的也是已脱敏的请求头。
- URL 查询串与请求头中的
- 命令输入:
/probe …各子命令经权限节点门控,只有持相应权限者可执行;告警游戏内通道仅面向 OP 或持serverprobe.alert权限者。 - 配置项容错:配置项均有默认值与容错处理。典型如 Prometheus 端口被占用(含 Windows 动态保留端口场景)时优雅降级、不影响插件正常启用(已在真机印证);Webhook 超时过小会被兜底为下限。
- agent 字节码插桩的安全约束(可选 agent,M5):
- 插桩生成的字节码经 ASM
CheckClassAdapter对真实 JDK 类校验合法后才应用,确保不产出非法字节码。 - 插桩与外呼记录逻辑全程
try/catch兜底,premain顶层再以catch(Throwable)包裹,任何异常只静默降级为「agent 未生效」,绝不向上抛、绝不破坏或崩溃 JVM。 - 跨 ClassLoader 通道只把极薄、零反向依赖的
ProbeAgentBridgeappend 到 bootstrap ClassLoader(纯数据中转),严守「bootstrap CL 上只放对所有 CL 安全可见的最小桥接类」的边界,避免双向越界引发IllegalAccessError。
- 插桩生成的字节码经 ASM
⚠️ 占位说明:本项目尚未发布、暂无公开远程仓库(remote),以下报告渠道为临时约定,待维护者补充正式联系方式后更新本节。
如发现安全问题:
- 请经项目维护者渠道私下上报,不要在公开 issue 中暴露漏洞细节,以免在修复前被利用。
- 报告时请尽量提供:受影响版本 / 端、复现步骤、影响范围与可能的利用方式。
- 维护者会在收到报告后尽快确认与评估;在修复发布前,请报告者遵循负责任披露原则,暂不公开细节。
- 修复发布后,可与维护者协商披露时间点与致谢方式。
待维护者补充:
- 安全问题专用联系邮箱 / 私密上报入口(项目发布并建立公开 remote 后补充)。
- 明确的响应时限(SLA)与披露时间窗约定。