100pah commented on PR #148:
URL: https://github.com/apache/echarts-handbook/pull/148#issuecomment-3438050729
Add a doc for contributors of echarts.
It can be added to the echarts github wiki, along with other documents for
contributors after reviewing.
---
# Security Checklist for 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 the document 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 unavoided. 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 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 documentations**.
+ 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](https://echarts.apache.org/en/option.html#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](https://echarts.apache.org/handbook/en/security)
explain the security model, checklists, and safe usage recommendations based on
the perspective of developers using ECharts. ECharts contributors should also
follow this document and update it as necessary.
--
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]
