You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

5.6 KiB

安全设计

保护的边界

模板将 renderer 视为可能被脚本注入的浏览器上下文。renderer 不应拥有任意文件访问、命令执行、凭据读取或远程网页访问本地桥接的权限。模板保护 IPC 来源、窗口角色和用户选择的文件授权边界。

它不对抗已经控制用户操作系统账户的攻击者;同一账户通常可以读取应用数据或修改安装目录。授权文件的本地竞态与系统密钥链安全仍取决于 OS。应用供应链、签名证书和更新发布服务器属于发布者需要管理的边界。

默认值

  • 所有窗口 sandbox/contextIsolation/webSecurity 开启,nodeIntegration/webviewTag 关闭。
  • 只加载应用资源,禁止任意导航、新窗口和 webview 附加。
  • 默认拒绝浏览器权限与下载。
  • 生产资源使用安全自定义协议;路径检查包括真实路径,禁止目录逃逸和符号链接逃逸。
  • 生产 CSP 禁止远程脚本、远程连接、嵌套 frame、object、表单提交。样式允许 inline 以支持 Vue 样式绑定。
  • 开发 CSP 只额外允许本机 Vite WebSocket;IPC 仍校验确切端口和入口路径。
  • 打包 fuses 关闭 RunAsNode、Node options 环境变量、CLI inspector,并限制从 ASAR 加载应用。

IPC 校验顺序

注册窗口 → 主 frame → 确切协议/host/path → electron-trpc 消息结构与大小 → 频率与并发限额 → 已声明 tRPC path 与操作类型 → 窗口角色 → 输入 schema → 业务服务 → 输出 schema。订阅还受每窗口 32 个的限额约束;发送响应、退订时也验证来源。

不向 renderer 暴露原生 IPC 对象。preload 仅提供固定 electron-trpc 通道的消息发送与接收,输入消息经过结构校验,没有任意 channel 参数。异常返回 tRPC 错误代码和用户可读消息,移除 stack/path;未知异常记录方法名、owner、incidentId、白名单中的异常类型与错误码、受限原因链及数字位置,不记录任意 message、完整 stack、文件路径、输入或凭据。返回给 renderer 的内部错误包含同一 incidentId,便于在主进程日志中关联。启动失败另记录固定的启动阶段。业务调用上下文携带窗口,但不会把 Electron 对象序列化到 renderer。tRPC 输入校验和输出校验不能替代来源与角色授权。

现有示例 procedure 显式允许 main,并按用途允许 settings/about。新增接口必须明确声明角色,没有自动扩大权限的默认方法集合。角色元数据是唯一方法授权声明,公共 middleware 默认拒绝;窗口角色不会随 hash 路由变化而提升。query/mutation 校验输出,RpcEvent 校验每次事件载荷。

文件能力

必须通过原生选择框授权,renderer 得到随机 UUID,主进程保留真实路径。句柄绑定 owner 与文件/目录类型,刷新和关闭窗口即撤销。读写限制 256 KB,目录最多列出 2000 项,每窗口最多 16 个句柄、4 个监听器。目录监听观察当前目录,不递归。

文件授权代表该窗口有读写选中文件的权限。示例 UI 保存前会确认;如果业务需要主进程强制每次确认,请在写路由中加入原生确认,不能只依赖 renderer UI。

文件选择框返回期间如果原文档刷新或导航,结果会被作废,防止旧文档授权落到新文档上。

凭据

只使用 OS 加密;Linux 没有有效密钥链或使用 basic_text 时返回不可用。renderer 可以设置/删除和查询存在状态,不能获取明文。SecretService.read 只供主进程业务服务使用。输入保存在 renderer 的时间应尽可能短,禁止写日志或广播。

发布与远程内容

默认没有更新 feed。启用时只使用 HTTPS,禁止降级与预发布,自动检查但要求用户明确下载和安装;禁用 NSIS Web Installer,安装前完成应用清理。启用 feed 的构建要求平台签名,发布检查与实际签名验证仍需目标环境,详见 release.md。

统一诊断不上传原始日志、错误消息、完整栈或任意 renderer 参数。接收地址只来自构建配置;安装版本、有地址及用户授权三者同时成立才发送。撤销授权会中止请求并清除待发队列;已送达的数据需由后端删除策略处理。Crashpad 只收集本地原生转储,不进行远程上传。协议与保留范围见 diagnostics.md。

如果新增远程网页,使用独立 session 和无应用 preload 的容器,不注册到 RpcGateway。不要复用可信窗口加载远程 URL。外部系统浏览器链接必须匹配配置白名单。

参考:Electron 安全指南、Context Isolation、Sandbox。

依赖审计记录(2026-10-11)

pnpm audit --prod 已通过。workspace 的 Vue 与 updater peer 下限与根依赖保持一致,避免旧 peer 版本留在 lockfile 中。

完整 pnpm audit 仍报告构建工具链中 electron-builder → @electron/get → global-agent → roarr → sprintf-js@1.1.3 的中危格式化精度拒绝服务告警。官方 registry 尚无修复版本;官方公告 也标注 Patched versions: None。它属于构建工具依赖,不在应用生产依赖树中;模板没有向 renderer 暴露此格式化器。不能因此宣称全依赖树无告警。升级构建工具或该依赖后应重新审计;CI 对生产依赖执行审计,不忽略任何生产告警。