100pah commented on code in PR #148: URL: https://github.com/apache/echarts-handbook/pull/148#discussion_r2446817801
########## contents/zh/best-practices/security.md: ########## @@ -0,0 +1,100 @@ +# 安全性 + +## 概述 + +ECharts 旨在提供丰富而灵活的可视化能力。虽然其绝大多数 API 不需要额外的安全考虑，但有几个例外。例如，`tooltip.formatter` 允许输入 HTML 字符串，从而完全控制组件的内容与布局；`title.link` 直接使用输入的 URL 字符串而不进行自动的净化处理（sanitization）。这种灵活性虽然强大，但当输入来自“不受信任”的来源时，可能带来安全风险。本文档列出了这些 API，并提供了如何安全使用这些特性的建议。 + +任何潜在安全问题，可通过邮件报告至 [[email protected]](mailto:[email protected])。 + + +## 安全边界与检查清单 [[[#security_boundaries_and_checklist]]] + +ECharts 专注于可视化逻辑，一般假定输入内容是可信任的，因此不会自动对输入进行净化处理。其实 ECharts 自身也不知如何合适地做净化处理，因为不存在适用于所有使用场景的通用处理规则。然而，ECharts 应该明确哪些 API（尤其是 ECharts options）在哪些场景下须在输入前进行安全相关的处理或考量。由于 ECharts options 数量庞大，对所有输入在任何场景下都进行安全处理不现实也无必要。 + +ECharts 通过 Canvas 或 SVG 渲染，只有几个特殊组件例外，允许 HTML 渲染（例如，[toolip](${optionPath}tooltip) 和 [dataView](${optionPath}toolbox.feature.dataView)）。ECharts API 的输入可被分为“JS 函数”或者“非 JS 函数”。“JS 函数输入”本意就须允许执行。而大多数“非 JS 函数输入”（例如仅用于渲染的纯文本）不会被执行，因此通常无需防范恶意代码注入。然而，某些 API 允许在页面中嵌入不安全内容（如 HTML 或 URL 文本）。这些 API 能带来丰富的定制能力，但当输入来自“不受信任”的来源时，容易遭受 XSS （跨站脚本攻击）或相关攻击。 + +**一般而言，如果输入的内容都是可被信任的，就不会出现这些注入漏洞。** +“不受信任”（untrusted）的内容指，内容来自于无法完全控制的来源，或者内容可能被用户或外部系统修改或注入。开发者应该总是假定直接在 HTML、CSS、JS 中使用这些内容会不安全。例如，用户生成的数据或来自客户端的输入都应被认为是“不受信任”的。但在许多情况下，处理用户生成的内容不可避免。例如，从数据库获取用户生成的数据，并组装成 HTML 输入 `tooltip.formatter` 来渲染，就须要进行额外处理，首先是保正渲染正确（通常通过 HTML 转义（HTML escaping）），然后是防止 XSS 攻击（如果无法被转义的部分也是“不受信任”的，需要净化处理（sanitization））。 + +在部署图表之前，请根据以下**检查清单**确认使用是否安全： + +| APIs | 潜在风险与建议 | +| ------ | ------------------ | +| **option [tooltip.formatter](${optionPath}tooltip.formatter)**<br>· `formatter` 允许 HTML 文本或 DOM 元素传入，并后续直接渲染到 tooltip 内部，于是需要考虑 XSS 风险。<br>（例外）：如果 `formatter` 被直接设置成一个字符串，则认为是一个内部实现的简单模版，后续能内部填入数据。[tooltip.renderMode: 'richText'](${optionPath}tooltip.renderMode) 是另一种内部实现的模版，用于定制样式。他们都不涉及 HTML，从而安全。<br><br>**option [toolbox.feature.dataView.optionToContent](${optionPath}toolbox.feature.dataView.optionToContent)**<br>**option [toolbox.feature.dataView.title](${optionPath}toolbox.feature.dataView.title)**<br>**option [toolbox.feature.dataView.lang](${optionPath}toolbox.feature.dataView.lang)**<br>· `tooltip.dataView` 面板完全以 HTML 渲染，这些 API 可自定义 HTML 文本中的部分内容，于是需要考虑 XSS 风险。 | 需要考虑 XSS 风险。一般情况 下，仅需 HTML 转义即可。但如果一些不能转义的部分来自“不受信任”的来源，则须更多处理（如净化处理（sanitization）或沙盒隔离）。<br><br>详细描述见 [“传入 HTML 时的安全考虑”](best-practices/security#passing_raw_html_safely)。 | +| **option [tooltip.extraCssText](${optionPath}tooltip.extraCssText)**<br>· `extraCssText` 接受一个原始 CSS style 字符串，并接下来直接拼接进 `tooltipEl.style.cssText`。<br>（例外）：[tooltip.renderMode: 'richText'](${optionPath}tooltip.renderMode) 时此 `extraCssText` 无效。 | 若输入来自可信来源，则一般无安全问题，否则需要仔细评估风险。<br><br>详细描述见 [“传入内联 CSS 时的安全考虑”](best-practices/security#passing_inline_css_safely)。 | +| **option [title.link](${optionPath}title.link)**<br>**option [title.sublink](${optionPath}title.sublink)**<br>**option [series-treemap.data.link](${optionPath}series-treemap.data.link)**<br>**option [series-sunburst.data.link](${optionPath}series-sunburst.data.link)**<br>· 这些 option 直接接受原始 URL 字符串。 | 若若输入来自可信来源，则一般无安全问题，否则须要考虑 XSS 风险。<br><br>详细描述见 ["传入 URL 时的安全考虑"](best-practices/security#passing_raw_urls_safely)。 | +| **option [toolbox.feature.saveAsImage.name](${optionPath}toolbox.feature.saveAsImage.name)**<br>**option [toolbox.feature.saveAsImage.type](${optionPath}toolbox.feature.saveAsImage.type)**<br>**option [title[0].text](${optionPath}title.text)**<br>· `saveAsImage` 功能的下载文件名由 `{name}.{type}` 拼装而成，并未做额外校验或净化（sanitization）处理。如果 `name` 没有指定，则使用 `title[0].text` 替代，尽管这种用法并不推荐。 | 详细描述见 [“传入下载文件名时的安全考虑”](best-practices/security#passing_download_filename_safely)。 | +| 所有“JS 函数”输入（回调） | 通常无安全问题，除非存在特殊使用场景（例如需要执行不可信来源的函数）。<br><br>详细描述见 [“传入 JS 函数时的安全考虑”](best-practices/security#passing_js_function_safely)。 | + + +## 传入 HTML 时的安全考虑 [[[#passing_raw_html_safely]]] + +在 [“安全边界与检查清单”](best-practices/security#security_boundaries_and_checklist) 一节中已列出会接受原始 HTML 的 API。“不受信任”的 HTML 可能导致 XSS 等攻击，因此在传入 ECharts 前应进行处理。常见的处理方式包括 **HTML 转义（HTML Escaping）**、**净化（Sanitization）**、**沙盒**。大多数情况下，仅进行 HTML 转义即可，除非那些不能被转义的部分来自于“不受信任”的来源。 + +### HTML 转义（HTML Escaping） [[[#passing_raw_html_safely_html_escaping]]] +数据组装成 HTML 字符串前总需要进行 HTML 转义。这不仅是安全需要，也是正确显示的前提。 + +最简单和常见的 HTML 转义是这些字符串转换： +``` +'&' => '&' +'<' => '<' +'>' => '>' +'"' => '"' +"'" => ''' Review Comment: Oh, yes. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
