xss is a module used to filter input from users to prevent XSS attacks.
(What is XSS attack?)
Project Homepage: http://jsxss.com
Try Online: http://jsxss.com/en/try.html
- Specifies HTML tags and their attributes allowed with whitelist
- Handle any tags or attributes using custom function.
- the xss module: 22.53 MB/s
xss()function from modulevalidator@0.3.7: 6.9 MB/s
For test code please refer to benchmark directory.
- 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
- cocalc.com - Collaborative Calculation and Data Science - https://cocalc.com
npm install xssbower install xssOr
bower install https://github.com/leizongmin/js-xss.gitvar xss = require("xss");
var html = xss('<script>alert("xss");</script>');
console.log(html);Shim mode (reference file test/test.html):
<script src="https://rawgit.com/leizongmin/js-xss/master/dist/xss.js"></script>
<script>
// apply function filterXSS in the same way
var html = filterXSS('<script>alert("xss");</scr' + "ipt>");
alert(html);
</script>AMD mode - shim:
<script>
require.config({
baseUrl: "./",
paths: {
xss: "https://rawgit.com/leizongmin/js-xss/master/dist/xss.js",
},
shim: {
xss: { exports: "filterXSS" },
},
});
require(["xss"], function (xss) {
var html = xss('<script>alert("xss");</scr' + "ipt>");
alert(html);
});
</script>Notes: please don't use the URL https://rawgit.com/leizongmin/js-xss/master/dist/xss.js in production environment.
You can use the xss command line tool to process a file. Usage:
xss -i <input_file> -o <output_file>Example:
xss -i origin.html -o target.htmlRun the following command, them you can type HTML code in the command-line, and check the filtered output:
xss -tFor more details, please run $ xss -h to see it.
When using the xss() function, the second parameter could be used to specify
custom rules:
options = {}; // Custom rules
html = xss('<script>alert("xss");</script>', options);To avoid passing options every time, you can also do it in a faster way by
creating a FilterXSS instance:
options = {}; // Custom rules
myxss = new xss.FilterXSS(options);
// then apply myxss.process()
html = myxss.process('<script>alert("xss");</script>');Details of parameters in options would be described below.
By specifying a whiteList, e.g. { 'tagName': [ 'attr-1', 'attr-2' ] }. Tags
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"],
},
};
// With the configuration specified above, the following HTML:
// <a href="#" ><i>Hello</i></a>
// would become:
// <a href="#"><i>Hello</i></a>For the default whitelist, please refer xss.whiteList.
allowList is also supported, and has the same function as whiteList.
By specifying the handler function with onTag:
function onTag(tag, html, options) {
// 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>
// options is some addition informations:
// isWhite boolean, whether the tag is in whitelist
// isClosing boolean, whether the tag is a closing tag, e.g. true for </a>
// position integer, the position of the tag in output result
// sourcePosition integer, the position of the tag in input HTML source
// If a string is returned, the current tag would be replaced with the string
// If return nothing, the default measure would be taken:
// If in whitelist: filter attributes using onTagAttr, as described below
// If not in whitelist: handle by onIgnoreTag, as described below
}By specifying the handler function with onTagAttr:
function onTagAttr(tag, name, value, isWhiteAttr) {
// 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="#"
// isWhiteAttr whether the attribute is in whitelist
// If a string is returned, the attribute would be replaced with the string
// If return nothing, the default measure would be taken:
// If in whitelist: filter the value using safeAttrValue as described below
// If not in whitelist: handle by onIgnoreTagAttr, as described below
}By specifying the handler function with onIgnoreTag:
function onIgnoreTag(tag, html, options) {
// Parameters are the same with onTag
// If a string is returned, the tag would be replaced with the string
// If return nothing, the default measure would be taken (specifies using
// escape, as described below)
}By specifying the handler function with onIgnoreTagAttr:
function onIgnoreTagAttr(tag, name, value, isWhiteAttr) {
// Parameters are the same with onTagAttr
// If a string is returned, the value would be replaced with this string
// If return nothing, then keep default (remove the attribute)
}By specifying the handler function with escapeHtml. Following is the default
function (Modification is not recommended):
function escapeHtml(html) {
return html.replace(/</g, "<").replace(/>/g, ">");
}By specifying the handler function with safeAttrValue:
function safeAttrValue(tag, name, value) {
// Parameters are the same with onTagAttr (without options)
// Return the value as a string
}By specifying a singleQuotedAttributeValue. Use true for '. Otherwise default " will be used
var options = {
singleQuotedAttributeValue: true,
};
// With the configuration specified above, the following HTML:
// <a href="#">Hello</a>
// would become:
// <a href='#'>Hello</a>If you allow the attribute style, the value will be processed by cssfilter module. The cssfilter module includes a default css whitelist. You can specify the options for cssfilter module like this:
myxss = new xss.FilterXSS({
css: {
whiteList: {
position: /^fixed|relative$/,
top: true,
left: true,
},
},
});
html = myxss.process('<script>alert("xss");</script>');If you don't want to filter out the style content, just specify false to the css option:
myxss = new xss.FilterXSS({
css: false,
});For more help, please see https://github.com/leizongmin/js-css-filter
By using stripIgnoreTag parameter:
truefilter out tags not in the whitelistfalse: by default: escape the tag using configuredescapefunction
Example:
If stripIgnoreTag = true is set, the following code:
code:
<script>
alert(/xss/);
</script>would output filtered:
code:alert(/xss/);By using stripIgnoreTagBody parameter:
false|null|undefinedby 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:
code:
<script>
alert(/xss/);
</script>would output filtered:
code:By using allowCommentTag parameter:
true: do nothingfalseby default: filter out HTML comments
Example:
If allowCommentTag = false is set, the following code:
code:<!-- something -->
ENDwould output filtered:
code: ENDvar source = '<div a="1" b="2" data-a="3" data-b="4">hello</div>';
var html = xss(source, {
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);Result:
<div a="1" b="2" data-a="3" data-b="4">hello</div>
convert to:
<div data-a="3" data-b="4">hello</div>var source = "<x><x-1>he<x-2 checked></x-2>wwww</x-1><a>";
var html = xss(source, {
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);Result:
<x
><x-1>he<x-2 checked></x-2>wwww</x-1
><a>
convert to: <x><x-1>he<x-2 checked></x-2>wwww</x-1><a></a></a
></x>var source =
'<img src="img1">a<img src="img2">b<img src="img3">c<img src="img4">d';
var list = [];
var html = xss(source, {
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
// characters such as <
list.push(xss.friendlyAttrValue(value));
}
// Return nothing, means keep the default handling measure
},
});
console.log("image list:\n%s", list.join(", "));Result:
image list: img1, img2, img3, img4var source = "<strong>hello</strong><script>alert(/xss/);</script>end";
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
// to filter out its content
});
console.log("text: %s", html);Result:
text: helloendCopyright (c) 2012-2018 Zongmin Lei(雷宗民) <leizongmin@gmail.com>
http://ucdok.com
The MIT License
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.