Electron 信任与安全边界

本页整合 Electron 归档分稿中的机制、接口和接线。归档使用 Electron 44 系列作为其版本讨论背景；本文接口依据官方文档及 breaking changes 核查，实际采用时仍需固定项目版本。包版本、维护状态和原稿实测均是对应日期的历史信息。本次未启动 Electron、构建安装包、签名、公证或验证更新。代码块按各自标注区分片段与组合示例。

调研时间:2026-10-04。本章基于 Electron 官方文档/官方博客/release notes 原文,辅以 CISA、Unit 42、Checkmarx 等一手安全通告;所有版本号、默认值、时间线均与来源核对,无法核实的注明「待核实」。

5.1 原理与机制:为什么 Electron 安全模型是"三层纵深"复制锚点链接

官方 Security 文档开宗明义:"Electron is not a web browser"——你的 JS 代码可以触达文件系统与用户 shell,能力越大,风险的量级也越大。官方的威胁定义非常直白:只要从不可信来源(如远程服务器)接收代码并在本地执行,就存在安全问题;最极端的红线被原文加粗强调:

"Under no circumstances should you load and execute remote code with Node.js integration enabled."

Electron 的安全模型是三层纵深防御,核心是**把"展示内容的进程"与"拥有特权的进程"在 JS 上下文与 OS 进程两个维度上隔离开":

1. Main process(特权层):默认具有完整 Node.js 能力的应用入口；utility process 或自行启动的 Node 子进程也可能具有相应能力,所有文件、shell、原生 API 都应该在这里,并把每个 IPC 请求当作不可信输入。
2. Renderer process(不可信层):跑网页的 Chromium 渲染进程。现代 Electron 中它默认没有 Node.js、没有文件系统,只能"自由使用 CPU 和内存"(sandbox 文档原话),特权操作必须经 IPC 委托给 main。
3. Preload + contextBridge(桥接层):preload 在渲染进程中、但在隔离的 JS 上下文里运行,通过 contextBridge.exposeInMainWorld() 把最小化的白名单 API 暴露给页面。

三层各自的默认值是分阶段演进到位的(这张表用于核对跨版本默认行为):

contextIsolation 用的是与 Chromium Content Scripts 相同的隔离技术:preload 和 Electron 内部逻辑运行在独立 JS 上下文,页面脚本无法篡改 JSON.parse、Array.prototype.push 这类全局原语——即使在 nodeIntegration: false 下,要真正阻断 Node 原语污染,官方明确要求 context isolation 必须同时开启。另有一个容易致命的联动(官方 §4 的 info 框原文):设置 nodeIntegration: true 会连带关掉进程沙箱;显式 contextIsolation: false 也会禁用 sandbox,即使你全局启用了沙箱。

5.2 官方安全清单逐项解读(20 项,按主题分组)复制锚点链接

官方 Security 文档的 Checklist 共 20 条。2026 年视角下按主题分组解读(条目编号沿用官方):

A. 窗口与 webPreferences 组(2/3/4/6/8/9/10)

• #2 不为远程内容开 nodeIntegration(默认已关);#3 开 contextIsolation(默认已开);#4 开进程沙箱(默认已开)。——这三条在 2026 年的正确姿势是"别去动默认值",老项目升级时重点检查有没有历史遗留的 contextIsolation: false。
• #6 永远不要 webSecurity: false:官方原话它会 "disable the same-origin policy" 并顺带把 allowRunningInsecureContent 置 true。生产环境禁用。
• #8 不开 allowRunningInsecureContent(防 mixed content);#9 不开 experimentalFeatures;#10 不用 enableBlinkFeatures——"Under no circumstances should you enable features speculatively"(绝不投机式开启特性)。

B. 内容加载与策略组(1/5/7/18)

• #1 只加载 HTTPS/WSS/FTPS 等安全协议内容。
• #5 权限请求处理。关键事实:Electron 默认自动批准所有权限请求(notifications、geolocation、clipboard 等),不像 Chrome 会弹窗问用户。所有加载远程内容的 session 都应装 setPermissionRequestHandler:

session.defaultSession.setPermissionRequestHandler((webContents, permission, callback) => {
  try {
    const parsedUrl = new URL(webContents?.getURL() ?? '')
    const trusted = parsedUrl.origin === 'https://example.com'
    callback(trusted && permission === 'notifications')
  } catch { callback(false) }
})

(注意 session.defaultSession 仅在 app.whenReady() 之后可用。)

• #7 定义 CSP,并收紧到 script-src 'self' 级别。本地 file:// 页面无法用 HTTP 头下发时,用 <meta http-equiv="Content-Security-Policy">;打包应用更推荐通过 webRequest.onHeadersReceived 统一注入(官方示例以 default-src 'none' 为起点再逐项放开)。
• #18 避免 file:// 协议,改用自定义协议(protocol.handle)。官方原因:"Pages running on file:// have unilateral access to every file on your machine"——file:// 页面下任何 XSS 都可能变成任意本地文件读取。

C. 导航、新窗口与 WebView 组(11/12/13/14/15)

• #13 限制导航:will-navigate 中 event.preventDefault();必须用 new URL() 解析后比对 origin,不要用 startsWith 字符串匹配——官方举例 startsWith('https://example.com') 会被 https://example.com.attacker.com 绕过:

app.on('web-contents-created', (_e, contents) => {
  contents.on('will-navigate', (event, navigationUrl) => {
    const parsedUrl = new URL(navigationUrl)
    if (parsedUrl.origin !== 'https://example.com') event.preventDefault()
  })
})

• #14 限制新窗口:这是对"window.open 滥用"的标准答案——setWindowOpenHandler 默认 deny,白名单内的外部链接再交给系统浏览器:

app.on('web-contents-created', (_e, contents) => {
  contents.setWindowOpenHandler(({ url }) => {
    if (isSafeForExternalOpen(url)) {
      setImmediate(() => shell.openExternal(url)) // 只放行硬编码/严格校验过的 URL
    }
    return { action: 'deny' }
  })
})

• #15 shell.openExternal 绝不接收不可信输入:官方原话,误用 "can be leveraged to execute arbitrary commands"(在 macOS 上等价于 open,可能唤起危险 URI scheme 关联应用)。
• #11 <webview> 不加 allowpopups;#12 在 will-attach-webview 里剥离 preload、强制 nodeIntegration = false 并校验 params.src——因为 <webview> 标签活在 DOM 里,页面脚本可以在没有 Node 集成的情况下自行创建 webview,必须由 main 进程把关。

D. IPC 组(17/20)——官方近年补强的重点条目(具体加入清单的版本待核实)

• #17 校验所有 IPC 消息的 sender。所有 Web Frame(包括 iframe 和子窗口)理论上都能向 main 发 IPC。官方推荐用 event.senderFrame 并比对 origin 而非 URL(因为 about:blank、blob:、沙箱化文档的 URL 无法标识控制者):

ipcMain.handle('get-secrets', (e) => {
  if (!validateSender(e.senderFrame)) return null
  return getSecrets()
})
function validateSender(frame) {
  if (frame && frame.origin === 'https://electronjs.org') return true
  return false
}

• #20 不要把 Electron API 原样暴露给网页。contextBridge.exposeInMainWorld('electronAPI', { on: ipcRenderer.on }) 是官方点名的坏例子;回调也不能直接透传——IPC 事件对象的 sender 属性会把整个 ipcRenderer 实例泄漏给页面。正确做法是把每个 IPC 消息包装成独立方法:onUpdateCounter: (callback) => ipcRenderer.on('update-counter', (_event, value) => callback(value))。

E. 版本与发布组(16/19)

• #16 始终用最新版 Electron:官方明确"最新稳定版获得 main 全部修复;最老的支持线只回移安全修复"(支持策略为最近 3 个 major)。
• #19 fuses,见 5.5 节。

开发期提示:安全警告只在二进制名为 Electron 时打印到 console,可用 ELECTRON_ENABLE_SECURITY_WARNINGS / ELECTRON_DISABLE_SECURITY_WARNINGS 强制开关。

5.3 本地内容 vs 远程内容:威胁模型差异复制锚点链接

官方 Preface 直接给出了行业事实:"the most popular Electron apps (Atom, Slack, Visual Studio Code, etc) display primarily local content (or trusted, secure remote content without Node integration)"。两类内容的风险不在一个量级:

本地内容也需要依赖审查、输入处理与安全更新。嵌入远程内容还需限制其导航、权限及暴露能力；默认隔离、应用检查与运行时补丁共同形成边界。官方还有一句罕见的坦率建议:"If your goal is to display a website, a browser will be a more secure option."(§12 结尾)

5.4 进程沙箱与站点隔离(Site Isolation)复制锚点链接

OS 级沙箱:自 Electron 20 起渲染进程默认运行在 Chromium sandbox 中,进程"只能自由使用 CPU 和内存"。沙箱化渲染进程中的 preload 拿到的是 polyfill 过的 require,可用模块白名单仅:contextBridge、crashReporter、ipcRenderer、nativeImage、webFrame、webUtils(外加 events/timers/url 等基础能力),且 Buffer、process 等全局是 polyfill——这意味着多文件 preload 需要 bundler 打包,也意味着preload 能干的事天然受限,这是好事。可用 app.enableSandbox()(app ready 前)全局强制;--no-sandbox 仅限测试。官方同时坦承:"Electron cannot be as secure as Chromium without the resources that Chromium is able to dedicate",且修复不保证回移——留在受支持版本窗口内是硬要求。

Site Isolation(站点隔离)：归档调查曾记录一个预期教程地址返回 404，这只能说明该地址在当时不可用。Chromium 的站点隔离、Electron 的 renderer 进程、JavaScript 上下文与 session 存储承担不同职责，不能互相替代。可以为不同信任来源使用独立 WebContents 和 partition，分别约束导航、权限、preload 与 cookie 存储；partition 的直接保证是会话存储边界，不能仅凭它推定任意站点内容取得完整的进程隔离。具体进程分配及平台沙箱行为需要按目标 Electron 版本核对。Electron 进程模型、session API

5.5 electron/fuses 与发布期加固复制锚点链接

Fuses 是打包时烙进二进制、代码签名后 OS 防篡改的"魔数位"(哨兵串 dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX 之后,每字节 0/1/r)。用 @electron/fuses(或 Forge 的 @electron-forge/plugin-fuses)翻转:

配套时间线:ASAR Integrity 在 Electron 39(2025-10-28)转正(对 app.asar 做构建期哈希、启动校验、不匹配即终止),Electron 41(2026-03-10)又在 macOS 增加 ASAR digest 作为附加防篡改层。这是官方对"本地磁盘篡改/依赖注入"方向近两年最重要的加固,新项目应当默认启用。

5.6 依赖供应链:渲染进程 npm 与 preload 暴露面复制锚点链接

官方 General guidelines 把"你的应用安全 = Chromium + Node + Electron + 所有 NPM 依赖 + 你的代码"写成公式,并要求"Evaluate your dependencies"。2025 年的教训尤其深刻:

• Shai-Hulud 蠕虫(2025-09-14 起):npm 生态首个自复制蠕虫,窃取凭据并把受害者私有 GitHub 仓库设为公开;波及 500+ 包(约 600 个版本、近 200 个包名),CISA 于 2025-09-23 发布警报;11 月的 "Shai-Hulud 2.0" 进一步波及数万仓库(Unit 42 统计 25,000+ 恶意仓库、约 350 个账号)。
• VS Code(最大 Electron 应用)扩展市场:2025 年全年多起恶意扩展事件——ReversingLabs 披露伪装剪贴板/AI 助手的 clipboard-helper-vscode、code-ai-assistant 窃取 API key;Checkmarx 于 9 月系统性下架品牌仿冒扩展;12 月还有 "Bitcoin Black"/"Codo AI" 窃密木马。关键机制:扩展宿跑在完整 Node 特权里,装一个恶意扩展 ≈ 失守整个桌面端。

对 Electron 项目的落地含义:

1. 渲染进程依赖最小化:渲染层只是一个网页,任何打进渲染 bundle 的 npm 包都在攻击面内;UI 组件能用则用,涉及凭据/网络/原生能力的依赖要逐个审。
2. preload 是新的高价值目标:preload 拥有(受控的)Node 能力且能触达 IPC,供应链污染一个 preload 依赖即可横向打到 main。preload 应做到:依赖近零、不装任何运行时拉取代码的包、暴露面逐函数评审(#20)。
3. 工程手段:lockfile 提交、npm audit/OSV-Scanner 进 CI、发布凭据与构建隔离、配合 §5.5 的 asar integrity + fuses,让"装包即失守"的收益最小化。

5.7 历史安全事件与 CVE 模式(2025 前后)复制锚点链接

Electron 应用本体的历史漏洞主模式是 XSS → nodeIntegration 旁路 → RCE(官方文档自己点名过 "nodeIntegration bypasses" 这一类历史关键漏洞),而 2025 年的主战场明显转向 V8/Chromium 引擎层零日——渲染进程被攻破后,sandbox: true 成为最后一道 OS 防线:

可提炼的模式:① V8 type confusion 已成年度"保留节目"(2025 年至少 3 个在野),渲染进程沦陷是常态假设;② Electron 与 Chrome stable 之间永远存在数周 patch lag,不能把"用户浏览器已更新"当作你的应用已修复——你的用户不会通过浏览器自动更新获得 Electron 的 Chromium 补丁,必须自己发版;③ Electron 支持策略只承诺最近 3 个 major(当前为 42/43/44),且最老的线只回移安全修复,长尾旧版本应用是最大的存量风险;④ 每年 12 月 Electron 项目进入 quiet month,年底发版计划要预留。

5.8 安全设置的接线示例复制锚点链接

下面是本地内容加载与默认拒绝的组合示例，依赖本页讨论的 Electron API。它给出主进程配置，仍需项目提供 index.html、renderer.js、styles.css 和 preload.bundle.js；IPC 接收方另行强制来源、参数与权限。代码没有经过本轮 Electron 运行验证，不能作为所有应用安全性的证明。

const { app, BrowserWindow, session, shell, protocol, net } = require('electron')
const path = require('node:path')
const { pathToFileURL } = require('node:url')

protocol.registerSchemesAsPrivileged([
  { scheme: 'app', privileges: { standard: true, secure: true, supportFetchAPI: true } }
])
const localFiles = new Map([
  ['/index.html', 'index.html'],
  ['/renderer.js', 'renderer.js'],
  ['/styles.css', 'styles.css']
])
function isLocalPage(raw) {
  try {
    const url = new URL(raw)
    return url.protocol === 'app:' && url.hostname === 'myapp' &&
      url.port === '' && url.username === '' && url.password === ''
  } catch { return false }
}
function mayOpenExternal(raw) {
  try {
    const url = new URL(raw)
    return url.protocol === 'https:' && url.origin === 'https://docs.example.com' &&
      url.username === '' && url.password === ''
  } catch { return false }
}
app.on('web-contents-created', (_event, contents) => {
  contents.on('will-navigate', (event, raw) => {
    if (!isLocalPage(raw)) event.preventDefault()
  })
  contents.setWindowOpenHandler(({ url }) => {
    if (mayOpenExternal(url)) shell.openExternal(url).catch(console.error)
    return { action: 'deny' }
  })
  contents.on('will-attach-webview', (event) => event.preventDefault())
})
app.whenReady().then(() => {
  const ses = session.defaultSession
  ses.setPermissionRequestHandler((_contents, _permission, callback) => callback(false))
  ses.setPermissionCheckHandler(() => false)
  protocol.handle('app', (request) => {
    if (request.method !== 'GET' || !isLocalPage(request.url)) {
      return new Response(null, { status: 403 })
    }
    const relative = localFiles.get(new URL(request.url).pathname)
    if (!relative) return new Response(null, { status: 404 })
    const file = path.join(app.getAppPath(), relative)
    return net.fetch(pathToFileURL(file).href)
  })
  const win = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.bundle.js'),
      contextIsolation: true,
      sandbox: true,
      nodeIntegration: false,
      webSecurity: true,
      allowRunningInsecureContent: false,
      experimentalFeatures: false,
      webviewTag: false
    }
  })
  win.loadURL('app://myapp/index.html')
})

// forge.config.js —— fuses 基线(#19 + 5.5 节)
const { FuseV1Options, FuseVersion } = require('@electron/fuses')
const { FusesPlugin } = require('@electron-forge/plugin-fuses')
module.exports = { plugins: [new FusesPlugin({
  version: FuseVersion.V1,
  [FuseV1Options.RunAsNode]: false,
  [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
  [FuseV1Options.EnableNodeCliInspectArguments]: false,
  [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
  [FuseV1Options.OnlyLoadAppFromAsar]: true,
  [FuseV1Options.EnableCookieEncryption]: true,
  [FuseV1Options.GrantFileProtocolExtraPrivileges]: false
})]}

// preload.js —— 只暴露白名单方法,#17/#20
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('api', {
  loadPreferences: () => ipcRenderer.invoke('prefs:load'),
  onUpdateCounter: (cb) => {
    const listener = (_event, value) => cb(value)
    ipcRenderer.on('counter', listener)
    return () => ipcRenderer.removeListener('counter', listener)
  } // 不透传 event，并提供解除订阅
})
// main 侧每个 ipcMain.handle 都先过 validateSender(e.senderFrame)(见 5.2-D)

配套策略:停在支持窗口内(写作时为 42/43/44 线,最新 44.5.1 = Chromium 152.0.7977.130 / Node 24.21.0);按分发渠道、离线要求及恢复方案安排更新和最低版本策略;CI 中加入 Chromium 版本基线检查(参考 CVE-2025-10585 的教训)。

5.9 常见坑与反模式清单复制锚点链接

1. 为了用某个 npm 包把 nodeIntegration: true(或 sandbox: false)——官方文档 §3 明言这会连带关掉进程沙箱,等于一次关掉两层隔离。正解:能力放 main,IPC 暴露。
2. exposeInMainWorld('ipcRenderer', ipcRenderer) 或透传 event 对象 → 页面可任意发/收 IPC。
3. 用 startsWith 校验 URL/域名(官方点名可被 example.com.attacker.com 绕过)。
4. shell.openExternal(用户可控输入) → 命令执行面;只放行硬编码或严格 allowlist 的 https 链接。
5. file:// 加载应用 + 宽松 CSP → 本地 XSS 变任意文件读取。
6. 忘了 setPermissionRequestHandler → Electron 默认全部批准(与浏览器预期相反)。
7. will-navigate/setWindowOpenHandler 只挂在主窗口而非 web-contents-created 全局 → webview/子窗口绕过。
8. 无 fuses、无 asar integrity 发布 → ELECTRON_RUN_AS_NODE=1 即可把你的签名应用当 Node 用。
9. preload 里塞一堆运行时依赖 → 供应链直通特权层(Shai-Hulud 教训)。
10. 版本策略"能用就不动" → 官方只回移最近 3 个 major 的安全修复,旧线上的引擎零日无人兜底。

参考来源复制锚点链接

• Electron 官方 Security 文档(20 项清单原文): https://www.electronjs.org/docs/latest/tutorial/security
• Electron Context Isolation 文档: https://www.electronjs.org/docs/latest/tutorial/context-isolation
• Electron Process Sandboxing 文档: https://www.electronjs.org/docs/latest/tutorial/sandbox
• Electron Fuses 文档: https://www.electronjs.org/docs/latest/tutorial/fuses
• Electron IPC 教程(preload 暴露面): https://www.electronjs.org/docs/latest/tutorial/ipc
• Electron 支持策略(timelines): https://www.electronjs.org/docs/latest/tutorial/electron-timelines
• Electron v36.4.0 release notes(CVE-2025-5419 回移,#47353): https://releases.electronjs.org/release/v36.4.0
• Electron Releases(当前稳定版 44.5.1/43.7.7/42.11.10,45 alpha): https://releases.electronjs.org
• Electron 38.0.0 发布(Chromium 140.0.7339.41、支持矩阵): https://www.electronjs.org/blog/electron-38-0
• Electron 44.0.0 发布(Chromium 152、Node 24、macOS 13+): https://www.electronjs.org/blog/electron-44-0
• Electron 官方博客索引(E39/E41 ASAR Integrity、2025-2026 版本时间线): https://www.electronjs.org/blog
• CISA 警报:Widespread Supply Chain Compromise Impacting npm Ecosystem(2025-09-23): https://www.cisa.gov/news-events/alerts/2025/09/23/widespread-supply-chain-compromise-impacting-npm-ecosystem
• Unit 42: "Shai-Hulud" Worm Compromises npm Ecosystem: https://unit42.paloaltonetworks.com/npm-supply-chain-attack
• Checkmarx: NPM Hit By Shai-Hulud: https://checkmarx.com/zero-post/npm-hit-by-shai-hulud-the-self-replicating-supply-chain-attack
• The Hacker News:Chrome V8 零日 CVE-2025-13223(2025-11): https://thehackernews.com/2025/11/google-issues-security-fix-for-actively.html
• MeetCyber(dev.to):KEV V8 CVE-2025-10585 对 Electron 应用的影响(二手,patch lag 证据): https://medium.com/meetcyber/kev-v8-cve-2025-10585-hits-electron-apps-04544099f585
• SOC Prime:CVE-2025-5419 分析(Chrome 137.0.7151.68 修复线): https://socprime.com/blog/cve-2025-5419-zero-day-vulnerability
• IGEL KB(Chrome 140 线漏洞清单,含 CVE-2025-10201 站点隔离绕过): https://kb.igel.com/en/security-safety/current/isn-2025-38-critical-chromium-vulnerabilities-cve-
• ReversingLabs:恶意 VS Code 扩展窃密: https://www.reversinglabs.com/blog/malicious-helpers-vs-code-extensions-observed-stealing-sensitive-information
• Checkmarx:VS Code 恶意扩展下架流程: https://checkmarx.com/zero-post/how-we-take-down-malicious-visual-studio-code-extensions
• Chromium 官方 Process Model & Site Isolation 设计文档: https://chromium.googlesource.com/chromium/src/+/main/docs/process_model_and_site_isolation.md