{"id":13491928,"url":"https://github.com/leizongmin/js-xss","last_synced_at":"2025-05-10T10:32:53.525Z","repository":{"id":4709527,"uuid":"5857265","full_name":"leizongmin/js-xss","owner":"leizongmin","description":"Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist","archived":false,"fork":false,"pushed_at":"2024-03-03T02:31:06.000Z","size":3705,"stargazers_count":5266,"open_issues_count":69,"forks_count":629,"subscribers_count":118,"default_branch":"master","last_synced_at":"2025-05-08T22:37:10.979Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://jsxss.com","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leizongmin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null},"funding":{"github":"leizongmin","patreon":null,"open_collective":"leizongmin","ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2012-09-18T14:05:07.000Z","updated_at":"2025-05-08T22:26:48.000Z","dependencies_parsed_at":"2024-03-03T03:33:21.883Z","dependency_job_id":null,"html_url":"https://github.com/leizongmin/js-xss","commit_stats":{"total_commits":382,"total_committers":38,"mean_commits":"10.052631578947368","dds":"0.15968586387434558","last_synced_commit":"8884b21308315915ca5456a8552ddc23366c8325"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leizongmin%2Fjs-xss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leizongmin%2Fjs-xss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leizongmin%2Fjs-xss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leizongmin%2Fjs-xss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leizongmin","download_url":"https://codeload.github.com/leizongmin/js-xss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166474,"owners_count":21864467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T19:01:01.625Z","updated_at":"2025-05-10T10:32:53.501Z","avatar_url":"https://github.com/leizongmin.png","language":"HTML","funding_links":["https://github.com/sponsors/leizongmin","https://opencollective.com/leizongmin"],"categories":["Tools","HTML","Web 后端","\u003ca id=\"43b0310ac54c147a62c545a2b0f4bce2\"\u003e\u003c/a\u003e辅助周边","Code","Security","HTML (177)","Security [🔝](#readme)","\u003ca id=\"569887799ee0148230cc5d7bf98e96d0\"\u003e\u003c/a\u003e未分类-Assist","安全性","41. 实用工具/其他插件"],"sub_categories":["Preventing","\u003ca id=\"569887799ee0148230cc5d7bf98e96d0\"\u003e\u003c/a\u003e未分类","library/repositories","Runner","\u003ca id=\"776c034543a65be69c061d1aafce3127\"\u003e\u003c/a\u003e新添加的","运行器","24.3 Web Sockets","运行器e2e测试"],"readme":"[![NPM version][npm-image]][npm-url]\n[![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)\n[![Test coverage][coveralls-image]][coveralls-url]\n[![David deps][david-image]][david-url]\n[![node version][node-image]][node-url]\n[![npm download][download-image]][download-url]\n[![npm license][license-image]][download-url]\n\n[npm-image]: https://img.shields.io/npm/v/xss.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/xss\n[coveralls-image]: https://img.shields.io/coveralls/leizongmin/js-xss.svg?style=flat-square\n[coveralls-url]: https://coveralls.io/r/leizongmin/js-xss?branch=master\n[david-image]: https://img.shields.io/david/leizongmin/js-xss.svg?style=flat-square\n[david-url]: https://david-dm.org/leizongmin/js-xss\n[node-image]: https://img.shields.io/badge/node.js-%3E=_0.10-green.svg?style=flat-square\n[node-url]: http://nodejs.org/download/\n[download-image]: https://img.shields.io/npm/dm/xss.svg?style=flat-square\n[download-url]: https://npmjs.org/package/xss\n[license-image]: https://img.shields.io/npm/l/xss.svg\n\n# Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist.\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/leizongmin/js-xss.svg)](https://greenkeeper.io/)\n\n![xss](https://nodei.co/npm/xss.png?downloads=true\u0026stars=true)\n\n---\n\n`xss` is a module used to filter input from users to prevent XSS attacks.\n([What is XSS attack?](http://en.wikipedia.org/wiki/Cross-site_scripting))\n\n**Project Homepage:** http://jsxss.com\n\n**Try Online:** http://jsxss.com/en/try.html\n\n**[中文版文档](https://github.com/leizongmin/js-xss/blob/master/README.zh.md)**\n\n---\n\n## Features\n\n- Specifies HTML tags and their attributes allowed with whitelist\n- Handle any tags or attributes using custom function.\n\n## Reference\n\n- [XSS Filter Evasion Cheat Sheet](https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet)\n- [Data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme)\n- [XSS with Data URI Scheme](http://hi.baidu.com/badzzzz/item/bdbafe83144619c199255f7b)\n\n## Benchmark (for references only)\n\n- the xss module: 22.53 MB/s\n- `xss()` function from module `validator@0.3.7`: 6.9 MB/s\n\nFor test code please refer to `benchmark` directory.\n\n## They are using xss module\n\n- **nodeclub** - A Node.js bbs using MongoDB - https://github.com/cnodejs/nodeclub\n- **cnpmjs.org** - Private npm registry and web for Enterprise - https://github.com/cnpm/cnpmjs.org\n- **cocalc.com** - Collaborative Calculation and Data Science - https://cocalc.com\n\n## Install\n\n### NPM\n\n```bash\nnpm install xss\n```\n\n### Bower\n\n```bash\nbower install xss\n```\n\nOr\n\n```bash\nbower install https://github.com/leizongmin/js-xss.git\n```\n\n## Usages\n\n### On Node.js\n\n```javascript\nvar xss = require(\"xss\");\nvar html = xss('\u003cscript\u003ealert(\"xss\");\u003c/script\u003e');\nconsole.log(html);\n```\n\n### On Browser\n\nShim mode (reference file `test/test.html`):\n\n```html\n\u003cscript src=\"https://rawgit.com/leizongmin/js-xss/master/dist/xss.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // apply function filterXSS in the same way\n  var html = filterXSS('\u003cscript\u003ealert(\"xss\");\u003c/scr' + \"ipt\u003e\");\n  alert(html);\n\u003c/script\u003e\n```\n\nAMD mode - shim:\n\n```html\n\u003cscript\u003e\n  require.config({\n    baseUrl: \"./\",\n    paths: {\n      xss: \"https://rawgit.com/leizongmin/js-xss/master/dist/xss.js\",\n    },\n    shim: {\n      xss: { exports: \"filterXSS\" },\n    },\n  });\n  require([\"xss\"], function (xss) {\n    var html = xss('\u003cscript\u003ealert(\"xss\");\u003c/scr' + \"ipt\u003e\");\n    alert(html);\n  });\n\u003c/script\u003e\n```\n\n**Notes: please don't use the URL https://rawgit.com/leizongmin/js-xss/master/dist/xss.js in production environment.**\n\n## Command Line Tool\n\n### Process File\n\nYou can use the xss command line tool to process a file. Usage:\n\n```bash\nxss -i \u003cinput_file\u003e -o \u003coutput_file\u003e\n```\n\nExample:\n\n```bash\nxss -i origin.html -o target.html\n```\n\n### Active Test\n\nRun the following command, them you can type HTML\ncode in the command-line, and check the filtered output:\n\n```bash\nxss -t\n```\n\nFor more details, please run `$ xss -h` to see it.\n\n## Custom filter rules\n\nWhen using the `xss()` function, the second parameter could be used to specify\ncustom rules:\n\n```javascript\noptions = {}; // Custom rules\nhtml = xss('\u003cscript\u003ealert(\"xss\");\u003c/script\u003e', options);\n```\n\nTo avoid passing `options` every time, you can also do it in a faster way by\ncreating a `FilterXSS` instance:\n\n```javascript\noptions = {}; // Custom rules\nmyxss = new xss.FilterXSS(options);\n// then apply myxss.process()\nhtml = myxss.process('\u003cscript\u003ealert(\"xss\");\u003c/script\u003e');\n```\n\nDetails of parameters in `options` would be described below.\n\n### Whitelist\n\nBy specifying a `whiteList`, e.g. `{ 'tagName': [ 'attr-1', 'attr-2' ] }`. Tags\nand attributes not in the whitelist would be filter out. For example:\n\n```javascript\n// only tag a and its attributes href, title, target are allowed\nvar options = {\n  whiteList: {\n    a: [\"href\", \"title\", \"target\"],\n  },\n};\n// With the configuration specified above, the following HTML:\n// \u003ca href=\"#\" onclick=\"hello()\"\u003e\u003ci\u003eHello\u003c/i\u003e\u003c/a\u003e\n// would become:\n// \u003ca href=\"#\"\u003e\u0026lt;i\u0026gt;Hello\u0026lt;/i\u0026gt;\u003c/a\u003e\n```\n\nFor the default whitelist, please refer `xss.whiteList`.\n\n`allowList` is also supported, and has the same function as `whiteList`.\n\n### Customize the handler function for matched tags\n\nBy specifying the handler function with `onTag`:\n\n```javascript\nfunction onTag(tag, html, options) {\n  // tag is the name of current tag, e.g. 'a' for tag \u003ca\u003e\n  // html is the HTML of this tag, e.g. '\u003ca\u003e' for tag \u003ca\u003e\n  // options is some addition informations:\n  //   isWhite    boolean, whether the tag is in whitelist\n  //   isClosing  boolean, whether the tag is a closing tag, e.g. true for \u003c/a\u003e\n  //   position        integer, the position of the tag in output result\n  //   sourcePosition  integer, the position of the tag in input HTML source\n  // If a string is returned, the current tag would be replaced with the string\n  // If return nothing, the default measure would be taken:\n  //   If in whitelist: filter attributes using onTagAttr, as described below\n  //   If not in whitelist: handle by onIgnoreTag, as described below\n}\n```\n\n### Customize the handler function for attributes of matched tags\n\nBy specifying the handler function with `onTagAttr`:\n\n```javascript\nfunction onTagAttr(tag, name, value, isWhiteAttr) {\n  // tag is the name of current tag, e.g. 'a' for tag \u003ca\u003e\n  // name is the name of current attribute, e.g. 'href' for href=\"#\"\n  // isWhiteAttr whether the attribute is in whitelist\n  // If a string is returned, the attribute would be replaced with the string\n  // If return nothing, the default measure would be taken:\n  //   If in whitelist: filter the value using safeAttrValue as described below\n  //   If not in whitelist: handle by onIgnoreTagAttr, as described below\n}\n```\n\n### Customize the handler function for tags not in the whitelist\n\nBy specifying the handler function with `onIgnoreTag`:\n\n```javascript\nfunction onIgnoreTag(tag, html, options) {\n  // Parameters are the same with onTag\n  // If a string is returned, the tag would be replaced with the string\n  // If return nothing, the default measure would be taken (specifies using\n  // escape, as described below)\n}\n```\n\n### Customize the handler function for attributes not in the whitelist\n\nBy specifying the handler function with `onIgnoreTagAttr`:\n\n```javascript\nfunction onIgnoreTagAttr(tag, name, value, isWhiteAttr) {\n  // Parameters are the same with onTagAttr\n  // If a string is returned, the value would be replaced with this string\n  // If return nothing, then keep default (remove the attribute)\n}\n```\n\n### Customize escaping function for HTML\n\nBy specifying the handler function with `escapeHtml`. Following is the default\nfunction **(Modification is not recommended)**:\n\n```javascript\nfunction escapeHtml(html) {\n  return html.replace(/\u003c/g, \"\u0026lt;\").replace(/\u003e/g, \"\u0026gt;\");\n}\n```\n\n### Customize escaping function for value of attributes\n\nBy specifying the handler function with `safeAttrValue`:\n\n```javascript\nfunction safeAttrValue(tag, name, value) {\n  // Parameters are the same with onTagAttr (without options)\n  // Return the value as a string\n}\n```\n\n### Customize output attribute value syntax for HTML\n\nBy specifying a `singleQuotedAttributeValue`. Use `true` for `'`. Otherwise default `\"` will be used\n\n```javascript\nvar options = {\n  singleQuotedAttributeValue: true,\n};\n// With the configuration specified above, the following HTML:\n// \u003ca href=\"#\"\u003eHello\u003c/a\u003e\n// would become:\n// \u003ca href='#'\u003eHello\u003c/a\u003e\n```\n\n### Customize CSS filter\n\nIf you allow the attribute `style`, the value will be processed by [cssfilter](https://github.com/leizongmin/js-css-filter) module. The cssfilter module includes a default css whitelist. You can specify the options for cssfilter module like this:\n\n```javascript\nmyxss = new xss.FilterXSS({\n  css: {\n    whiteList: {\n      position: /^fixed|relative$/,\n      top: true,\n      left: true,\n    },\n  },\n});\nhtml = myxss.process('\u003cscript\u003ealert(\"xss\");\u003c/script\u003e');\n```\n\nIf you don't want to filter out the `style` content, just specify `false` to the `css` option:\n\n```javascript\nmyxss = new xss.FilterXSS({\n  css: false,\n});\n```\n\nFor more help, please see https://github.com/leizongmin/js-css-filter\n\n### Quick Start\n\n#### Filter out tags not in the whitelist\n\nBy using `stripIgnoreTag` parameter:\n\n- `true` filter out tags not in the whitelist\n- `false`: by default: escape the tag using configured `escape` function\n\nExample:\n\nIf `stripIgnoreTag = true` is set, the following code:\n\n```html\ncode:\n\u003cscript\u003e\n  alert(/xss/);\n\u003c/script\u003e\n```\n\nwould output filtered:\n\n```html\ncode:alert(/xss/);\n```\n\n#### Filter out tags and tag bodies not in the whitelist\n\nBy using `stripIgnoreTagBody` parameter:\n\n- `false|null|undefined` by default: do nothing\n- `'*'|true`: filter out all tags not in the whitelist\n- `['tag1', 'tag2']`: filter out only specified tags not in the whitelist\n\nExample:\n\nIf `stripIgnoreTagBody = ['script']` is set, the following code:\n\n```html\ncode:\n\u003cscript\u003e\n  alert(/xss/);\n\u003c/script\u003e\n```\n\nwould output filtered:\n\n```html\ncode:\n```\n\n#### Filter out HTML comments\n\nBy using `allowCommentTag` parameter:\n\n- `true`: do nothing\n- `false` by default: filter out HTML comments\n\nExample:\n\nIf `allowCommentTag = false` is set, the following code:\n\n```html\ncode:\u003c!-- something --\u003e\nEND\n```\n\nwould output filtered:\n\n```html\ncode: END\n```\n\n## Examples\n\n### Allow attributes of whitelist tags start with `data-`\n\n```javascript\nvar source = '\u003cdiv a=\"1\" b=\"2\" data-a=\"3\" data-b=\"4\"\u003ehello\u003c/div\u003e';\nvar html = xss(source, {\n  onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) {\n    if (name.substr(0, 5) === \"data-\") {\n      // escape its value using built-in escapeAttrValue function\n      return name + '=\"' + xss.escapeAttrValue(value) + '\"';\n    }\n  },\n});\n\nconsole.log(\"%s\\nconvert to:\\n%s\", source, html);\n```\n\nResult:\n\n```html\n\u003cdiv a=\"1\" b=\"2\" data-a=\"3\" data-b=\"4\"\u003ehello\u003c/div\u003e\nconvert to:\n\u003cdiv data-a=\"3\" data-b=\"4\"\u003ehello\u003c/div\u003e\n```\n\n### Allow tags start with `x-`\n\n```javascript\nvar source = \"\u003cx\u003e\u003cx-1\u003ehe\u003cx-2 checked\u003e\u003c/x-2\u003ewwww\u003c/x-1\u003e\u003ca\u003e\";\nvar html = xss(source, {\n  onIgnoreTag: function (tag, html, options) {\n    if (tag.substr(0, 2) === \"x-\") {\n      // do not filter its attributes\n      return html;\n    }\n  },\n});\n\nconsole.log(\"%s\\nconvert to:\\n%s\", source, html);\n```\n\nResult:\n\n```html\n\u003cx\n  \u003e\u003cx-1\u003ehe\u003cx-2 checked\u003e\u003c/x-2\u003ewwww\u003c/x-1\n  \u003e\u003ca\u003e\n    convert to: \u0026lt;x\u0026gt;\u003cx-1\u003ehe\u003cx-2 checked\u003e\u003c/x-2\u003ewwww\u003c/x-1\u003e\u003ca\u003e\u003c/a\u003e\u003c/a\n\u003e\u003c/x\u003e\n```\n\n### Parse images in HTML\n\n```javascript\nvar source =\n  '\u003cimg src=\"img1\"\u003ea\u003cimg src=\"img2\"\u003eb\u003cimg src=\"img3\"\u003ec\u003cimg src=\"img4\"\u003ed';\nvar list = [];\nvar html = xss(source, {\n  onTagAttr: function (tag, name, value, isWhiteAttr) {\n    if (tag === \"img\" \u0026\u0026 name === \"src\") {\n      // Use the built-in friendlyAttrValue function to escape attribute\n      // values. It supports converting entity tags such as \u0026lt; to printable\n      // characters such as \u003c\n      list.push(xss.friendlyAttrValue(value));\n    }\n    // Return nothing, means keep the default handling measure\n  },\n});\n\nconsole.log(\"image list:\\n%s\", list.join(\", \"));\n```\n\nResult:\n\n```html\nimage list: img1, img2, img3, img4\n```\n\n### Filter out HTML tags (keeps only plain text)\n\n```javascript\nvar source = \"\u003cstrong\u003ehello\u003c/strong\u003e\u003cscript\u003ealert(/xss/);\u003c/script\u003eend\";\nvar html = xss(source, {\n  whiteList: {}, // empty, means filter out all tags\n  stripIgnoreTag: true, // filter out all HTML not in the whitelist\n  stripIgnoreTagBody: [\"script\"], // the script tag is a special case, we need\n  // to filter out its content\n});\n\nconsole.log(\"text: %s\", html);\n```\n\nResult:\n\n```html\ntext: helloend\n```\n\n## License\n\n```text\nCopyright (c) 2012-2018 Zongmin Lei(雷宗民) \u003cleizongmin@gmail.com\u003e\nhttp://ucdok.com\n\nThe MIT License\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\nNONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE\nLIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION\nOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleizongmin%2Fjs-xss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleizongmin%2Fjs-xss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleizongmin%2Fjs-xss/lists"}