Files
usdt/docs/security-hardening.md
2026-11-16 02:09:23 -05:00

118 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Quartz 入侵链修复与网络隔离部署
## 本轮实现
`sys_job` 的恶意调用链为 Quartz → 任意类反射 → SnakeYAML → 远程 JAR。
修复作用于后续执行,不能证明已被入侵的操作系统恢复可信,也不删除数据库中的取证记录。
1. Quartz 仅能调用已有 Spring Bean 上标记 `@AllowedJobMethod` 的 public、非 static、void 方法,
并精确匹配参数类型。禁止完整类名实例化、继承的通用对象方法、表达式及非标量参数。
新增、修改、恢复、立即运行、创建调度和最终执行均校验;最终执行检查不能通过直接改库绕过。
2. 启动发现非法任务只记录 jobId 并跳过,不修改原记录、不阻止合法任务启动。
因此历史恶意记录仍可能显示“正常”,但不会被本轮版本加载执行。
3. 两个根 POM 统一锁定 SnakeYAML 2.3。`SafeYamlPropertySourceLoader` 在 Spring 启动前注册,
适配 Boot 2.2,使用 SafeConstructor、禁止重复键、限制别名 50、嵌套 50 层及 3 Mi 字符输入。
展开阶段拒绝循环别名,限制展开节点 100000;保留普通 Map/列表、占位符、Unicode、多文档 profile
选择与简单锚点;不打印配置 Map。
适配器返回标准属性源,不提供旧 OriginTrackedYamlLoader 的逐字段行号元数据。
4. Java 入口增加 `/monitor/job`、`/monitor/jobLog`、`/druid` 来源 CIDR 检查(包含子路径及旧 MVC 后缀)。
默认仅允许回环对端,不读取 X-Forwarded-For;来源通过后仍须原有认证/权限检查。
支付 API、回调、OAuth、WebSocket 及 `@Scheduled` 调度不在该限制范围。
## 现有任务兼容
当前已授权的专用任务入口:
| Bean | 方法 |
| --- | --- |
| ryTask | ryNoParams、ryParams(String)、ryMultipleParams(String,Boolean,Long,Double,Integer) |
| dmPlayerentOnlineStatusTask | execute |
| paymentLedgerReconciliationTask | reconcile |
| paymentOrderExpireTask | expireOrders |
| payoutConfirmationTask | confirm |
| tronPaymentTask | scan |
| usdtConfigBalanceRefreshTask | refresh |
| walletSnapshotRefreshTask | produce |
原有无参 `bean.method` / `bean.method()` 和单引号字符串、Boolean、Long(L)、Double(D)、Integer
调用格式保留;正常支付、归集和钱包派生逻辑没有改写。
数据库无法从本机连接,因此部署前仍须核对真实库内其他合法 Quartz 任务。
如有表外自定义任务,应审查对应专用 Bean 及方法后在源码加注解并测试,不能放行任意包或通用 Service。
`UsdtAggregationExecutorTask` 当前不是 Spring Bean,也没有启用调度;本次没有额外启用该旧执行器。
## 构建与更新范围
两个项目是独立 Maven reactor,Quartz 来自兄弟目录,必须先构建它:
```powershell
cd D:/myprojects/usdt/ruoyi-common
mvn -pl ruoyi-quartz -am install
cd ../myEpusdt
mvn clean package -DskipTests
```
外置 lib 部署使用新的干净发布目录,包含新 `ruoyi-admin.jar`、`ruoyi-system-3.4.0.jar`、
`ruoyi-quartz-3.4.0.jar`、`snakeyaml-2.3.jar` 及本轮依赖清单中的其他 JAR。
不要往旧 lib 叠加文件;旧 `snakeyaml-1.*.jar`、旧 Quartz 或旧 system 不能留在同一 classpath。
保留原部署目录用于取证/恢复配置;不能通过回滚到有漏洞的旧程序恢复运行。
若独立链上执行器也部署,使用本轮构建的执行器制品,避免继续携带旧 YAML 依赖。
## 管理来源和代理配置
**同机 Nginx:** 保留当前 profiles 并追加 `hardening`(例如 `prod,rental,hardening`),
使 Java 只监听 127.0.0.1。Nginx 的所有业务上游需指向该回环端口;该 profile 不应直接用于跨主机代理。
`deploy/security/nginx-admin-allow.conf` 加入实际管理员公网 IP/VPN CIDR 后复制到
`/etc/nginx/snippets/usdt-admin-allow.conf`,把 `nginx-management.conf` 合入现有 server。
按实际 Java 端口及前端 API 前缀调整模板,不替换原 TLS、公共 API、WebSocket 配置。
模板默认只允许回环,不含虚构的管理员 IP。
已有 `^~ /prod-api/`、更早的正则或精确 location 可能使安全 location 失效,必须用 `nginx -T`
核查优先级;必要时把相同 allow 规则直接合并到现有管理 location。
若前面还有 CDN/LB,仅信任明确代理网段的 real_ip 配置,不能信任客户端转发头。
Java 默认只能看到同机代理地址,所以**代理层来源控制不可省略**。
跨主机代理/管理员直连时,用外部配置设置:
```text
SECURITY_MANAGEMENT_ALLOWED_CIDRS=10.8.0.0/24,192.0.2.10/32
```
上述地址仅为格式示例,必须换成真实可信网段;跨主机 Java 应绑定私网地址,主机安全组仅允许代理访问。
如需整个管理站只限 VPN,使用独立管理域名并在 server 层 include 来源规则;原公共支付域名继续提供
商户 API、支付/租赁回调、OAuth 回调、Telegram webhook 和节点 WebSocket,不能直接对公共 server 全面 deny。
先执行 `nginx -t`,再 reload;验证可信来源能管理任务,不可信来源返回 403,伪造 X-Forwarded-For 仍拒绝。
确认公网不能直接访问 Java、3306 和 6379;MySQL/Redis 若在独立主机上,用其安全组仅放行业务私网来源。
## 出站控制
`deploy/security/egress.nft.example` 是专用服务 UID 的 IPv4/IPv6 出站允许列表模板,未在本机或服务器加载。
先用真实服务用户 UID 替换 99999,并填充 dns、database、business 地址集合及实际端口。
不能以 root 运行服务后对整个 root UID 套用该规则;容器需在其实际网络命名空间/转发链上配置等价策略。
业务清单至少核实:MySQL、Redis、DNS、TRON 主网/Nile 的 HTTP/gRPC、TronGrid/TronScan、
链上执行器、资源租赁供应商、商户支付/代付/租赁回调、Google OAuth、Telegram、OSS/MinIO 及启用的插件外联。
动态域名的 IP 变更和 IPv6 必须一并维护;任意公网商户回调应经受控出站代理动态审批,不能使用固定
IP 模板后假定所有回调可用。不要通过允许所有 443 来“修复”连接失败,这会放回恶意 HTTPS 下载。
先在隔离测试环境核对业务目标,使用 `nft -c -f <配置文件>` 校验后再安排实际部署。
表名为 `usdt_egress`,不执行 `flush ruleset`;回退时只移除该专用表,不清空其他防火墙。
模板保留 established/related,部署切换需重启应用以断开旧恶意连接。
默认空集合会拒绝未登记的业务外联,因此不能原样应用。
本机是 Windows,未提供远程 Linux 会话,不能宣称已完成 Nginx/nftables 的线上生效验证。
## 发布后核验
本地验证:Quartz 安全测试 6 项、安全 YAML 6 项、管理来源过滤 4 项、当前全部配置兼容 1 项,
合计 17 项全通过;另有原业务/诊断回归 91 项,0 失败、1 项真实转账测试跳过。
最终制品 classpath 的 11 项 YAML/来源测试复测通过;已核对外置 lib 仅含 SnakeYAML 2.3,
Quartz 源码制品与发布依赖的 SHA256 相同,执行器也包含更新后的 YAML/system。
本地未启动连接真实数据库和链上的完整业务应用;以下线上核验需在部署环境完成。
- 日志中的任务 8/12 等非法 jobId 被拒绝加载;其他合法任务按期运行。
- 数据库任务管理的新增、修改、恢复和立即执行均拒绝非法目标,且没有发起网络解析。
- 支付创建/查询、入账扫描、回调、资源租赁及执行器调用在隔离环境分别验证。
- 核对实际加载的 SnakeYAML 只有 2.3,启动没有 NoSuchMethodError。
- 保留 `[NETWORK-TRACE]` 观察窗口,确认不再由恶意任务触发 Pinggy 外联。