Machine Loader 的安全模型、信任根和漏洞披露政策。
Machine Loader 采用分层信任模型：
用户
↓
Machine 加载器（已签名，信任根）
↓
Machine.Core.dll（已签名，核心）
↓
Mod DLL（用户自行选择安装，非默认信任）
↓
游戏代码（注入，已备份可还原）
| 层级 | 对象 | 信任级别 | 说明 |
|---|---|---|---|
| L0 | 用户 | 最高 | 用户拥有最终决定权 |
| L1 | Machine 加载器 | 完全信任 | 安装器和更新器，RSA 签名 |
| L2 | Machine.Core.dll | 完全信任 | 核心运行时，RSA 签名 |
| L3 | 官方 Mod | 信任 | 官方维护，随发布包分发 |
| L4 | 第三方 Mod | 用户决定 | 用户自行安装，加载器提示风险 |
| L5 | 游戏代码 | 注入 | 已备份，可完全还原 |
Machine 的信任根是编译进客户端的 RSA-3072 公钥：
- 公钥位置：
dist_upload/release_pubkey.pem - 私钥位置：仅由发布者持有，离线存储
- 签名算法：RSA-SHA256
- 密钥长度：3072 位
以下文件不是信任根，不能改变"只有持私钥者签名的 DLL 才被接受"这一原则：
- ❌
update.json- 更新配置，可被篡改但不影响签名校验 - ❌
version.json- 版本信息，仅用于显示 - ❌
installed.json- 已安装记录，仅用于本地状态 - ❌
config.json- 用户配置，不影响安全校验
1. 下载更新包
↓
2. 校验 SHA-256 哈希（防传输损坏）
↓
3. 校验 RSA 签名（防篡改，信任根验证）
↓
4. 校验清单 schema（防格式错误）
↓
5. 校验下载地址白名单（防恶意重定向）
↓
6. 校验通道过滤（防版本降级）
↓
7. 写入前再校验（防 TOCTOU 攻击）
↓
8. 原子替换（防半更新状态）
↓
9. 写入后复核（防写入错误）
| 机制 | 说明 |
|---|---|
| SHA-256 | 每个文件的哈希，防止传输损坏 |
| RSA-3072 签名 | 整个更新包的签名，防止篡改 |
| 清单 schema 校验 | 验证更新清单格式正确 |
| 下载地址白名单 | 只允许从指定域名下载 |
| 通道过滤 | 防止从 stable 通道降级到 dev |
| 机制 | 说明 |
|---|---|
| 备份 | 更新前自动备份原文件 |
| 原子替换 | 先写入临时文件，再原子重命名 |
| 自动回滚 | 更新失败自动还原到备份 |
| 版本撤销 | 支持标记某版本为已撤销，拒绝安装 |
| 审计日志 | 记录所有更新操作，便于排查 |
- 更新器检查目标版本必须 >= 当前版本
- 支持
is_version_revoked标记，撤销有安全漏洞的版本 - 通道过滤：stable 通道不会接受 dev 版本
| 环节 | 位置 | 校验内容 | 失败行为 |
|---|---|---|---|
| 1. 清单 schema 校验 | validate_update_config() |
JSON 格式、必需字段、类型 | 拒绝更新，提示清单损坏 |
| 2. 下载地址白名单 | machine_update.py |
URL 域名是否在白名单 | 拒绝下载，提示地址不安全 |
| 3. 通道过滤 | machine_update.py |
目标通道是否允许 | 拒绝更新，提示通道不匹配 |
| 4. SHA-256 校验 | sha256_file() |
文件哈希是否匹配清单 | 拒绝安装，提示文件损坏 |
| 5. RSA 签名校验 | rsa_verify_sha256() |
签名是否由信任私钥生成 | 拒绝安装，提示签名无效 |
| 6. 写入前再校验 | machine_update.py |
临时文件哈希再次校验 | 中止安装，保留备份 |
| 7. 备份 | backup_files() |
原文件备份成功 | 中止安装，不修改原文件 |
| 8. 原子替换 | os.replace() |
临时文件原子重命名 | 自动回滚到备份 |
| 9. 写入后复核 | verify_installation() |
安装后文件哈希校验 | 自动回滚，提示安装失败 |
| 10. 安装器哈希比对 | install_machine.py |
安装器自身哈希校验 | 拒绝运行，提示安装器损坏 |
- 全异常捕获：所有外部操作都在 try/except 中
- 返回码检查：每个操作检查返回码，非零即失败
- 路径探测：操作前检查路径存在性和权限
- 游戏运行检测：更新前检测游戏是否在运行，运行中拒绝更新
- 权限检测：检测是否有写入权限
- 全量日志：记录所有操作和结果
config.jsonschema 校验update.jsonschema 校验mod.jsonschema 校验- 无效配置使用默认值，不崩溃
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 通用错误 |
| 2 | 参数错误 |
| 3 | 网络错误 |
| 4 | 哈希校验失败 |
| 5 | 签名校验失败 |
| 6 | 备份失败 |
| 7 | 写入失败 |
| 8 | 游戏运行中 |
- Mod DLL 不强制签名（用户可自行安装第三方 Mod）
- 加载器在 Mod 管理器中显示 Mod 来源和状态
- 异常隔离：单个 Mod 异常不影响其他 Mod
- 自动禁用：连续异常超过 10 次自动禁用该 Mod
- 依赖检查：缺失前置 Mod 时明确提示，不静默加载
Mod 运行在与游戏相同的进程中，拥有与游戏代码相同的权限。这意味着：
⚠️ Mod 可以访问游戏内存⚠️ Mod 可以读写文件系统⚠️ Mod 可以访问网络⚠️ Mod 可以执行任意代码
建议：只从可信来源安装 Mod，安装前查看 Mod 源码。
- 支持
conflicts字段声明冲突 - 冲突 Mod 自动禁用，不崩溃
- 明确提示用户哪个 Mod 与哪个 Mod 冲突
如果你发现了安全漏洞，请不要公开提交 Issue，而是通过以下方式私密报告：
- GitHub Security Advisories：新建安全公告
- 邮件：发送邮件给项目维护者（请在 GitHub 个人主页查找）
请包含以下信息：
- 漏洞类型（例如：签名绕过、任意代码执行、权限提升）
- 受影响版本
- 复现步骤
- 概念验证代码（如适用）
- 潜在影响
- 你的联系信息（可选）
我们遵循 Responsible Disclosure（负责任披露）原则：
- 报告者私密提交漏洞
- 维护者在 7 天内确认收到
- 维护者在 30 天内修复或提供缓解措施
- 修复发布后，漏洞可公开讨论
- 报告者将在安全公告中获得致谢（如愿意）
- ❌ 不要在公开 Issue 中披露漏洞细节
- ❌ 不要利用漏洞进行攻击
- ❌ 不要访问或修改他人数据
- ❌ 不要进行拒绝服务测试
- 影响范围：签名绕过、任意代码执行、权限提升
- 响应时间：7 天内发布修复
- 通知方式：GitHub Security Advisory + 游戏内更新提示
- 版本撤销：标记受影响版本为已撤销
- 影响范围：信息泄露、拒绝服务
- 响应时间：14 天内发布修复
- 通知方式：GitHub Security Advisory
- 版本撤销：视情况决定
- 影响范围：理论漏洞、难以利用
- 响应时间：下一个常规版本修复
- 通知方式：CHANGELOG 记录
感谢以下人员对 Machine Loader 安全的贡献：
- （暂无，欢迎提交漏洞报告）
- 安全公告：GitHub Security Advisories
- 一般问题：GitHub Discussions
- 项目主页：https://github.com/AODOJUST/MachineLoader
最后更新：2026-09-13