dompurify中文文档|dompurify js中文教程|解析

npm npmdoc 2年前 (2022-01-01) 3163次浏览

dompurify中文文档|dompurify js中文教程|解析

安装命令:npm i dompurify

DOM净化

npm 版本 构建和测试 下载 缩小尺寸 压缩包大小 家属

新产品管理

DOMPurify 是用于 HTML、MathML 和 SVG 的仅 DOM、超快、超容忍 XSS 清理程序。

它的使用和入门也非常简单。DOMPurify 于2014 年 2 月启动,同时已达到 2.3.4 版本。

DOMPurify 是用 JavaScript 编写的,适用于所有现代浏览器(Safari (10+)、Opera (15+)、Internet Explorer (10+)、Edge、Firefox 和 Chrome – 以及几乎所有使用 Blink 或 WebKit 的其他浏览器)。它不会在 MSIE6 或其他旧浏览器上中断。它要么使用回退,要么干脆什么都不做。

我们的自动化测试目前涵盖19 种不同的浏览器,未来还会有更多。我们还介绍了 Node.js v14.15.1、v15.4.0、v16.13.0、v17.0.0,在 jsdom 上运行DOMPurify已知较旧的 Node.js 版本也可以工作。

DOMPurify 由在 Web 攻击和 XSS 方面具有丰富背景的安全人员编写。不要怕。有关更多详细信息,请同时阅读我们的安全目标和威胁模型请阅读它。就像,真的。

它有什么作用?

DOMPurify 清理 HTML 并防止 XSS 攻击。您可以使用充满脏 HTML 的字符串提供给 DOMPurify,它会返回一个带有干净 HTML 的字符串(除非另有配置)。DOMPurify 将去除所有包含危险 HTML 的内容,从而防止 XSS 攻击和其他恶意行为。它也该死的快。我们使用浏览器提供的技术并将它们变成 XSS 过滤器。您的浏览器越快,DOMPurify 就会越快。

我该如何使用它?

这简单。只需在您的网站上包含 DOMPurify。

使用未缩小的开发版本

<script type="text/javascript" src="src/purify.js"></script>

使用缩小和测试的生产版本(可用的源映射)

<script type="text/javascript" src="dist/purify.min.js"></script>

之后,您可以通过执行以下代码来清理字符串:

let clean = DOMPurify.sanitize( dirty );

生成的 HTML 可以使用innerHTML或 DOM写入 DOM 元素document.write()这完全取决于你。请注意,默认情况下,我们允许使用 HTML、SVGMathML。如果您只需要 HTML(这可能是一个非常常见的用例),您也可以轻松地进行设置:

let clean = DOMPurify.sanitize( dirty , {USE_PROFILES: {html: true}} );

有没有脚炮的潜力?

好了,请注意,如果你清理HTML,然后修改它之后,你可能很容易丧失消毒的效果如果您在清理后将清理过的标记提供给另一个库,请确保库不会自行处理 HTML。

好的,有道理,让我们继续

DOMPurify.removed清理标记后,您还可以查看属性并找出哪些元素和属性被丢弃。不要使用此属性来做出任何安全关键决策。这只是好奇心的一个小帮手。

如果你使用Require.js这样AMD模块加载器,你也可以异步加载这个脚本:

import DOMPurify from 'dompurify';

var clean = DOMPurify.sanitize(dirty);

DOMPurify 还可以在 Node.js 的服务器端工作,也可以通过Browserify或类似的转换器在客户端工作至少需要 Node.js 4.x 或更新版本。我们的支持力求遵循Node.js 发布周期DOMPurify 打算支持任何被标记为活动的版本。同时,我们逐步停止支持任何标记为维护的版本。DOMPurify 可能不会立即中断维护中的所有版本,而是停止对这些旧版本运行测试。

npm install dompurify

对于 JSDOM v10 或更新版本

const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);

const clean = DOMPurify.sanitize(dirty);

对于早于 v10 的 JSDOM 版本

const createDOMPurify = require('dompurify');
const jsdom = require('jsdom').jsdom;

const window = jsdom('').defaultView;
const DOMPurify = createDOMPurify(window);

const clean = DOMPurify.sanitize(dirty);

有演示吗?

当然有demo!玩转 DOMPurify

如果我发现安全漏洞怎么办?

首先,请立即通过电子邮件与我们联系,以便我们进行修复。PGP密钥

此外,您可能有资格获得漏洞赏金!Fastmail的优秀人员使用 DOMPurify 作为他们的服务,并将我们的库添加到他们的漏洞赏金范围。因此,如果您找到绕过或削弱 DOMPurify 的方法,请同时查看他们的网站和漏洞赏金信息

请一些纯化样品?

纯化标记是什么样子的?好吧,该演示显示了一大堆令人讨厌的元素。但让我们也展示一些较小的例子!

DOMPurify.sanitize('<img src=x onerror=alert(1)//>'); // becomes <img src="x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('<p>abc<iframe//src=jAva&Tab;script:alert(3)>def</p>'); // becomes <p>abc</p>
DOMPurify.sanitize('<math><mi//xlink:href="data:x,<script>alert(4)</script>">'); // becomes <math><mi></mi></math>
DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>'); // becomes <table><tbody><tr><td>HELLO</td></tr></tbody></table>
DOMPurify.sanitize('<UL><li><A HREF=//google.com>click</UL>'); // becomes <ul><li><a href="//google.com">click</a></li></ul>

支持什么?

DOMPurify 目前支持 HTML5、SVG 和 MathML。DOMPurify 默认允许 CSS、HTML 自定义数据属性。DOMPurify 还支持 Shadow DOM – 并递归地清理 DOM 模板。DOMPurify 还允许您清理 HTML 以便与 jQuery$()elm.html()API一起使用,不会出现任何已知问题。

像 MSIE8 这样的旧浏览器呢?

DOMPurify 为较旧的 MSIE 浏览器提供了回退行为。它使用仅限 MSIE 的toStaticHTML功能进行清理。但是请注意,在这种回退模式下,下面显示的配置标志几乎没有任何效果。你需要自己处理。

如果甚至toStaticHTML不支持,DOMPurify 什么也不做。它只是简单地返回您输入的字符串。

DOMPurify 还公开了一个名为 的属性isSupported,它告诉您 DOMPurify 是否能够完成它的工作。

DOMPurify 和 Trusted Types 呢?

在 1.0.9 版本中,DOMPurify 添加了Trusted Types API 的支持在 2.0.0 版本中,添加了一个配置标志来控制 DOMPurify 对此的行为。

DOMPurify.sanitizeTrusted Types API 可用且RETURN_TRUSTED_TYPE设置为的环境中使用时true,它会尝试返回一个TrustedHTML值而不是字符串(RETURN_DOMRETURN_DOM_FRAGMENT配置选项的行为不会改变)。

我可以配置 DOMPurify 吗?

是的。包含的默认配置值已经相当不错了 – 但您当然可以覆盖它们。查看/demos文件夹以查看有关如何自定义 DOMPurify 的大量示例

/**
 * General settings
 */

// strip {{ ... }} and <% ... %> to make output safe for template systems
// be careful please, this mode is not recommended for production usage.
// allowing template parsing in user-controlled HTML is not advised at all.
// only use this mode if there is really no alternative.
var clean = DOMPurify.sanitize(dirty, {SAFE_FOR_TEMPLATES: true});

/**
 * Control our allow-lists and block-lists
 */
// allow only <b> elements, very strict
var clean = DOMPurify.sanitize(dirty, {ALLOWED_TAGS: ['b']});

// allow only <b> and <q> with style attributes
var clean = DOMPurify.sanitize(dirty, {ALLOWED_TAGS: ['b', 'q'], ALLOWED_ATTR: ['style']});

// allow all safe HTML elements but neither SVG nor MathML
// note that the USE_PROFILES setting will override the ALLOWED_TAGS setting
// so don't use them together
var clean = DOMPurify.sanitize(dirty, {USE_PROFILES: {html: true}});

// allow all safe SVG elements and SVG Filters, no HTML or MathML
var clean = DOMPurify.sanitize(dirty, {USE_PROFILES: {svg: true, svgFilters: true}});

// allow all safe MathML elements and SVG, but no SVG Filters
var clean = DOMPurify.sanitize(dirty, {USE_PROFILES: {mathMl: true, svg: true}});

// change the default namespace from HTML to something different
var clean = DOMPurify.sanitize(dirty, {NAMESPACE: 'http://www.w3.org/2000/svg'});

// leave all safe HTML as it is and add <style> elements to block-list
var clean = DOMPurify.sanitize(dirty, {FORBID_TAGS: ['style']});

// leave all safe HTML as it is and add style attributes to block-list
var clean = DOMPurify.sanitize(dirty, {FORBID_ATTR: ['style']});

// extend the existing array of allowed tags and add <my-tag> to allow-list
var clean = DOMPurify.sanitize(dirty, {ADD_TAGS: ['my-tag']});

// extend the existing array of allowed attributes and add my-attr to allow-list
var clean = DOMPurify.sanitize(dirty, {ADD_ATTR: ['my-attr']});

// prohibit HTML5 data attributes, leave other safe HTML as is (default is true)
var clean = DOMPurify.sanitize(dirty, {ALLOW_DATA_ATTR: false});

/**
 * Control behavior relating to Custom Elements
 */
 
// DOMPurify allows to define rules for Custom Elements. When using the CUSTOM_ELEMENT_HANDLING 
// literal, it is possible to define exactly what elements you wish to allow (by default, none are allowed).
//
// The same goes for their attributes. By default, the built-in or configured allow.list is used.
//
// You can use a RegExp literal to specify what is allowed or a predicate, examples for both can be seen below.
// The default values are very restrictive to prevent accidental XSS bypasses. Handle with great care!


var clean = DOMPurify.sanitize(
    '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
    {
        CUSTOM_ELEMENT_HANDLING: {
            tagNameCheck: null, // no custom elements are allowed
            attributeNameCheck: null, // default / standard attribute allow-list is used
            allowCustomizedBuiltInElements: false, // no customized built-ins allowed
        },
    }
); // <div is=""></div>
 
var clean = DOMPurify.sanitize(
    '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
    {
        CUSTOM_ELEMENT_HANDLING: {
            tagNameCheck: /^foo-/, // allow all tags starting with "foo-"
            attributeNameCheck: /baz/, // allow all attributes containing "baz"
            allowCustomizedBuiltInElements: false, // customized built-ins are allowed
        },
    }
); // <foo-bar baz="foobar"></foo-bar><div is=""></div>
  
var clean = DOMPurify.sanitize(
    '<foo-bar baz="foobar" forbidden="true"></foo-bar><div is="foo-baz"></div>',
    {
        CUSTOM_ELEMENT_HANDLING: {
            tagNameCheck: (tagName) => tagName.match(/^foo-/), // allow all tags starting with "foo-"
            attributeNameCheck: (attr) => attr.match(/baz/), // allow all containing "baz"
            allowCustomizedBuiltInElements: true, // allow customized built-ins
        },
    }
); // <foo-bar baz="foobar"></foo-bar><div is="foo-baz"></div>

/**
 * Control behavior relating to URI values
 */
// extend the existing array of elements that can use Data URIs
var clean = DOMPurify.sanitize(dirty, {ADD_DATA_URI_TAGS: ['a', 'area']});

// extend the existing array of elements that are safe for URI-like values (be careful, XSS risk)
var clean = DOMPurify.sanitize(dirty, {ADD_URI_SAFE_ATTR: ['my-attr']});

/**
 * Control permitted attribute values
 */
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, cid and xmpp are allowed.
var clean = DOMPurify.sanitize(dirty, {ALLOW_UNKNOWN_PROTOCOLS: true});

// allow specific protocols handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, cid and xmpp are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
var clean = DOMPurify.sanitize(dirty, {ALLOWED_URI_REGEXP: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|cid|xmpp|xxx):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;});

/**
 * Influence the return-type
 */
// return a DOM HTMLBodyElement instead of an HTML string (default is false)
var clean = DOMPurify.sanitize(dirty, {RETURN_DOM: true});

// return a DOM DocumentFragment instead of an HTML string (default is false)
var clean = DOMPurify.sanitize(dirty, {RETURN_DOM_FRAGMENT: true});

// use the RETURN_TRUSTED_TYPE flag to turn on Trusted Types support if available
var clean = DOMPurify.sanitize(dirty, {RETURN_TRUSTED_TYPE: true}); // will return a TrustedHTML object instead of a string if possible

/**
 * Influence how we sanitize
 */
// return entire document including <html> tags (default is false)
var clean = DOMPurify.sanitize(dirty, {WHOLE_DOCUMENT: true});

// disable DOM Clobbering protection on output (default is true, handle with care, minor XSS risks here)
var clean = DOMPurify.sanitize(dirty, {SANITIZE_DOM: false});

// keep an element's content when the element is removed (default is true)
var clean = DOMPurify.sanitize(dirty, {KEEP_CONTENT: false});

// glue elements like style, script or others to document.body and prevent unintuitive browser behavior in several edge-cases (default is false)
var clean = DOMPurify.sanitize(dirty, {FORCE_BODY: true});

// change the parser type so sanitized data is treated as XML and not as HTML, which is the default
var clean = DOMPurify.sanitize(dirty, {PARSER_MEDIA_TYPE: 'application/xhtml+xml'});

/**
 * Influence where we sanitize
 */
// use the IN_PLACE mode to sanitize a node "in place", which is much faster depending on how you use DOMPurify
var dirty = document.createElement('a');
dirty.setAttribute('href', 'javascript:alert(1)');
var clean = DOMPurify.sanitize(dirty, {IN_PLACE: true}); // see https://github.com/cure53/DOMPurify/issues/288 for more info

这里还有更多示例,展示了如何运行、自定义和配置 DOMPurify 以满足您的需求。

持久配置

DOMPurify.sanitize您可以使用该DOMPurify.setConfig方法而不是重复地将相同的配置传递给您的配置将持续到您下一次调用DOMPurify.setConfig,或者直到您调用DOMPurify.clearConfig以重置它。请记住,只有一个活动配置,这意味着一旦设置,DOMPurify.sanitize将忽略传递给的所有额外配置参数

挂钩

DOMPurify 允许您通过将一个或多个具有该DOMPurify.addHook方法的函数附加到以下钩子之一来增强其功能

  • beforeSanitizeElements
  • uponSanitizeElement (没有’s’ – 为每个元素调用)
  • afterSanitizeElements
  • beforeSanitizeAttributes
  • uponSanitizeAttribute
  • afterSanitizeAttributes
  • beforeSanitizeShadowDOM
  • uponSanitizeShadowNode
  • afterSanitizeShadowDOM

它将当前处理的 DOM 节点(在需要时带有已验证节点和属性数据的文字以及 DOMPurify 配置)传递给回调。查看MentalJS 钩子演示以了解如何很好地使用 API。

示例

DOMPurify.addHook('beforeSanitizeElements', function (
  currentNode,
  hookEvent,
  config
) {
  // Do something with the current node and return it
  // You can also mutate hookEvent (i.e. set hookEvent.forceKeepAttr = true)
  return currentNode;
});

持续集成

我们目前正在将 Github Actions 与 BrowserStack 结合使用。这使我们有可能为每个提交确认所有支持的浏览器都按计划进行。在此处查看构建日志:https : //github.com/cure53/DOMPurify/actions

您可以通过执行进一步运行本地测试npm test这些测试适用于 Node.js v0.6.2 和 jsdom@8.5.0。

所有相关提交都将使用密钥签名以0x24BB6BF4增加安全性(自 2016 年 4 月 8 日起)。

发展与贡献

安装 ( yarn i)

我们同时支持yarnnpm@5.2官方,同时为任一依赖管理器提供锁定文件,以提供可重现的安装和构建。TravisCI 本身被配置为使用yarn. 使用旧版本时,npm我们无法完全确保已安装依赖项的版本,这可能会导致意外问题。

脚本

我们依靠 npm run-scripts 与我们的工具基础设施集成。我们使用 ESLint 作为预提交钩子来确保代码一致性。此外,为了简化格式化,我们在构建资产时使用更漂亮的./distrollup

这些是我们的 npm 脚本:

  • npm run dev 在观察变化源的同时开始构建
  • npm run test 通过 jsdom 和 karma 运行我们的测试套件

    • test:jsdom 只通过 jsdom 运行测试
    • test:karma 仅通过业力运行测试
  • npm run lint 使用 ESLint(通过 xo)整理源代码
  • npm run format 使用更漂亮的格式来格式化我们的源代码以轻松通过 ESLint
  • npm run build 将我们的分销资产缩小和未缩小为 UMD 模块

    • npm run build:umd 只构建一个未缩小的 UMD 模块
    • npm run build:umd:min 只构建一个缩小的 UMD 模块

注意:所有通过触发的运行脚本npm run <script>也可以使用yarn <script>.

还有更多的 npm 脚本,但它们主要是为了与 CI 集成,或者是“私有的”,例如在每次提交时修改构建分发文件。

安全邮件列表

我们维护一个邮件列表,每当发布 DOMPurify 的安全关键版本时都会发出通知。这意味着,如果有人发现了绕过,并且我们通过发布修复了它(当找到绕过时总是发生这种情况),邮件将发送到该列表。这通常在了解旁路后几分钟或几小时内发生。该列表可以在这里订阅:

https://lists.ruhr-uni-bochum.de/mailman/listinfo/dompurify-security

功能版本不会在此列表中公布。

谁贡献了?

许多人帮助和帮助DOMPurify成为现在的样子,需要在这里得到承认!

格兰特·格里森 💸,低效💸,格兰姆💸,奥利奥奶昔💸,德克莱默💸,德肯斯❤️,地狱❤️franktopelNateScarletneiljfhemberger里斯-VAN-DER-WELydanivterjanq文件描述符ConradIrwingibson042choumx0xSobkystyfletlau88strugeeoparozmathiasbynensedg2sdnkolegovdhardtkewirehead ,刺0 ,styumozfreddybmikesamueljorangreefjimmyhchanjameydeoriojameskraushyderalihansottowirtzhackvertorfreddybflavorjonesdjfarrellyDEVDcamerondunfordbuu700buildogalabiagaVector919RobbertGreLIFuzzySocketsArtemBernatskyy@garethheyes@shafigullin@mmrupp@irsdlShikariSenpaiansjdnakjdnajkd@asutherland@mathias@cgvwzq@robbertatwork@giutro@CmdEngineer_@ avr4mit尤其是@securitymb❤️@masatokinugawa❤️

测试由

最后但并非最不重要的一点,感谢BrowserStack 开源计划通过免费服务支持该项目,并在此基础上提供出色、专注和非常专业的支持。

项目贡献人员列表:


极客公园 , 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权
转载请注明原文链接:dompurify中文文档|dompurify js中文教程|解析
喜欢 (0)
.excerpt .focus {display:none}