Security Checklist for Code Contributors

Security issues should be given special attention. Although ECharts focuses on visualization logic and generally assumes that inputs originate from trusted sources, contributors should stay cautious of potential security risks during implementation. They should either mitigate these risks whenever possible, or highlight them in documentation for each API (including ECharts options).

XSS is one of the most common security risks, especially when using innerHTML or similar APIs. Common measures to prevent XSS are listed below -- some can be handled by ECharts, while others require implementation by the API caller as needed.

• Do not input content from untrusted sources unless unavoidable. Whether an input source is trusted can only be determined by the ECharts API caller.
• Avoid using security-sensitive APIs (such as innerHTML) unless unavoidable or unless their safety can be guaranteed. This decisions should be made by ECharts contributors during implementation.
• Escape content before embeding it into HTML/JS/CSS/URL text. Escaping is a fundamental requirement for correct rendering, which also removes possible XSS attack vectors. However, in practice, this is the most frequently overlooked part that can lead to security issues. Therefore, API design and implementation should always enforce automatic escaping internally, except in cases where raw caller-provided HTML/CSS/URL text have to be accepted. In such case, security warnings must be clearly included in documentation.
• Sanitizing untrusted HTML/CSS/URL. This measure is generally left to API callers, since ECharts itself can not determine which inputs are untrusted, and no universal sanitization rules fit all cases.
• Other measures, such as sandboxing, CSP, Trusted Types, etc., are left to API callers.

Before committing a pull request, please check your new design and implementation against the CHECKLIST below.

• Does this code modification involve any security-sensitive web API?
  • Although a security-sensitive API is not easy to define precisely, empirically it generally refers to any API that:
    • interprets an input string as HTML/JS/CSS, or
    • can arbitrary modify of DOM structures, or
    • can trigger arbitrary browser navigations, or
    • can access or modify content not owned by ECharts.
  • For example:
    • DOM-manipulation APIs: innerHTML = ..., outerHTML = ..., insertAdjacentHTML(...), creating a <script> and loading JS, etc.
    • DOM-selection APIs: querySelector querySelectorAll getElementsById, getElementsByClassName, getElementsByTagName, etc.
    • JS built-in APIs: eval(...), Function(...), setTimeout(string), setInterval(string), etc.
    • Style-manipulation APIs: element.style.cssText = ..., setting a style attribute, injecting a <style> block, creating a <link> and loading CSS, etc.
    • URL-related APIs: a.href = ..., iframe.src = ..., location.href = ..., document.location = ..., window.open(url), <form action>, etc.
  • Contributors should handle these APIs cautiously:
    • Do not use them unless absolute necessary or unless their safety can be guaranteed (e.g., by enforcing strict escaping before assigning to innerHTML, ensuring that no code can ever be interpreted).
    • If code interpretation is allowed by design, or if any potential risk may be introduced, a clear security warning and usage guide must be included in the documentation (as demonstrated in tooltip.formatter).
• Do the newly introduced ECharts APIs (including ECharts options) potentially allow callers to access or modify anything outside of ECharts' ownership (e.g., DOM elements, styles, or JS context outside of ECharts's scope)?
  • This possibility should generally be avoided.
  • Such risks can be introduced unintentionally. For example, if a new ECharts API allows the caller to input a DOM selector, it may be difficult to restrict the selector's scope. As a result, DOM elements outside of ECharts' ownership could be accessed or modified unexpectedly. Such API design should be avoided.
  • An exception is when the design is unavoidable and the feature is necessary. For instance, tooltip.formatter allows users to customize the format using raw HTML. In such cases, a clear security warning and usage guide must be included in the documentation.

Security Guidelines explain the security model, checklists, and safe usage recommendations based on the perspective of developers using ECharts API. ECharts contributors should also follow this document and update it as necessary.