update README

This commit is contained in:
Zongmin Lei
2015-11-18 10:21:56 +08:00
parent b546f64278
commit 2fb5bdb3f6
2 changed files with 43 additions and 45 deletions

View File

@@ -1,7 +1,6 @@
[![NPM version](https://badge.fury.io/js/xss.png)](http://badge.fury.io/js/xss) [![NPM version](https://badge.fury.io/js/xss.png)](http://badge.fury.io/js/xss)
[![Build Status](https://secure.travis-ci.org/leizongmin/js-xss.png?branch=master)](http://travis-ci.org/leizongmin/js-xss) [![Build Status](https://secure.travis-ci.org/leizongmin/js-xss.png?branch=master)](http://travis-ci.org/leizongmin/js-xss)
[![Dependencies Status](https://david-dm.org/leizongmin/js-xss.png)](https://david-dm.org/leizongmin/js-xss) [![Dependencies Status](https://david-dm.org/leizongmin/js-xss.png)](https://david-dm.org/leizongmin/js-xss)
[![testling badge](https://ci.testling.com/leizongmin/js-xss.png)](https://ci.testling.com/leizongmin/js-xss)
Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist. Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist.
====== ======
@@ -83,7 +82,7 @@ $ bower install https://github.com/leizongmin/js-xss.git
### On Node.js ### On Node.js
```JavaScript ```javascript
var xss = require('xss'); var xss = require('xss');
var html = xss('<script>alert("xss");</script>'); var html = xss('<script>alert("xss");</script>');
console.log(html); console.log(html);
@@ -93,7 +92,7 @@ console.log(html);
Shim mode (reference file `test/test.html`): Shim mode (reference file `test/test.html`):
```HTML ```html
<script src="https://raw.github.com/leizongmin/js-xss/master/dist/xss.js"></script> <script src="https://raw.github.com/leizongmin/js-xss/master/dist/xss.js"></script>
<script> <script>
// apply function filterXSS in the same way // apply function filterXSS in the same way
@@ -104,7 +103,7 @@ alert(html);
AMD mode (reference file `test/test_amd.html`): AMD mode (reference file `test/test_amd.html`):
```HTML ```html
<script> <script>
require.config({ require.config({
baseUrl: './' baseUrl: './'
@@ -150,7 +149,7 @@ For more details, please run `$ xss -h` to see it.
When using the `xss()` function, the second parameter could be used to specify When using the `xss()` function, the second parameter could be used to specify
custom rules: custom rules:
```JavaScript ```javascript
options = {}; // Custom rules options = {}; // Custom rules
html = xss('<script>alert("xss");</script>', options); html = xss('<script>alert("xss");</script>', options);
``` ```
@@ -158,7 +157,7 @@ html = xss('<script>alert("xss");</script>', options);
To avoid passing `options` every time, you can also do it in a faster way by To avoid passing `options` every time, you can also do it in a faster way by
creating a `FilterXSS` instance: creating a `FilterXSS` instance:
```JavaScript ```javascript
options = {}; // Custom rules options = {}; // Custom rules
myxss = new xss.FilterXSS(options); myxss = new xss.FilterXSS(options);
// then apply myxss.process() // then apply myxss.process()
@@ -172,7 +171,7 @@ Details of parameters in `options` would be described below.
By specifying a `whiteList`, e.g. `{ 'tagName': [ 'attr-1', 'attr-2' ] }`. Tags By specifying a `whiteList`, e.g. `{ 'tagName': [ 'attr-1', 'attr-2' ] }`. Tags
and attributes not in the whitelist would be filter out. For example: and attributes not in the whitelist would be filter out. For example:
```JavaScript ```javascript
// only tag a and its attributes href, title, target are allowed // only tag a and its attributes href, title, target are allowed
var options = { var options = {
whiteList: { whiteList: {
@@ -191,7 +190,7 @@ For the default whitelist, please refer `xss.whiteList`.
By specifying the handler function with `onTag`: By specifying the handler function with `onTag`:
```JavaScript ```javascript
function onTag (tag, html, options) { function onTag (tag, html, options) {
// tag is the name of current tag, e.g. 'a' for tag <a> // tag is the name of current tag, e.g. 'a' for tag <a>
// html is the HTML of this tag, e.g. '<a>' for tag <a> // html is the HTML of this tag, e.g. '<a>' for tag <a>
@@ -211,7 +210,7 @@ function onTag (tag, html, options) {
By specifying the handler function with `onTagAttr`: By specifying the handler function with `onTagAttr`:
```JavaScript ```javascript
function onTagAttr (tag, name, value, isWhiteAttr) { function onTagAttr (tag, name, value, isWhiteAttr) {
// tag is the name of current tag, e.g. 'a' for tag <a> // tag is the name of current tag, e.g. 'a' for tag <a>
// name is the name of current attribute, e.g. 'href' for href="#" // name is the name of current attribute, e.g. 'href' for href="#"
@@ -227,7 +226,7 @@ function onTagAttr (tag, name, value, isWhiteAttr) {
By specifying the handler function with `onIgnoreTag`: By specifying the handler function with `onIgnoreTag`:
```JavaScript ```javascript
function onIgnoreTag (tag, html, options) { function onIgnoreTag (tag, html, options) {
// Parameters are the same with onTag // Parameters are the same with onTag
// If a string is returned, the tag would be replaced with the string // If a string is returned, the tag would be replaced with the string
@@ -240,7 +239,7 @@ function onIgnoreTag (tag, html, options) {
By specifying the handler function with `onIgnoreTagAttr`: By specifying the handler function with `onIgnoreTagAttr`:
```JavaScript ```javascript
function onIgnoreTagAttr (tag, name, value, isWhiteAttr) { function onIgnoreTagAttr (tag, name, value, isWhiteAttr) {
// Parameters are the same with onTagAttr // Parameters are the same with onTagAttr
// If a string is returned, the value would be replaced with this string // If a string is returned, the value would be replaced with this string
@@ -253,7 +252,7 @@ function onIgnoreTagAttr (tag, name, value, isWhiteAttr) {
By specifying the handler function with `escapeHtml`. Following is the default By specifying the handler function with `escapeHtml`. Following is the default
function **(Modification is not recommended)**: function **(Modification is not recommended)**:
```JavaScript ```javascript
function escapeHtml (html) { function escapeHtml (html) {
return html.replace(/</g, '&lt;').replace(/>/g, '&gt;'); return html.replace(/</g, '&lt;').replace(/>/g, '&gt;');
} }
@@ -263,7 +262,7 @@ function escapeHtml (html) {
By specifying the handler function with `safeAttrValue`: By specifying the handler function with `safeAttrValue`:
```JavaScript ```javascript
function safeAttrValue (tag, name, value) { function safeAttrValue (tag, name, value) {
// Parameters are the same with onTagAttr (without options) // Parameters are the same with onTagAttr (without options)
// Return the value as a string // Return the value as a string
@@ -283,13 +282,13 @@ Example:
If `stripIgnoreTag = true` is set, the following code: If `stripIgnoreTag = true` is set, the following code:
```HTML ```html
code:<script>alert(/xss/);</script> code:<script>alert(/xss/);</script>
``` ```
would output filtered: would output filtered:
```HTML ```html
code:alert(/xss/); code:alert(/xss/);
``` ```
@@ -305,13 +304,13 @@ Example:
If `stripIgnoreTagBody = ['script']` is set, the following code: If `stripIgnoreTagBody = ['script']` is set, the following code:
```HTML ```html
code:<script>alert(/xss/);</script> code:<script>alert(/xss/);</script>
``` ```
would output filtered: would output filtered:
```HTML ```html
code: code:
``` ```
@@ -326,13 +325,13 @@ Example:
If `allowCommentTag = false` is set, the following code: If `allowCommentTag = false` is set, the following code:
```HTML ```html
code:<!-- something --> END code:<!-- something --> END
``` ```
would output filtered: would output filtered:
```HTML ```html
code: END code: END
``` ```
@@ -341,7 +340,7 @@ code: END
### Allow attributes of whitelist tags start with `data-` ### Allow attributes of whitelist tags start with `data-`
```JavaScript ```javascript
var source = '<div a="1" b="2" data-a="3" data-b="4">hello</div>'; var source = '<div a="1" b="2" data-a="3" data-b="4">hello</div>';
var html = xss(source, { var html = xss(source, {
onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) { onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) {
@@ -365,7 +364,7 @@ convert to:
### Allow tags start with `x-` ### Allow tags start with `x-`
```JavaScript ```javascript
var source = '<x><x-1>he<x-2 checked></x-2>wwww</x-1><a>'; var source = '<x><x-1>he<x-2 checked></x-2>wwww</x-1><a>';
var html = xss(source, { var html = xss(source, {
onIgnoreTag: function (tag, html, options) { onIgnoreTag: function (tag, html, options) {
@@ -389,7 +388,7 @@ convert to:
### Parse images in HTML ### Parse images in HTML
```JavaScript ```javascript
var source = '<img src="img1">a<img src="img2">b<img src="img3">c<img src="img4">d'; var source = '<img src="img1">a<img src="img2">b<img src="img3">c<img src="img4">d';
var list = []; var list = [];
var html = xss(source, { var html = xss(source, {
@@ -416,7 +415,7 @@ img1, img2, img3, img4
### Filter out HTML tags (keeps only plain text) ### Filter out HTML tags (keeps only plain text)
```JavaScript ```javascript
var source = '<strong>hello</strong><script>alert(/xss/);</script>end'; var source = '<strong>hello</strong><script>alert(/xss/);</script>end';
var html = xss(source, { var html = xss(source, {
whiteList: [], // empty, means filter out all tags whiteList: [], // empty, means filter out all tags

View File

@@ -1,7 +1,6 @@
[![NPM version](https://badge.fury.io/js/xss.png)](http://badge.fury.io/js/xss) [![NPM version](https://badge.fury.io/js/xss.png)](http://badge.fury.io/js/xss)
[![Build Status](https://secure.travis-ci.org/leizongmin/js-xss.png?branch=master)](http://travis-ci.org/leizongmin/js-xss) [![Build Status](https://secure.travis-ci.org/leizongmin/js-xss.png?branch=master)](http://travis-ci.org/leizongmin/js-xss)
[![Dependencies Status](https://david-dm.org/leizongmin/js-xss.png)](https://david-dm.org/leizongmin/js-xss) [![Dependencies Status](https://david-dm.org/leizongmin/js-xss.png)](https://david-dm.org/leizongmin/js-xss)
[![testling badge](https://ci.testling.com/leizongmin/js-xss.png)](https://ci.testling.com/leizongmin/js-xss)
根据白名单过滤HTML(防止XSS攻击) 根据白名单过滤HTML(防止XSS攻击)
====== ======
@@ -76,7 +75,7 @@ $ bower install https://github.com/leizongmin/js-xss.git
### 在Node.js中使用 ### 在Node.js中使用
```JavaScript ```javascript
var xss = require('xss'); var xss = require('xss');
var html = xss('<script>alert("xss");</script>'); var html = xss('<script>alert("xss");</script>');
console.log(html); console.log(html);
@@ -86,7 +85,7 @@ console.log(html);
Shim模式参考文件 `test/test.html`: Shim模式参考文件 `test/test.html`:
```HTML ```html
<script src="https://raw.github.com/leizongmin/js-xss/master/dist/xss.js"></script> <script src="https://raw.github.com/leizongmin/js-xss/master/dist/xss.js"></script>
<script> <script>
// 使用函数名 filterXSS用法一样 // 使用函数名 filterXSS用法一样
@@ -97,7 +96,7 @@ alert(html);
AMD模式参考文件 `test/test_amd.html`: AMD模式参考文件 `test/test_amd.html`:
```HTML ```html
<script> <script>
require.config({ require.config({
baseUrl: './' baseUrl: './'
@@ -141,7 +140,7 @@ $ xss -t
在调用 `xss()` 函数进行过滤时,可通过第二个参数来设置自定义规则: 在调用 `xss()` 函数进行过滤时,可通过第二个参数来设置自定义规则:
```JavaScript ```javascript
options = {}; // 自定义规则 options = {}; // 自定义规则
html = xss('<script>alert("xss");</script>', options); html = xss('<script>alert("xss");</script>', options);
``` ```
@@ -163,7 +162,7 @@ html = myxss.process('<script>alert("xss");</script>');
通过 `whiteList` 来指定,格式为:`{'标签名': ['属性1', '属性2']}`。不在白名单上 通过 `whiteList` 来指定,格式为:`{'标签名': ['属性1', '属性2']}`。不在白名单上
的标签将被过滤,不在白名单上的属性也会被过滤。以下是示例: 的标签将被过滤,不在白名单上的属性也会被过滤。以下是示例:
```JavaScript ```javascript
// 只允许a标签该标签只允许href, title, target这三个属性 // 只允许a标签该标签只允许href, title, target这三个属性
var options = { var options = {
whiteList: { whiteList: {
@@ -182,7 +181,7 @@ var options = {
通过 `onTag` 来指定相应的处理函数。以下是详细说明: 通过 `onTag` 来指定相应的处理函数。以下是详细说明:
```JavaScript ```javascript
function onTag (tag, html, options) { function onTag (tag, html, options) {
// tag是当前的标签名称比如<a>标签则tag的值是'a' // tag是当前的标签名称比如<a>标签则tag的值是'a'
// html是该标签的HTML比如<a>标签则html的值是'<a>' // html是该标签的HTML比如<a>标签则html的值是'<a>'
@@ -202,7 +201,7 @@ function onTag (tag, html, options) {
通过 `onTagAttr` 来指定相应的处理函数。以下是详细说明: 通过 `onTagAttr` 来指定相应的处理函数。以下是详细说明:
```JavaScript ```javascript
function onTagAttr (tag, name, value, isWhiteAttr) { function onTagAttr (tag, name, value, isWhiteAttr) {
// tag是当前的标签名称比如<a>标签则tag的值是'a' // tag是当前的标签名称比如<a>标签则tag的值是'a'
// name是当前属性的名称比如href="#"则name的值是'href' // name是当前属性的名称比如href="#"则name的值是'href'
@@ -219,7 +218,7 @@ function onTagAttr (tag, name, value, isWhiteAttr) {
通过 `onIgnoreTag` 来指定相应的处理函数。以下是详细说明: 通过 `onIgnoreTag` 来指定相应的处理函数。以下是详细说明:
```JavaScript ```javascript
function onIgnoreTag (tag, html, options) { function onIgnoreTag (tag, html, options) {
// 参数说明与onTag相同 // 参数说明与onTag相同
// 如果返回一个字符串,则当前标签将被替换为该字符串 // 如果返回一个字符串,则当前标签将被替换为该字符串
@@ -231,7 +230,7 @@ function onIgnoreTag (tag, html, options) {
通过 `onIgnoreTagAttr` 来指定相应的处理函数。以下是详细说明: 通过 `onIgnoreTagAttr` 来指定相应的处理函数。以下是详细说明:
```JavaScript ```javascript
function onIgnoreTagAttr (tag, name, value, isWhiteAttr) { function onIgnoreTagAttr (tag, name, value, isWhiteAttr) {
// 参数说明与onTagAttr相同 // 参数说明与onTagAttr相同
// 如果返回一个字符串,则当前属性值将被替换为该字符串 // 如果返回一个字符串,则当前属性值将被替换为该字符串
@@ -243,7 +242,7 @@ function onIgnoreTagAttr (tag, name, value, isWhiteAttr) {
通过 `escapeHtml` 来指定相应的处理函数。以下是默认代码 **(不建议修改)** 通过 `escapeHtml` 来指定相应的处理函数。以下是默认代码 **(不建议修改)**
```JavaScript ```javascript
function escapeHtml (html) { function escapeHtml (html) {
return html.replace(/</g, '&lt;').replace(/>/g, '&gt;'); return html.replace(/</g, '&lt;').replace(/>/g, '&gt;');
} }
@@ -253,7 +252,7 @@ function escapeHtml (html) {
通过 `safeAttrValue` 来指定相应的处理函数。以下是详细说明: 通过 `safeAttrValue` 来指定相应的处理函数。以下是详细说明:
```JavaScript ```javascript
function safeAttrValue (tag, name, value) { function safeAttrValue (tag, name, value) {
// 参数说明与onTagAttr相同没有options参数 // 参数说明与onTagAttr相同没有options参数
// 返回一个字符串表示该属性值 // 返回一个字符串表示该属性值
@@ -273,13 +272,13 @@ function safeAttrValue (tag, name, value) {
当设置 `stripIgnoreTag = true`时,以下代码 当设置 `stripIgnoreTag = true`时,以下代码
```HTML ```html
code:<script>alert(/xss/);</script> code:<script>alert(/xss/);</script>
``` ```
过滤后将输出 过滤后将输出
```HTML ```html
code:alert(/xss/); code:alert(/xss/);
``` ```
@@ -295,13 +294,13 @@ code:alert(/xss/);
当设置 `stripIgnoreTagBody = ['script']`时,以下代码 当设置 `stripIgnoreTagBody = ['script']`时,以下代码
```HTML ```html
code:<script>alert(/xss/);</script> code:<script>alert(/xss/);</script>
``` ```
过滤后将输出 过滤后将输出
```HTML ```html
code: code:
``` ```
@@ -316,13 +315,13 @@ code:
当设置 `allowCommentTag = false` 时,以下代码 当设置 `allowCommentTag = false` 时,以下代码
```HTML ```html
code:<!-- something --> END code:<!-- something --> END
``` ```
过滤后将输出 过滤后将输出
```HTML ```html
code: END code: END
``` ```
@@ -331,7 +330,7 @@ code: END
### 允许标签以data-开头的属性 ### 允许标签以data-开头的属性
```JavaScript ```javascript
var source = '<div a="1" b="2" data-a="3" data-b="4">hello</div>'; var source = '<div a="1" b="2" data-a="3" data-b="4">hello</div>';
var html = xss(source, { var html = xss(source, {
onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) { onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) {
@@ -355,7 +354,7 @@ convert to:
### 允许名称以x-开头的标签 ### 允许名称以x-开头的标签
```JavaScript ```javascript
var source = '<x><x-1>he<x-2 checked></x-2>wwww</x-1><a>'; var source = '<x><x-1>he<x-2 checked></x-2>wwww</x-1><a>';
var html = xss(source, { var html = xss(source, {
onIgnoreTag: function (tag, html, options) { onIgnoreTag: function (tag, html, options) {
@@ -379,7 +378,7 @@ convert to:
### 分析HTML代码中的图片列表 ### 分析HTML代码中的图片列表
```JavaScript ```javascript
var source = '<img src="img1">a<img src="img2">b<img src="img3">c<img src="img4">d'; var source = '<img src="img1">a<img src="img2">b<img src="img3">c<img src="img4">d';
var list = []; var list = [];
var html = xss(source, { var html = xss(source, {
@@ -404,7 +403,7 @@ img1, img2, img3, img4
### 去除HTML标签只保留文本内容 ### 去除HTML标签只保留文本内容
```JavaScript ```javascript
var source = '<strong>hello</strong><script>alert(/xss/);</script>end'; var source = '<strong>hello</strong><script>alert(/xss/);</script>end';
var html = xss(source, { var html = xss(source, {
whiteList: [], // 白名单为空,表示过滤所有标签 whiteList: [], // 白名单为空,表示过滤所有标签