100pah commented on code in PR #148: URL: https://github.com/apache/echarts-handbook/pull/148#discussion_r2446816479
########## contents/en/best-practices/security.md: ########## @@ -0,0 +1,97 @@ +# Security + +## Overview + +ECharts aims to provide rich and flexible visualization capabilities. Although the vast majority of its APIs do not require special security considerations, sereval APIs are exceptions. For example, the option `tooltip.formatter` accepts a raw HTML string, allowing full control over the component's content and layout; the option `title.link` uses the provided URL string directly without automatic sanitization. While this flexibility is powerful, security risks may arise if the input comes from untrusted sources. These APIs are listed below, along with suggestions on how to use these features safely. + +Any security issues can be reported to [[email protected]](mailto:[email protected]) . + + +## Security Boundaries and Checklist [[[#security_boundaries_and_checklist]]] + +ECharts focuses on visualization logic. It assumes that inputs are trusted, and does not automatically sanitize them. In fact, ECharts itself can not properly sanitize inputs, as there are no universal sanitization rules that applies to all use cases. However, ECharts should clearly identify which APIs (especially ECharts options) require security-related preprocessing or considerations in specific use cases. Given the large number of ECharts options, preprocess all inputs in every case would be impractical and unnecessary. + +ECharts renders using Canvas or SVG, except for several special components that allow HTML rendering (e.g., [toolip](${optionPath}tooltip), [dataView](${optionPath}toolbox.feature.dataView)). ECharts APIs accept Non-JS-function inputs and JS-function inputs. JS-function inputs are intended to be execute. Most non-JS-function inputs (e.g., plain text provided to be rendered) are treated as data only, and are inherently prevented from code evaluation and execution. Therefore, they generally do not require sanitization from malicious code. However, several APIs allow embeding potential unsafe content (for example, raw HTML or raw URLs) into the page. These APIs are powerful but vulnerable to Cross-Site Scripting (XSS) and related attacks if the inputs originate from untrusted sources. + +**Generally speaking, if no untrusted content is involved, these injection vulnerabilities will not arise.** Untrusted content refers to content that originates from a source that can not be fully controlled, or that can be modified or injected by users or external systems. Developers must assume it unsafe to use directly in HTML, CSS and JS. For example, content is untrusted if it is produced by users or received from a client. However, handling user-provided content is often unavoidable. For example, when rendering user data fetched from a database inside an HTML-based `tooltip` through a customized formatter, additional processing is required to ensure correctness (typically by HTML escaping) and to prevent XSS and related attacks (typically by sanitizing any untrusted parts if they can not be unescaped to plain text). + +Before deploying charts, please review this **checklist** to ensure your usage is safe: + +| APIs | Potential Risks and Suggestions | +| ------|------------------ | +| **option [tooltip.formatter](${optionPath}tooltip.formatter)**<br>· `formatter` allows HTML string or DOM elements input, which are later rendered directly inside the tooltip, where XSS risks need to be considered.<br>(exceptions): A string directly set to the `formatter` is treated as a simple template for later combining with data internally. [tooltip.renderMode: 'richText'](${optionPath}tooltip.renderMode) is another level of templating syntax for styling. Both of them are internally implemented and safe from injection.<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>· The `tooltip.dataView` panel is fully rendered in HTML. Certain parts of the HTML string are allowed to be customized via these APIs. | XSS risks should be consi dered. In most cases, HTML escaping alone is sufficient. But if any unescaped parts originate from untrusted sources, more measures are required (e.g., sanitization, sandboxing).<br><br>See section ["Passing Raw HTML Safely"](best-practices/security#passing_raw_html_safely) for safe usage recommendations. | +| **option [tooltip.extraCssText](${optionPath}tooltip.extraCssText)**<br>· `extraCssText` accepts a raw CSS style string for later directly appending to `tooltipEl.style.cssText`(via the DOM API).<br>(exceptions): this option is not applicable when [tooltip.renderMode: 'richText'](${optionPath}tooltip.renderMode).<br> | Safe if the input comes from trusted sources; otherwise, a careful assessment is required.<br><br>See section ["Passing inline CSS Safely"](best-practices/security#passing_inline_css_safely) for details. | +| **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>· They accept raw URLs directly for these links. | Safe if the input comes from trusted sources; otherwise, XSS risks should be considered.<br><br>See section ["Passing Raw URLs Safely"](best-practices/security#passing_raw_urls_safely) for safe usage recommendations. +**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>· The download filename is assembled by `{name}.{type}` without validation or sanitization. If `name` is not provided, `title[0].text` (if any) has historically been used instead, although this usage is not recommended. | See section ["Passing Download Filename Safely"](best-practices/security#passing_download_filename_safely) for safe usage recommendations. | Review Comment: `title[0].text` accurately reflects the current behavior or implementation. `title[1].text` will not be used. And I found that no doc mentioned it. Additionally, I think this logic should be removed, because it doesn't seems necessary, and may introduces risks or troubles if an invalid `title.text` is used as a filename. -- 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]
