This is an automated email from the ASF dual-hosted git repository. sushuang pushed a commit to branch security-related in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit 68bde9bf6c1387a9c98ddc20fa122add4ea5e54b Author: 100pah <[email protected]> AuthorDate: Sun Oct 19 17:42:33 2025 +0800 security: add security warnings for APIs (options) in doc. --- README.md | 9 +++++++-- en/option/component/title.md | 8 ++++++++ en/option/component/toolbox.md | 27 +++++++++++++++++++++++++-- en/option/partial/security-warning.md | 12 ++++++++++-- en/option/partial/tooltip-common.md | 17 +++++++++++++++-- en/option/series/sunburst.md | 2 ++ en/option/series/treemap.md | 2 ++ src/style/mixin.scss | 9 +++++++++ zh/option/component/title.md | 8 ++++++++ zh/option/component/toolbox.md | 26 ++++++++++++++++++++++++-- zh/option/partial/security-warning.md | 11 +++++++++-- zh/option/partial/tooltip-common.md | 16 ++++++++++++++-- zh/option/series/sunburst.md | 2 ++ zh/option/series/treemap.md | 2 ++ 14 files changed, 137 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2337ae6b..675f75c4 100644 --- a/README.md +++ b/README.md @@ -71,11 +71,16 @@ For example, Security waning is required for unsafe APIs/options. For example, ``` -{{ use: security-warning }} +{{ use: partial-security-warning }} Or -{{ use: security-warning( +{{ use: partial-security-warning( desc: 'Raw HTML is allowed in this option.' )}} +Or +{{ use: partial-security-warning( + desc: 'Raw HTML is allowed in this option.', + securityRiskExclamation: '**Security risks** must be considered when xxx.' +)}} ``` See ["Security"](https://echarts.apache.org/handbook/en/best-practices/security) for more details. diff --git a/en/option/component/title.md b/en/option/component/title.md index f448dacb..ff23218e 100644 --- a/en/option/component/title.md +++ b/en/option/component/title.md @@ -26,10 +26,16 @@ Set this to `false` to prevent the title from showing The main title text, supporting for `\n` for newlines. +{{ use: partial-security-warning( + securityRiskExclamation: 'When enabling [toolbox.feature.saveAsImage](~toolbox.feature.saveAsImage), and [toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name) is not provided, it has historically been using `title[0].text` instead. This usage is not recommended -- [toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name) should always be specified explicitly; otherwise, **correctness** and **security risks** for a filename have to be considered in this `ti [...] +)}} + ## link(string) = '' The hyper link of main title text. +{{ use: partial-security-url-common-warning }} + ## target(string) = 'blank' Open the hyper link of main title in specified tab. @@ -63,6 +69,8 @@ Subtitle text, supporting for `\n` for newlines. The hyper link of subtitle text. +{{ use: partial-security-url-common-warning }} + ## subtarget(string) = 'blank' Open the hyper link of subtitle in specified tab, options: diff --git a/en/option/component/toolbox.md b/en/option/component/toolbox.md index caf1b23e..6cd510f7 100644 --- a/en/option/component/toolbox.md +++ b/en/option/component/toolbox.md @@ -63,6 +63,11 @@ Padding of text area. Whether to show the tool. #### title(string) = '${title}' +{{ if: ${warnToolboxDataViewSecurity} }} +{{ use: partial-security-warning( + desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The `title` is embedded in the HTML without HTML-escaping, so it should be properly escaped before being passed in.' +)}} +{{ /if }} #### icon(string) @@ -169,11 +174,20 @@ File suffix of the image saved. + If the `renderer` is set to be `'canvas'` when chart [initialized](api.html#echarts.init) (default), then `'png'` (default) and `'jpg'` are supported. + If the `renderer` is set to be `'svg'` when when chart [initialized](api.html#echarts.init), then only `'svg'` is supported for `type` (`'svg'` type is supported since `v4.8.0`). +{{ use: partial-security-warning( + securityRiskExclamation: 'This value will be used as the file extension. However, it has not historically been validated internally. So do not input an invalid value; otherwise, **security risks** have to be considered.' +)}} + #### name(string) <ExampleUIControlText /> -Name to save the image, whose default value is [title.text](~title.text). +Name (file stem) to save the image. If it is not provided, [title[0].text](~title.text) (if any) has historically been used. The full download filename is `{name}.{type}` + +{{ use: partial-security-warning( + securityRiskExclamation: 'It is recommended to always specify this `name` explicitly, and do not use text from untrusted sources. Otherwise, **correctness** and **security risks** for a filename have to be considered.' +)}} + #### backgroundColor(Color) = 'auto' @@ -214,7 +228,8 @@ Restore configuration item. Data view tool, which could display data in current chart and updates chart after being edited. {{ use: feature-common( - title = "data view" + title = "data view", + warnToolboxDataViewSecurity = true ) }} #### readOnly(boolean) = false @@ -231,6 +246,10 @@ Whether it is read-only. Define a function to present dataView. It is used to replace default textarea for richer data editing. It can return a DOM object, or an HTML string. +{{ use: partial-security-warning( + desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The HTML provided by `optionToContent` is embedded in the panel HTML without HTML-escaping, so it should be properly escaped before being passed in.' +)}} + For example: ```ts optionToContent: function(opt) { @@ -265,6 +284,10 @@ When optionToContent is used, if you want to support refreshing chart after data There are 3 names in data view, which are `['data view', 'turn off' and 'refresh']`. +{{ use: partial-security-warning( + desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The items in `lang` are embedded in the HTML without HTML-escaping, so it should be properly escaped before being passed in.' +)}} + #### backgroundColor(string) = '#fff' <ExampleUIControlColor default="#fff" /> diff --git a/en/option/partial/security-warning.md b/en/option/partial/security-warning.md index e9c293e3..af413563 100644 --- a/en/option/partial/security-warning.md +++ b/en/option/partial/security-warning.md @@ -1,5 +1,13 @@ -{{ target: security-warning }} +{{ target: partial-security-warning }} <div class="doc-partial-security-warning"> -**[WARNING]:** ${desc} Security risks must be considered here. See ["Security"](${handbookPath}best-practices/security) for recommendations on safe usage. +<span class="warning-title">[WARNING]:</span> ${desc} {{ if: ${securityRiskExclamation} }}${securityRiskExclamation}{{ else }}**Security risks** must be considered when using it.{{ /if }} See document ["Security"](${handbookPath}best-practices/security) for recommendations on safe usage. </div> {{ /target }} + + +{{ target: partial-security-url-common-warning }} +{{ use: partial-security-warning( + desc: 'This URL string is accepted directly without any internal sanitization.', + securityRiskExclamation: '**Security risks** must be considered if it comes from untrusted sources.' +)}} +{{ /target }} diff --git a/en/option/partial/tooltip-common.md b/en/option/partial/tooltip-common.md index ee7b9214..0d726284 100644 --- a/en/option/partial/tooltip-common.md +++ b/en/option/partial/tooltip-common.md @@ -305,9 +305,13 @@ formatter: '{b0}: {c0}<br />{b1}: {c1}' The format of callback function: ```ts -(params: Object|Array, ticket: string, callback: (ticket: string, html: string)) => string | HTMLElement | HTMLElement[] +(params: Object|Array, ticket: string, callback: (ticket: string, html: string | HTMLElement | HTMLElement[])) => string | HTMLElement | HTMLElement[] ``` +{{ use: partial-security-warning( + desc: '`tooltip` is implemented in HTML (unless [tooltip.renderMode](~tooltip.renderMode) is set as `richText`), allowing users to customize the HTML in this way. The content in the HTML should be properly escaped before being passed in.' +)}} + The first parameter `params` is the data that the formatter needs. Its format is shown as follows: {{ use: partial-formatter-params-structure( @@ -369,13 +373,18 @@ Interface: (value: number | string, dataIndex: number) => string ``` -> `dataIndex` is provided since `v5.5.0`. +{{ use: partial-version( + feature = '`dataIndex` is provided', + version = '5.5.0' +) }} Example: ```ts // Add $ prefix valueFormatter: (value) => '$' + value.toFixed(2) ``` + +> **[NOTE]:** Different from [tooltip.formater](~tooltip.formatter), raw HTML is NOT accepted in this approach -- the returned content will be escaped internally before rendering. {{ /if }} #${prefix} backgroundColor(Color) = 'rgba(50,50,50,0.7)' @@ -446,3 +455,7 @@ Extra CSS style for floating layer. The following is an example for adding shado extraCssText: 'box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);' ``` +{{ use: partial-security-warning( + desc: '`tooltip` is implemented in HTML (unless [tooltip.renderMode](~tooltip.renderMode) is set as `richText`), allowing users to customize the CSS text of the box in this way.', + securityRiskExclamation: '**Security risks** must be considered if the CSS text comes from untrusted sources.' +)}} diff --git a/en/option/series/sunburst.md b/en/option/series/sunburst.md index 600e45ba..5e975b44 100644 --- a/en/option/series/sunburst.md +++ b/en/option/series/sunburst.md @@ -215,6 +215,8 @@ Link address that redirects to when this sector is clicked. Only useful when [se See [series-sunburst.data.target](~series-sunburst.data.target). +{{ use: partial-security-url-common-warning }} + ### target(string) = 'blank' Like `target` attribute of HTML `<a>`, which can either be `'blank'` or `'self'`. See [series-sunburst.data.link](~series-sunburst.data.link). diff --git a/en/option/series/treemap.md b/en/option/series/treemap.md index 465ed63a..a5e9d8ed 100644 --- a/en/option/series/treemap.md +++ b/en/option/series/treemap.md @@ -391,6 +391,8 @@ Enable hyperlink jump when clicking on node. It is available when [series-treema See [series-treemap.data.target](~series-treemap.data.target). +{{ use: partial-security-url-common-warning }} + ### target(string) = 'blank' The same meaning as `target` in `html` `<a>` label, See [series-treemap.data.link](~series-treemap.data.link). Option values are: `'blank'` or `'self'`. diff --git a/src/style/mixin.scss b/src/style/mixin.scss index 4ef90f4c..7f68e23f 100644 --- a/src/style/mixin.scss +++ b/src/style/mixin.scss @@ -101,5 +101,14 @@ padding: 10px; border-left: 2px solid rgba(248, 113, 113, 1); color: rgb(100, 116, 139); + + code { + background: rgba(254, 202, 202, 1); + } + + .warning-title { + font-weight: bold; + color: rgba(185, 28, 28, 1); + } } } diff --git a/zh/option/component/title.md b/zh/option/component/title.md index 4520c13b..fe2c1490 100644 --- a/zh/option/component/title.md +++ b/zh/option/component/title.md @@ -43,10 +43,16 @@ const option = { 主标题文本，支持使用 `\n` 换行。 +{{ use: partial-security-warning( + securityRiskExclamation: '如果使用了 [toolbox.feature.saveAsImage](~toolbox.feature.saveAsImage)，并且没有设置 [toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name)，会用 `title[0].text` 替代。这种用法是历史实现但并不推荐，应该总是显式指定[toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name)；否则，不得不考虑 `title.text` 是否是个正确的文件名，以及其 **安全性**。' +)}} + ## link(string) = '' 主标题文本超链接。 +{{ use: partial-security-url-common-warning }} + ## target(string) = 'blank' 指定窗口打开主标题超链接。 @@ -80,6 +86,8 @@ const option = { 副标题文本超链接。 +{{ use: partial-security-url-common-warning }} + ## subtarget(string) = 'blank' 指定窗口打开副标题超链接，可选： diff --git a/zh/option/component/toolbox.md b/zh/option/component/toolbox.md index b05af9f2..12cb25fb 100644 --- a/zh/option/component/toolbox.md +++ b/zh/option/component/toolbox.md @@ -63,6 +63,11 @@ ${name} icon 样式设置。由于 icon 的文本信息只在 icon hover 时候 是否显示该工具。 #### title(string) = '${title}' +{{ if: ${warnToolboxDataViewSecurity} }} +{{ use: partial-security-warning( + desc: '`dataView` 面板是用 HTML 实现的，一些部分允许用户自定义格式和样式。`title` 字段会直接拼接到此 HTML 中，并没有做转义。因此传入前须要正确转义。' +)}} +{{ /if }} #### icon(string) @@ -243,11 +248,19 @@ option = { + 如果 `renderer` 的类型在 [初始化图表](api.html#echarts.init) 时被设为 `'canvas'`（默认），则支持 `'png'`（默认）和 `'jpg'`； + 如果 `renderer` 的类型在 [初始化图表](api.html#echarts.init) 时被设为 `'svg'`，则 `type` 只支持 `'svg'`（`'svg'` 格式的图片从 `v4.8.0` 开始支持）。 +{{ use: partial-security-warning( + securityRiskExclamation: '`type` 会被用于文件的扩展名。但是实现中并没有在内部对其进行合法性校验（历史因素）。所以不要传入不合法的值；否则，需要考虑 **安全风险**。' +)}} + #### name(string) <ExampleUIControlText /> -保存的文件名称，默认使用 [title.text](~title.text) 作为名称。 +保存的文件名称的扩展名之前的部分。如果没有指定，会使用 [title[0].text](~title.text)（如果存在的话）。完整的文件名是 `{name}.{type}`。 + +{{ use: partial-security-warning( + securityRiskExclamation: '建议总是显式指定 `name`，以及不使用“不可信任来源”的字符串。否则，须要考虑作为文件名的 **正确性** 和 **安全性**。' +)}} #### backgroundColor(Color) = 'auto' @@ -288,7 +301,8 @@ option = { 数据视图工具，可以展现当前图表所用的数据，编辑后可以动态更新。 {{ use: feature-common( - title = "数据视图" + title = "数据视图", + warnToolboxDataViewSecurity = true ) }} #### readOnly(boolean) = false @@ -305,6 +319,10 @@ option = { 自定义 dataView 展现函数，用以取代默认的 textarea 使用更丰富的数据编辑。可以返回 dom 对象或者 html 字符串。 +{{ use: partial-security-warning( + desc: '`dataView` 面板是用 HTML 实现的，一些部分允许用户自定义格式和样式。`optionToContent` 给出的 HTML 会直接拼接到面板 HTML 中，并没有做转义。因此传入前须要正确转义。' +)}} + 如下示例使用表格展现数据值： ```ts optionToContent: function(opt) { @@ -339,6 +357,10 @@ optionToContent: function(opt) { 数据视图上有三个话术，默认是`['数据视图', '关闭', '刷新']`。 +{{ use: partial-security-warning( + desc: '`dataView` 面板是用 HTML 实现的，一些部分允许用户自定义格式和样式。`lang` 中的内容会直接拼接到此 HTML 中，并没有做转义。因此传入前须要正确转义。' +)}} + #### backgroundColor(string) = '#fff' <ExampleUIControlColor default="#fff" /> diff --git a/zh/option/partial/security-warning.md b/zh/option/partial/security-warning.md index 66bc89a1..d1b85049 100644 --- a/zh/option/partial/security-warning.md +++ b/zh/option/partial/security-warning.md @@ -1,5 +1,12 @@ -{{ target: security-warning }} +{{ target: partial-security-warning }} <div class="doc-partial-security-warning"> -**[警告]:** ${desc} 使用时必须考虑安全风险。文档 [“安全性”](${handbookPath}best-practices/security) 给出了安全使用建议。 +<span class="warning-title">[警告]:</span> ${desc} {{ if: ${securityRiskExclamation} }}${securityRiskExclamation}{{ else }}使用时必须考虑 **安全风险**。{{ /if }}文档 [“安全性”](${handbookPath}best-practices/security) 给出了安全使用建议。 </div> {{ /target }} + +{{ target: partial-security-url-common-warning }} +{{ use: partial-security-warning( + desc: '此 URL 字符串直接被使用，并未在内部做其他净化处理（sanitization）', + securityRiskExclamation: '如果他们来自于“不受信任”的来源，必须考虑 **安全风险**。' +)}} +{{ /target }} diff --git a/zh/option/partial/tooltip-common.md b/zh/option/partial/tooltip-common.md index d4fbb02e..cea13ff1 100644 --- a/zh/option/partial/tooltip-common.md +++ b/zh/option/partial/tooltip-common.md @@ -311,11 +311,15 @@ formatter: '{b0}: {c0}<br />{b1}: {c1}' 回调函数格式： ```ts -(params: Object|Array, ticket: string, callback: (ticket: string, html: string)) => string | HTMLElement | HTMLElement[] +(params: Object|Array, ticket: string, callback: (ticket: string, html: string | HTMLElement | HTMLElement[])) => string | HTMLElement | HTMLElement[] ``` 支持返回 HTML 字符串或者创建的 DOM 实例。 +{{ use: partial-security-warning( + desc: 'tooltip 是用 HTML 实现的（除非 [tooltip.renderMode](~tooltip.renderMode) 设为 `richText`）。允许用此方式定制 HTML。传入 HTML 前须要对其内容进行正确转义。' +)}} + 第一个参数 `params` 是 formatter 需要的数据集。格式如下： {{ use: partial-formatter-params-structure( @@ -375,7 +379,10 @@ tooltip 中数值显示部分的格式化回调函数。 (value: number | string, dataIndex: number) => string ``` -> 自 `v5.5.0` 版本起提供 `dataIndex`。 +{{ use: partial-version( + feature = '`dataIndex` 参数', + version = '5.3.0' +) }} 示例： @@ -383,6 +390,7 @@ tooltip 中数值显示部分的格式化回调函数。 // 添加 $ 前缀 valueFormatter: (value) => '$' + value.toFixed(2) ``` +> **[注]:** 不同于 [tooltip.formater](~tooltip.formatter)，本方式不支持返回原始 HTML。返回内容渲染前会被自动按需转义。 {{ /if }} #${prefix} backgroundColor(Color) = 'rgba(50,50,50,0.7)' @@ -453,3 +461,7 @@ valueFormatter: (value) => '$' + value.toFixed(2) extraCssText: 'box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);' ``` +{{ use: partial-security-warning( + desc: 'tooltip 是用 HTML 实现的（除非 [tooltip.renderMode](~tooltip.renderMode) 设为 `richText`）。允许用此方式定制 toolbox 外壳的 CSS text。', + securityRiskExclamation: '如果此 CSS text 来自于“不受信任”的来源，必须考虑 **安全风险**。' +)}} diff --git a/zh/option/series/sunburst.md b/zh/option/series/sunburst.md index 020ca31c..5efe7752 100644 --- a/zh/option/series/sunburst.md +++ b/zh/option/series/sunburst.md @@ -364,6 +364,8 @@ const option = { 参见 [series-sunburst.data.target](~series-sunburst.data.target)。 +{{ use: partial-security-url-common-warning }} + ### target(string) = 'blank' 意义同 HTML `<a>` 标签中的 `target`，参见 [series-sunburst.data.link](~series-sunburst.data.link)。可选值为：`'blank'` 或 `'self'`。 diff --git a/zh/option/series/treemap.md b/zh/option/series/treemap.md index 1344490a..a259bbce 100644 --- a/zh/option/series/treemap.md +++ b/zh/option/series/treemap.md @@ -535,6 +535,8 @@ treemap 默认把第一个维度（Array 第一项）映射到『面积』上。 参见 [series-treemap.data.target](~series-treemap.data.target)。 +{{ use: partial-security-url-common-warning }} + ### target(string) = 'blank' 意义同 `html` `<a>` 标签中的 `target`，参见 [series-treemap.data.link](~series-treemap.data.link)。可选值为：`'blank'` 或 `'self'`。 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
