diff --git a/README.md b/README.md index 4868a40..fd7bc1d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ [![NPM version][npm-image]][npm-url] -[![build status][travis-image]][travis-url] +[![Node.js CI](https://github.com/leizongmin/js-xss/actions/workflows/nodejs.yml/badge.svg)](https://github.com/leizongmin/js-xss/actions/workflows/nodejs.yml) [![Test coverage][coveralls-image]][coveralls-url] [![David deps][david-image]][david-url] [![node version][node-image]][node-url] @@ -8,8 +8,6 @@ [npm-image]: https://img.shields.io/npm/v/xss.svg?style=flat-square [npm-url]: https://npmjs.org/package/xss -[travis-image]: https://img.shields.io/travis/leizongmin/js-xss.svg?style=flat-square -[travis-url]: https://travis-ci.org/leizongmin/js-xss [coveralls-image]: https://img.shields.io/coveralls/leizongmin/js-xss.svg?style=flat-square [coveralls-url]: https://coveralls.io/r/leizongmin/js-xss?branch=master [david-image]: https://img.shields.io/david/leizongmin/js-xss.svg?style=flat-square @@ -41,26 +39,26 @@ ## Features -* Specifies HTML tags and their attributes allowed with whitelist -* Handle any tags or attributes using custom function. +- Specifies HTML tags and their attributes allowed with whitelist +- Handle any tags or attributes using custom function. ## Reference -* [XSS Filter Evasion Cheat Sheet](https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet) -* [Data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme) -* [XSS with Data URI Scheme](http://hi.baidu.com/badzzzz/item/bdbafe83144619c199255f7b) +- [XSS Filter Evasion Cheat Sheet](https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet) +- [Data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme) +- [XSS with Data URI Scheme](http://hi.baidu.com/badzzzz/item/bdbafe83144619c199255f7b) ## Benchmark (for references only) -* the xss module: 22.53 MB/s -* `xss()` function from module `validator@0.3.7`: 6.9 MB/s +- the xss module: 22.53 MB/s +- `xss()` function from module `validator@0.3.7`: 6.9 MB/s For test code please refer to `benchmark` directory. ## They are using xss module -* **nodeclub** - A Node.js bbs using MongoDB - https://github.com/cnodejs/nodeclub -* **cnpmjs.org** - Private npm registry and web for Enterprise - https://github.com/cnpm/cnpmjs.org +- **nodeclub** - A Node.js bbs using MongoDB - https://github.com/cnodejs/nodeclub +- **cnpmjs.org** - Private npm registry and web for Enterprise - https://github.com/cnpm/cnpmjs.org ## Install @@ -99,9 +97,9 @@ Shim mode (reference file `test/test.html`): ```html ``` @@ -109,19 +107,19 @@ AMD mode - shim: ```html ``` @@ -185,8 +183,8 @@ and attributes not in the whitelist would be filter out. For example: // only tag a and its attributes href, title, target are allowed var options = { whiteList: { - a: ["href", "title", "target"] - } + a: ["href", "title", "target"], + }, }; // With the configuration specified above, the following HTML: // Hello @@ -289,9 +287,9 @@ myxss = new xss.FilterXSS({ whiteList: { position: /^fixed|relative$/, top: true, - left: true - } - } + left: true, + }, + }, }); html = myxss.process(''); ``` @@ -300,7 +298,7 @@ If you don't want to filter out the `style` content, just specify `false` to the ```javascript myxss = new xss.FilterXSS({ - css: false + css: false, }); ``` @@ -312,15 +310,18 @@ For more help, please see https://github.com/leizongmin/js-css-filter By using `stripIgnoreTag` parameter: -* `true` filter out tags not in the whitelist -* `false`: by default: escape the tag using configured `escape` function +- `true` filter out tags not in the whitelist +- `false`: by default: escape the tag using configured `escape` function Example: If `stripIgnoreTag = true` is set, the following code: ```html -code: +code: + ``` would output filtered: @@ -333,16 +334,19 @@ code:alert(/xss/); By using `stripIgnoreTagBody` parameter: -* `false|null|undefined` by default: do nothing -* `'*'|true`: filter out all tags not in the whitelist -* `['tag1', 'tag2']`: filter out only specified tags not in the whitelist +- `false|null|undefined` by default: do nothing +- `'*'|true`: filter out all tags not in the whitelist +- `['tag1', 'tag2']`: filter out only specified tags not in the whitelist Example: If `stripIgnoreTagBody = ['script']` is set, the following code: ```html -code: +code: + ``` would output filtered: @@ -355,15 +359,16 @@ code: By using `allowCommentTag` parameter: -* `true`: do nothing -* `false` by default: filter out HTML comments +- `true`: do nothing +- `false` by default: filter out HTML comments Example: If `allowCommentTag = false` is set, the following code: ```html -code: END +code: +END ``` would output filtered: @@ -379,12 +384,12 @@ code: END ```javascript var source = '
hello
'; var html = xss(source, { - onIgnoreTagAttr: function(tag, name, value, isWhiteAttr) { + onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) { if (name.substr(0, 5) === "data-") { // escape its value using built-in escapeAttrValue function return name + '="' + xss.escapeAttrValue(value) + '"'; } - } + }, }); console.log("%s\nconvert to:\n%s", source, html); @@ -403,12 +408,12 @@ convert to: ```javascript var source = "hewwww"; var html = xss(source, { - onIgnoreTag: function(tag, html, options) { + onIgnoreTag: function (tag, html, options) { if (tag.substr(0, 2) === "x-") { // do not filter its attributes return html; } - } + }, }); console.log("%s\nconvert to:\n%s", source, html); @@ -417,9 +422,11 @@ console.log("%s\nconvert to:\n%s", source, html); Result: ```html -hewwww -convert to: -<x>hewwww +hewwww + convert to: <x>hewwww ``` ### Parse images in HTML @@ -429,7 +436,7 @@ var source = 'abcd'; var list = []; var html = xss(source, { - onTagAttr: function(tag, name, value, isWhiteAttr) { + onTagAttr: function (tag, name, value, isWhiteAttr) { if (tag === "img" && name === "src") { // Use the built-in friendlyAttrValue function to escape attribute // values. It supports converting entity tags such as < to printable @@ -437,7 +444,7 @@ var html = xss(source, { list.push(xss.friendlyAttrValue(value)); } // Return nothing, means keep the default handling measure - } + }, }); console.log("image list:\n%s", list.join(", ")); @@ -446,8 +453,7 @@ console.log("image list:\n%s", list.join(", ")); Result: ```html -image list: -img1, img2, img3, img4 +image list: img1, img2, img3, img4 ``` ### Filter out HTML tags (keeps only plain text) @@ -457,7 +463,7 @@ var source = "helloend"; var html = xss(source, { whiteList: {}, // empty, means filter out all tags stripIgnoreTag: true, // filter out all HTML not in the whitelist - stripIgnoreTagBody: ["script"] // the script tag is a special case, we need + stripIgnoreTagBody: ["script"], // the script tag is a special case, we need // to filter out its content }); diff --git a/README.zh.md b/README.zh.md index f923209..3bdb4b8 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,5 +1,5 @@ [![NPM version][npm-image]][npm-url] -[![build status][travis-image]][travis-url] +[![Node.js CI](https://github.com/leizongmin/js-xss/actions/workflows/nodejs.yml/badge.svg)](https://github.com/leizongmin/js-xss/actions/workflows/nodejs.yml) [![Test coverage][coveralls-image]][coveralls-url] [![David deps][david-image]][david-url] [![node version][node-image]][node-url] @@ -8,8 +8,6 @@ [npm-image]: https://img.shields.io/npm/v/xss.svg?style=flat-square [npm-url]: https://npmjs.org/package/xss -[travis-image]: https://img.shields.io/travis/leizongmin/js-xss.svg?style=flat-square -[travis-url]: https://travis-ci.org/leizongmin/js-xss [coveralls-image]: https://img.shields.io/coveralls/leizongmin/js-xss.svg?style=flat-square [coveralls-url]: https://coveralls.io/r/leizongmin/js-xss?branch=master [david-image]: https://img.shields.io/david/leizongmin/js-xss.svg?style=flat-square @@ -36,22 +34,22 @@ ## 特性 -* 白名单控制允许的 HTML 标签及各标签的属性 -* 通过自定义处理函数,可对任意标签及其属性进行处理 +- 白名单控制允许的 HTML 标签及各标签的属性 +- 通过自定义处理函数,可对任意标签及其属性进行处理 ## 参考资料 -* [XSS 与字符编码的那些事儿 ---科普文](http://drops.wooyun.org/tips/689) -* [腾讯实例教程:那些年我们一起学 XSS](http://www.wooyun.org/whitehats/%E5%BF%83%E4%BC%A4%E7%9A%84%E7%98%A6%E5%AD%90) -* [mXSS 攻击的成因及常见种类](http://drops.wooyun.org/tips/956) -* [XSS Filter Evasion Cheat Sheet](https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet) -* [Data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme) -* [XSS with Data URI Scheme](http://hi.baidu.com/badzzzz/item/bdbafe83144619c199255f7b) +- [XSS 与字符编码的那些事儿 ---科普文](http://drops.wooyun.org/tips/689) +- [腾讯实例教程:那些年我们一起学 XSS](http://www.wooyun.org/whitehats/%E5%BF%83%E4%BC%A4%E7%9A%84%E7%98%A6%E5%AD%90) +- [mXSS 攻击的成因及常见种类](http://drops.wooyun.org/tips/956) +- [XSS Filter Evasion Cheat Sheet](https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet) +- [Data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme) +- [XSS with Data URI Scheme](http://hi.baidu.com/badzzzz/item/bdbafe83144619c199255f7b) ## 性能(仅作参考) -* xss 模块:22.53 MB/s -* validator@0.3.7 模块的 xss()函数:6.9 MB/s +- xss 模块:22.53 MB/s +- validator@0.3.7 模块的 xss()函数:6.9 MB/s 测试代码参考 benchmark 目录 @@ -92,9 +90,9 @@ Shim 模式(参考文件 `test/test.html`): ```html ``` @@ -102,19 +100,19 @@ AMD 模式(参考文件 `test/test_amd.html`): ```html ``` @@ -174,8 +172,8 @@ html = myxss.process(''); // 只允许a标签,该标签只允许href, title, target这三个属性 var options = { whiteList: { - a: ["href", "title", "target"] - } + a: ["href", "title", "target"], + }, }; // 使用以上配置后,下面的HTML // 大家好 @@ -278,9 +276,9 @@ myxss = new xss.FilterXSS({ whiteList: { position: /^fixed|relative$/, top: true, - left: true - } - } + left: true, + }, + }, }); html = myxss.process(''); ``` @@ -289,7 +287,7 @@ html = myxss.process(''); ```javascript myxss = new xss.FilterXSS({ - css: false + css: false, }); ``` @@ -301,15 +299,18 @@ myxss = new xss.FilterXSS({ 通过 `stripIgnoreTag` 来设置: -* `true`:去掉不在白名单上的标签 -* `false`:(默认),使用配置的`escape`函数对该标签进行转义 +- `true`:去掉不在白名单上的标签 +- `false`:(默认),使用配置的`escape`函数对该标签进行转义 示例: 当设置 `stripIgnoreTag = true`时,以下代码 ```html -code: +code: + ``` 过滤后将输出 @@ -322,16 +323,19 @@ code:alert(/xss/); 通过 `stripIgnoreTagBody` 来设置: -* `false|null|undefined`:(默认),不特殊处理 -* `'*'|true`:去掉所有不在白名单上的标签 -* `['tag1', 'tag2']`:仅去掉指定的不在白名单上的标签 +- `false|null|undefined`:(默认),不特殊处理 +- `'*'|true`:去掉所有不在白名单上的标签 +- `['tag1', 'tag2']`:仅去掉指定的不在白名单上的标签 示例: 当设置 `stripIgnoreTagBody = ['script']`时,以下代码 ```html -code: +code: + ``` 过滤后将输出 @@ -344,15 +348,16 @@ code: 通过 `allowCommentTag` 来设置: -* `true`:不处理 -* `false`:(默认),自动去掉 HTML 中的备注 +- `true`:不处理 +- `false`:(默认),自动去掉 HTML 中的备注 示例: 当设置 `allowCommentTag = false` 时,以下代码 ```html -code: END +code: +END ``` 过滤后将输出 @@ -368,12 +373,12 @@ code: END ```javascript var source = '
hello
'; var html = xss(source, { - onIgnoreTagAttr: function(tag, name, value, isWhiteAttr) { + onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) { if (name.substr(0, 5) === "data-") { // 通过内置的escapeAttrValue函数来对属性值进行转义 return name + '="' + xss.escapeAttrValue(value) + '"'; } - } + }, }); console.log("%s\nconvert to:\n%s", source, html); @@ -392,12 +397,12 @@ convert to: ```javascript var source = "hewwww"; var html = xss(source, { - onIgnoreTag: function(tag, html, options) { + onIgnoreTag: function (tag, html, options) { if (tag.substr(0, 2) === "x-") { // 不对其属性列表进行过滤 return html; } - } + }, }); console.log("%s\nconvert to:\n%s", source, html); @@ -406,9 +411,11 @@ console.log("%s\nconvert to:\n%s", source, html); 运行结果: ```html -hewwww -convert to: -<x>hewwww +hewwww + convert to: <x>hewwww ``` ### 分析 HTML 代码中的图片列表 @@ -418,13 +425,13 @@ var source = 'abcd'; var list = []; var html = xss(source, { - onTagAttr: function(tag, name, value, isWhiteAttr) { + onTagAttr: function (tag, name, value, isWhiteAttr) { if (tag === "img" && name === "src") { // 使用内置的friendlyAttrValue函数来对属性值进行转义,可将<这类的实体标记转换成打印字符< list.push(xss.friendlyAttrValue(value)); } // 不返回任何值,表示还是按照默认的方法处理 - } + }, }); console.log("image list:\n%s", list.join(", ")); @@ -433,8 +440,7 @@ console.log("image list:\n%s", list.join(", ")); 运行结果: ```html -image list: -img1, img2, img3, img4 +image list: img1, img2, img3, img4 ``` ### 去除 HTML 标签(只保留文本内容) @@ -444,7 +450,7 @@ var source = "helloend"; var html = xss(source, { whiteList: {}, // 白名单为空,表示过滤所有标签 stripIgnoreTag: true, // 过滤所有非白名单标签的HTML - stripIgnoreTagBody: ["script"] // script标签较特殊,需要过滤标签中间的内容 + stripIgnoreTagBody: ["script"], // script标签较特殊,需要过滤标签中间的内容 }); console.log("text: %s", html);