解读 Motrix 安全策略：支持版本、漏洞报告流程与源码中的安全信任边界

Motrix 的安全策略（SECURITY.md）明确了三件事：哪些版本会收到安全修复、疑似漏洞应如何私密报告、以及策略覆盖的组件范围。这篇文章以该文档为骨架，逐节拆解其条款含义，并结合仓库中的源码与测试用例，说明策略中提到的"沙箱、权限模型、更新校验、宿主集成"在 Motrix Turbo v2 代码库里具体对应哪些实现，帮助安全研究者与贡献者精准判断一个问题的归属并写出高质量的漏洞报告。

支持版本：只有"最新发布的 v2"在修复范围内

原文档的"Supported Versions"一节给出的支持矩阵是：

版本	是否支持
最新发布的 Motrix Turbo v2 版本	是
较早的 Motrix Turbo v2 预发布版本	否
旧版 Motrix v1 版本	否

三条要点需要准确理解：

1. 修复只投放在最新发布的 Motrix Turbo v2 发布线上。"Motrix Turbo" 是 v2 线的产品代号，仓库 package.json 中 "name": "motrix-turbo"、当前开发版本为 2.0.0-beta.x（预发布系列），而 productName 保持为 Motrix，这与策略中"Turbo v2 release" 的表述对应。
2. 预发布版本（prereleases）不在例行的安全支持范围内。也就是说，如果你持有某个较早的 beta 版本，维护者通常不会单独为它出补丁。
3. v1 旧发布线已冻结，不再提供安全修复。

由此得出的报告建议（原文档明确要求）：在条件允许的情况下，先在最新版本上复现问题再提交报告。这样做的实际价值在于——维护者需要评估修复是否值得投入，以及漏洞是否已经在较新版本中通过其他改动被消解；在最新线上无法复现的报告会被显著降低优先级。

报告漏洞：走私密通道，不走公开 Issue

文档"Reporting a Vulnerability"一节的硬性规则是：不要为疑似漏洞创建公开的 Issue、Discussion 或 Pull Request，而是通过 Motrix 项目页面的 GitHub 私密漏洞报告入口（Security Advisories）进行提交。这一条对下游集成方和安全研究人员尤其重要：把未修复的漏洞细节暴露在公开仓库中会直接扩大被利用的窗口期。

报告内容要求尽量完整，原文档列出的五项信息构成了一份合格的报告清单：

• 受影响的 Motrix 版本、运行方式（runtime）、操作系统与处理器架构——"runtime" 一词对应 Motrix 的多种形态：桌面端（Electron）、服务端（Server/容器）等，同一个漏洞在不同形态下可能只影响其一；
• 受影响的组件与安全影响（例如插件宿主、aria2 引擎通信、桥接服务器等）；
• 最小的可靠复现步骤或概念验证（PoC）；
• 相关日志或截图，且必须移除凭证、令牌、私有 URL 和个人路径（这一要求与 Motrix 自身的日志脱敏机制一致，仓库中存在专门的 日志脱敏模块）；
• 已知的缓解措施或修复建议。

后续流程上，维护者会在私密 Advisory 通道内保持沟通，并根据严重程度与维护资源协调修复与披露。文档同时要求报告方承担保密义务：在修复或安全公告发布之前，或双方另行约定披露之前，不得公开漏洞详情。这是典型的双向 NDA 式协作约定，理解这一点可以避免"报告后被公开引用"的纠纷。

适用范围：策略覆盖了哪些产物

"Scope" 一节列出的覆盖清单是：Motrix 桌面端与 Server 应用、原生消息宿主（native messaging host）、官方发布产物与容器镜像，以及本仓库中的第一方代码。把这条清单映射到仓库中的实际位置，可以更准确地判断一个漏洞是否属于 Motrix 的责任范围：

策略中的对象	仓库中的对应位置
桌面端应用	Electron 主/预加载/渲染进程代码，见 src/main、src/preload、src/renderer
Server 应用	独立的服务端入口与 HTTP 层，见 src/server/index.ts
原生消息宿主	Rust 编写的浏览器 Native Messaging 宿主，见 packages/native-host
官方发布产物	由 electron-builder.json 定义打包目标与签名配置
容器镜像	构建入口为 Dockerfile 与 compose.yaml
第一方代码	src/ 下的全部 TypeScript 代码

清单中的边界案例同样被原文档写明：第三方插件或服务的漏洞应报告给对应维护者；但有一个重要例外——如果该问题同时证明了 Motrix 自身的**沙箱（sandbox）、权限模型（permission model）、更新校验（update verification）或宿主集成（host integration）**存在漏洞，则应向 Motrix 报告。普通 Bug 与支持请求则走公开的 Issue 表单或 Discussions，不属于本策略范畴。

下面四个小节结合源码，逐一对应上述四类信任边界，说明它们在代码中的落点。

更新校验：内置插件热更新的 ed25519 签名信任边界

策略中"update verification" 对应的核心实现是内置插件热更新链。src/shared/builtin-signing.ts 在构建期固化了一组 Ed25519 公钥（PEM 格式数组），注释明确写着 "NEVER runtime-configurable"（运行时绝不可配置），并说明设计成数组是为了支持密钥轮换——换钥时可以同时下发新旧两把公钥，任一匹配即通过校验：

// Build-time pinned trust root(s) for builtin plugin hot updates
// NEVER runtime-configurable.
export const BUILTIN_SIGNING_PUBKEYS: ReadonlyArray<string> = [
  `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAbjfyCWHmZ8THA3nyliDdV6ADjXdVKAo5DBFlu8Vv6SY=
-----END PUBLIC KEY-----
`,
]

校验函数 verifyBuiltinSignature 采用**硬失败关闭（fail closed）**策略：Base64 解码失败、签名长度为零、所有固定公钥都无法通过 node:crypto 的 verify 验证，一律返回 false，调用方直接拒绝安装。热更新流程 builtin-updater.ts 中，缺少签名会报 builtin_no_signature，签名不匹配会报 builtin_bad_signature，且文件只有在签名判定通过后才落盘重命名——"the ed25519 signature is the trust decision"（源码注释原文）。signature.test.ts 与 builtin-updater.test.ts 配套测试覆盖了"篡改字节、错误密钥、垃圾签名均被拒绝"的场景，其中一条用例明确指出 SHA-256 摘要匹配但签名者不是固定密钥时依然拒绝，防止仅凭摘要比对建立的信任。

应用级自动更新（electron-updater）的发布产物也有对应的校验脚本 scripts/verify-update-artifacts.mjs，并可通过 package.json 中的 check:update-artifacts 脚本运行。如果你在供应链或更新链路上发现可被利用的问题，按 Scope 条款它属于应向 Motrix 报告的范畴。

沙箱与权限模型：插件宿主的进程外隔离

Motrix 的插件不运行在 Node 主进程里，而是运行在 QuickJS 引擎的 worker 中，这本身就是第一层沙箱。从源码结构看，插件宿主位于 src/core/plugin/host：quick-js-worker.ts 负责在 QuickJS 运行时内执行插件代码，capability-bridge.ts 是插件访问宿主能力的唯一桥梁，配套测试如 capability-bridge.permission.test.ts 与 capability-bridge.ffmpeg-gate.test.ts 验证了能力调用的权限门控与阶段约束；熔断机制位于 src/core/plugin/circuit，秘密存储 secret-store-libsodium.ts 使用 libsodium 做加密。

因此，判断"这是第三方插件的 Bug 还是 Motrix 沙箱逃逸"的依据很清晰：若恶意/缺陷插件代码仍被限制在 QuickJS 运行时内、无法触达未经授权的能力，那是插件自身问题；若能通过能力桥、钩子分发或更新通道突破边界，则属于策略中明确点名的沙箱/权限模型漏洞，应报告给 Motrix。

宿主集成：Native Messaging 宿主与 Flatpak 双层边界

"host integration" 在仓库中主要指浏览器 Native Messaging 集成，尤其是 Flatpak 场景下的双层结构，packages/native-host/README.md 对此有完整说明。从源码结构看，设计上有两个刻意分离的层：

1. motrix-flatpak-native-host 运行在 Flatpak 沙箱之外，作为浏览器的 Native Messaging 宿主，负责浏览器清单、启动固定的 Motrix Flatpak 应用，并只转发"带帧结构的配对请求"；
2. motrix-native-host-broker 运行在 Motrix 的 Flatpak 沙箱之内（见 flatpak_companion.rs），负责解析桥接端点、做 localhost 健康检查并获取一次性 nonce。README 原文强调"companion does not reimplement or weaken this security boundary"（宿主侧组件不重实现也不削弱沙箱侧的安全边界）。

这一层有大量可审计的加固细节：安装过程拒绝符号链接、外部属主、组/他人可写的路径成分；新建私有目录使用 0700 模式，宿主二进制用 0700，配置与清单用 0600，且不依赖调用方的 umask；自定义 Flatpak 可执行文件按规范路径存储并在每次运行时重新验证；宿主侧组件不依赖 Node.js、Electron 或 PATH 中任何解释器。这些特性本身不构成漏洞，但它们划定了攻击面——针对宿主集成的报告（如清单注入、路径遍历）应基于这些已知边界描述影响。

Server 形态的凭证处理：一个可直接引用的实现范例

策略要求报告中的日志"移除凭证、令牌、私有地址和个人路径"，而 Motrix Server 自身的凭证处理实现可以说明这一要求的由来。src/server/operator-token.ts 中的 provisionOperatorToken 为服务端子系统铸造操作者令牌：优先读取 MOTRIX_OPERATOR_TOKEN 环境变量；否则用 randomBytes(32) 生成随机令牌，以 wx 标志独占写入 <dataDir>/operator-token 并强制 0600 权限；源码注释明确 "The token itself is never logged"（令牌本身永不落日志），并发竞争通过 EEXIST 回读兜底。同类设计也出现在桥接侧的鉴权测试中（如 web-socket-bridge-server.authz.test.ts 验证 WebSocket 桥接服务器的授权行为）。

如何判断一个问题该报给谁：决策清单

综合以上证据，可以把原文档的条款压缩成一份可操作的判断清单：

1. 版本不在支持范围：先在最新发布的 Motrix Turbo v2 上复现；复现不了则按文档指引处理。
2. 问题在第三方插件内部：报给插件维护者。
3. 问题突破插件边界：能证明沙箱逃逸、权限门绕过、更新校验（非固定密钥签名被接受）、宿主集成（Native Messaging/Flatpak 边界）存在缺陷——报给 Motrix。
4. 问题在官方产物：桌面/Server 应用、native host 归档、容器镜像中第一方代码的行为——报给 Motrix。
5. 只是功能 Bug 或使用问题：走公开 Issue 表单或 Discussions，不要占用私密安全通道。

提交报告时，严格遵循"版本与运行时 + 组件与影响 + 最小 PoC + 脱敏证据 + 缓解建议"的五要素结构，并保持细节保密直至官方修复或公告发布——这两点分别是原文档中投入成本最高、也最容易被报告方忽略的要求。