写点什么

鸿蒙应用安全编码专题系列之 Web 组件 JavaScriptProxy 安全

HarmonyOS
  • 2026-05-27
    北京

  • 本文字数：5806 字

    阅读完需：约 19 分钟

一、背景介绍

JavaScript Bridge（简称 JSBridge）是 Hybrid App 中 WebView（H5 页面）与 native 层（Android/iOS/鸿蒙）进行通信的核心通道，负责实现前端与 native 代码的交互，是移动应用中典型的高风险攻击面。在鸿蒙系统中，Web 组件提供了 JavaScriptProxy 机制，为前端 H5 与 ArkTS native 层的通信提供支持，应用通常会通过注册 JavaScriptProxy 暴露 native 接口供前端调用，若未采取规范的安全防护措施，极易被攻击者利用，引发各类安全风险。

二、JSBridge 核心安全风险

鸿蒙 Web 组件的 JSBridge 通信机制，若实现不当，会面临以下 4 类核心安全风险，均可能导致敏感数据泄露、权限被滥用等严重后果：

2.1 跨站脚本攻击（XSS）与接口越权调用

攻击者通过注入恶意 JavaScript 代码到 H5 页面，利用 JSBridge 调用鸿蒙 native 接口。若 native 接口未做权限校验、参数过滤等安全控制，攻击者可通过该方式执行越权操作，如调用系统敏感接口、篡改应用数据等。

2.2 敏感数据泄露

若 JSBridge 暴露了获取用户敏感数据或全局认证凭据的接口（如 AccessToken、SessionId、用户密码等），一旦被攻击者利用，可直接冒充用户身份，访问云端服务、读取本地敏感数据（如数据库、缓存文件），造成用户信息泄露。

2.3 URL 跳转与钓鱼攻击

若应用通过 JSBridge 为 H5 提供 URL 加载接口（如鸿蒙 WebviewController 的 loadUrl 方法），且未对跳转 URL 进行白名单校验，攻击者可构造恶意 H5 页面，调用该接口将用户重定向至伪造的钓鱼网站（如仿银行、仿社交平台登录页），窃取用户输入的账号、密码等核心凭证。

2.4 UXSS 漏洞风险

若 JSBridge 中提供 URL 跳转（loadUrl）、JavaScript 脚本执行（runJavaScript、runJavaScriptExt）等功能，且未做严格的安全校验，可能引发通用跨站脚本（UXSS）攻击，攻击者可通过构造特殊 URL 或脚本，绕过同源策略，执行恶意代码。

核心防护前提

上述所有风险的防护核心的是 URL 白名单管控，目前主流有两种实现方案：

  1. 全局 URL 白名单：对 Web 组件加载的所有 URL 进行白名单校验，仅允许白名单内的 URL 加载和调用 JSBridge（前期已有文章针对此方案进行安全风险分析和安全实现方案推荐，可直接参考：鸿蒙应用安全编码专题系列之Web组件URL加载安全 | 华为开发者联盟，本文不重点展开）；

  2. 针对 JSBridge 单独校验白名单：不限制 Web 组件加载的 URL，仅在前端 H5 调用 JSBridge 时，对当前页面 URL 进行白名单校验，仅允许白名单内的 URL 调用 JSBridge（本文重点讨论该方案的不安全实现及防御措施）。

三、JSBridge 白名单校验的不安全实现

针对 JSBridge 单独校验白名单的核心是“获取当前调用 JSBridge 的 H5 页面 URL，再与白名单比对”，若 URL 获取方式不当，会导致校验失效，被攻击者通过时序攻击、条件竞争等方式绕过。以下是两种比较常见的不安全实现及问题分析。

3.1 方式一：在 onLoadIntercept 等回调中获取 URL

错误实现逻辑：在 Web 组件的 onLoadIntercept 等回调接口中，获取当前页面 URL 并缓存，后续 JSBridge 接口调用时，直接使用缓存的 URL 进行白名单校验。

核心问题：缓存的 URL 与实际调用 JSBridge 时的页面 URL 可能不一致，攻击者可通过延时攻击绕过校验。

错误示例代码

//1、定义JavaScriptProxy对象class TestObj1 {  private _url: string = '';  public setUrl(value: string) {    this._url = value;  }  public getUrl(): string {    return this._url;  }  constructor() {  }  getToken(): string {    console.log('get token : ' + this._url);    //2、域名白名单校验    if (isUrlInWhitelist(this._url)) {      return 'real token';    }    return 'fake token';  }}//域名白名单校验方法function isUrlInWhitelist(url: string) {  let whitelist = ['baidu.com', 'b.example.com'];  try {    const urlObj = new uri.URI(url);    if (whitelist.includes(urlObj.host) && 'https' === urlObj.scheme) {      return true;    }  } catch (e) {    return false;  }  return false;}//3、onControllerAttached回调中注册getToken方法this.controller.registerJavaScriptProxy(this.testObjtest1, "objName1", ["getToken"]);//4、onLoadIntercept回调中设置url，用于校验.onLoadIntercept((event) => {  if (event) {    console.info('onLoadIntercept url:' + event.data.getRequestUrl())    this.testObjtest1.setUrl(event.data.getRequestUrl());  }  return false;})
复制代码

攻击示例（PoC）

<button onclick="gettoken">click me</button><script type="text/javascript"> function gettoken(){   // 频繁跳转至白名单URL，让缓存的URL为白名单地址   setInterval(gotowhite, 5);     // 延时执行JSBridge调用，此时页面已被替换为恶意地址，但缓存URL仍为白名单   setTimeout(getUserInfo, 500);  function gotowhite() {    top.location.href = "https://baidu.com"; // 白名单内URL  }  function getUserInfo() {    if (window.objName1) {      var token = window.objName1.getToken(); // 调用JSBridge获取敏感令牌      console.log('get token : ' + token);      document.write('get token result : ' + token);    } else {      console.error("no window objName1");      document.write('get token fail : no window objName1');    }  }}</script>
复制代码

攻击结果

攻击者的恶意页面（如 xxx.github.io）通过延时跳转，使 JSBridge 校验时使用的缓存 URL 为白名单地址（https://baidu.com），但实际调用 JSBridge 的页面为恶意地址，最终成功绕过校验，获取到真实敏感令牌（如下图）。

cke_168.png

​

3.2 方式二：通过 WebviewController.getUrl()获取 URL

错误示例代码

错误实现逻辑：在 JSBridge 接口（如 getToken）中，通过鸿蒙 WebviewController 的 getUrl()方法获取当前页面 URL，再进行白名单校验。

// 1、定义JavaScriptProxy对象class TestObj2 {  webviewcontroller: webview.WebviewController;  constructor(webviewcontroller: webview.WebviewController) {    this.webviewcontroller = webviewcontroller;  }  getToken(): string {    // 2、通过getUrl()获取URL（核心错误点）    let url = this.webviewcontroller.getUrl();    console.log('get token : ' + url);    // 3、白名单校验    if (isUrlInWhitelist(url)) {      return 'real token'; // 校验通过，返回真实令牌    }    return 'fake token'; // 校验失败，返回虚假令牌  }}// 白名单校验函数function isUrlInWhitelist(url: string) {  let whitelist = ['baidu.com', 'b.example.com'];  try {    const urlObj = new uri.URI(url);    // 校验协议为https且域名在白名单内    if (whitelist.includes(urlObj.host) && 'https' === urlObj.scheme) {      return true;    }  } catch (e) {    return false;  }  return false;}// 4、初始化WebviewController和JavaScriptProxycontroller: webview.WebviewController = new webview.WebviewController();testObjtest2: TestObj2 = new TestObj2(this.controller);// 5、注册JavaScriptProxythis.controller.registerJavaScriptProxy(this.testObjtest2, "objName2", ["getToken"]);
复制代码

核心问题

getUrl()方法本身并非线程安全，读取的是 URL 的瞬时状态，无法保证与“JSBridge 调用时的真实 URL”一致。攻击者可通过文件替换、多进程并发读写等方式制造时序差，使 getUrl()获取到白名单 URL，而实际调用 JSBridge 的是恶意 URL，从而绕过校验。

四、安全实现方案

针对上述不安全实现，鸿蒙系统提供了两种可靠的防御方案，优先推荐使用系统自带的权限配置机制，无需自行实现复杂的校验逻辑，安全性更高、可维护性更强。

4.1 方案一：使用 getLastJavascriptProxyCallingFrameUrl()获取真实 URL

鸿蒙 WebviewController 提供了 getLastJavascriptProxyCallingFrameUrl()接口（详情参考：Class (WebviewController)-@ohos.web.webview (Webview)-ArkTS API-ArkWeb（方舟Web）-应用框架 - 华为HarmonyOS开发者），该接口可获取“最后一次调用注入 JavaScript 对象的 frame 的真实 URL”，不受时序攻击、条件竞争影响，是替代 getUrl()的安全方案。

getLastJavascriptProxyCallingFrameUrl

getLastJavascriptProxyCallingFrameUrl(): string

通过registerJavaScriptProxy或者javaScriptProxy注入 JavaScript 对象到 window 对象中。该接口可以获取最后一次调用注入的对象的 frame 的 url。

系统能力： SystemCapability.Web.Webview.Core

返回值：

正确实现代码

正确示例代码如下，只需将 getUrl 替换成 getLastJavascriptProxyCallingFrameUrl 即可。

// 1、定义JavaScriptProxy对象class TestObj2 {  webviewcontroller: webview.WebviewController;  constructor(webviewcontroller: webview.WebviewController) {    this.webviewcontroller = webviewcontroller;  }  getToken(): string {    // 2、使用安全接口获取真实调用URL（核心修改点）    let url = this.webviewcontroller.getLastJavascriptProxyCallingFrameUrl();    console.log('get token : ' + url);    // 3、白名单校验（逻辑不变）    if (isUrlInWhitelist(url)) {      return 'real token';    }    return 'fake token';  }}// 白名单校验函数（与错误示例一致）function isUrlInWhitelist(url: string) {  let whitelist = ['baidu.com', 'b.example.com'];  try {    const urlObj = new uri.URI(url);    if (whitelist.includes(urlObj.host) && 'https' === urlObj.scheme) {      return true;    }  } catch (e) {    return false;  }  return false;}// 4、初始化与注册（逻辑不变）controller: webview.WebviewController = new webview.WebviewController();testObjtest2: TestObj2 = new TestObj2(this.controller);this.controller.registerJavaScriptProxy(this.testObjtest2, "objName2", ["getToken"]);
复制代码

4.2 方案二：注册 JavaScriptProxy 时配置 permission（优先推荐）

鸿蒙 WebviewController 的 registerJavaScriptProxy 接口支持通过 permission 参数配置 JSBridge 的 URL 白名单，由系统自动完成校验，无需自行实现 URL 获取和比对逻辑，从源头避免校验漏洞，是比较安全、简洁的方案。

具体 API 如下，参考：Class (WebviewController)-@ohos.web.webview (Webview)-ArkTS API-ArkWeb（方舟Web）-应用框架 - 华为HarmonyOS开发者 和 属性-Web-ArkTS 组件-ArkWeb（方舟Web）-应用框架 - 华为HarmonyOS开发者

registerJavaScriptProxy

registerJavaScriptProxy(jsObject: object, name: string, methodList: Array, asyncMethodList?: Array, permission?: string): void

registerJavaScriptProxy 提供了应用与 Web 组件加载的网页之间强大的交互能力。注入 JavaScript 对象到 window 对象中，并在 window 对象中调用该对象的方法。

其中 permission 就是白名单，通过该字符串配置 JSBridge 的权限管控，可以定义 object 和 method 级别的 URL 白名单。

1. scheme（协议）和 host（域名）参数不可为空，且 host 不支持通配符，只能填写完整的 host。

2. 可以仅配置 object 级别的白名单，该白名单对所有 JSBridge 方法生效。

3. 若 JSBridge 方法 A 设置了 method 级别的白名单，那么方法 A 最终的白名单是 object 级别白名单与 method 级别白名单的交集。

javaScriptProxy

javaScriptProxy(javaScriptProxy: JavaScriptProxy)

将 javaScriptProxy 中的 ArkTS 对象注册到 Web 组件中，该对象将使用 JavaScriptProxy 中指定的名称注册到网页的所有框架中，包括所有 iframe，这使得 JavaScript 可以调用 javaScriptProxy 中 ArkTS 对象的方法。当属性没有显式调用时，默认不将 javaScriptProxy 中的 ArkTS 对象注册到 Web 组件中。

正确实现代码

正确示例代码如下，可以看到，相比于上面的方案，实现简单且安全

// 1、定义JavaScriptProxy对象（无需自行实现URL校验）class TestObj3 {  constructor() {  }  // 敏感接口：获取用户令牌  getToken(): string {    return 'real token';  }}// 2、配置白名单（permission参数）// 仅允许https协议、baidu.com域名的页面调用该JSBridgelet permission: string = '{"javascriptProxyPermission":{"urlPermissionList":[{"scheme":"https","host":"baidu.com"}]}}'// 3、初始化WebviewController和JavaScriptProxycontroller: webview.WebviewController = new webview.WebviewController();testObjtest3: TestObj3 = new TestObj3();// 4、注册时配置permission，系统自动校验URLthis.controller.registerJavaScriptProxy(this.testObjtest3, "objName3", ["getToken"], [], permission);
复制代码

防御效果

当攻击者尝试通过恶意 URL 调用该 JSBridge 时，系统会自动校验当前页面 URL 是否在 permission 配置的白名单内，若不在则抛出“Jsb Permission Denied”错误，拒绝执行敏感操作，从源头阻断攻击（如下图）。

​

五、安全建议

结合上述分析，针对鸿蒙 Web 组件 JSBridge 的安全防护，提出以下 4 点核心建议，覆盖开发、校验、配置全流程：

5.1 优先使用系统自带权限配置

注册 JavaScriptProxy 时，优先通过 permission 参数配置 URL 白名单，禁止自行实现 URL 校验逻辑，避免因时序攻击、接口使用不当导致的漏洞；permission 中 scheme 仅配置 https 协议，敏感方法建议额外增加 path 限制，进一步缩小访问范围。

5.2 避免使用不安全的 URL 获取方式

若确需自行实现白名单校验，必须使用 getLastJavascriptProxyCallingFrameUrl()获取真实 URL，严禁使用 getUrl()、getOriginalUrl()等接口，避免时序攻击和条件竞争漏洞。

5.3 禁用 JSBridge 中的高风险功能

避免在 JavaScriptProxy 中暴露页面加载（loadUrl）、脚本执行（runJavaScript、runJavaScriptExt）等功能，防止引发 UXSS 攻击；若确需提供此类功能，需对 URL、脚本内容进行严格的白名单校验和过滤。

5.4 加强接口权限管控与参数校验

对 JSBridge 暴露的敏感接口（如获取 token/令牌/sessionId 等、读取用户数据），除 URL 白名单校验外，还需增加用户身份校验、参数合法性校验；避免暴露不必要的敏感接口，遵循“最小权限原则”。

其他鸿蒙应用安全编码专题文章请参考：

https://developer.huawei.com/consumer/cn/blog//topic/03207416677214221

Copyright © 2026, Geekbang Technology Ltd. All rights reserved. 极客邦控股（北京）有限公司 | 京 ICP 备 16027448 号 - 5京公网安备京公网安备 11010502039052号 | 产品资质