Overview↑

XSSFilter is a module for filtering out unsafe tags from (X)HTML. To avoid having second-guessing how different clients handle strange HTML input, the filter assumes that the input is subset of valid XML and returns nil if the input doesn't parse. If the input does parse, we then traverse the tree and check each element and its attributes against a configuration table, replacing anything that's not allowed with a message. There is a default configuration table that shoots for a balance between security and features, but the client can either supply their own or modify the default.

Installation↑

XSSFilter consists of a single module file (colors.lua). Here is a list of recent releases:

It installs like any other single-file Lua module: just put it somewhere in your Lua path.

You can also install XSSFilter as a LuaRock from the repository at http://sputnik.freewisdom.org/rocks/earth/:

luarocks install --from http://sputnik.freewisdom.org/rocks/earth xssfilter

Using XSSFilter↑

Basic Usage

require("xssfilter")
local xss_filter = xssfilter.new()

local html, message = xss_filter:filter(my_unsafe_html)
if html then
   return html
elseif message then
   return "<pre>"..message.."</pre>"
end

Advanced Usage

XSSFilter two table to decide what tags to allow and what tags to remove. Those tables can be parsed as first and second parameter to new() and default to xssfilter.ALLOWEDTAGS and xssfilter.GENERICATTRIBUTES respectively.

The first table allows two types of entries:

  1. Simply entering the name of the tag as string, allows this tag to be used but without any attributes, except for those attributes listed in GENERIC_ATTRIBUTES and allowed for all tags.
  2. Alternatively, the tag can be entered as a table, keyed with the tag name, which can specify what attributes the tag can have, specifying for each attribute the pattern with which its values must start (use "." to allow any values).
    Additionally, _test can be set to a function that does a more complex evaluation of whether the tag's attributes should be allowed.

The second table specifies which attributes are allowed for all tags.

So, to allow just tags "foo" and "bar", we can do this:

local xss_filter = xssfilter.new({"foo", "bar"})

Or, to allow "foo" attribute for any tag, provided that its value starts with "bar":

local xss_filter = xssfilter.new(nil, {foo = "bar"})

We can also modify "allowed_tags" after creating the filter:

local xss_filter = xssfilter.new()
xss_filter.allowed_tags.a.href="." -- allows href attribute of <a> to take any value
xss_filter.allowed_tags.a.onClick="." -- allows <a> tags to have "onClick" attribute, with any value

Or, we could restrict it instead:

xss_filter.allowed_tags.a.href="http://mydomain" -- allows only links to files on this site.

Contact↑

Please contact Yuri Takhteyev (yuri -at- freewisdom.org) with any questions.

LuaDoc↑

xssfilter

Filters XHTML removing all tags that are not explicitly allowed. The function parse_xml() is adapted from Roberto Ierusalmischy's collect() (see http://lua-users.org/wiki/LuaXml). (c) 2007, 2008 Yuri Takhteyev (yuri@freewisdom.org) License: MIT/X, see http://sputnik.freewisdom.org/en/License

XSSFilter:filter() Filters (X)HTML.
html:
An HTML string that must parse as valid XML if is appended to it on both sides.
Returns: A string with all but the allowed tags removed.
XSSFilter:get_replacement() Returns HTML to be used for replacing bad tags.
tag:
tag name.
message:
[optional] an explanation for why the tag was removed.
Returns: replacement HTML.
XSSFilter:init() Initializes the new instance of XSSFilter.
allowed_tags:
[optional] a table specifying which tags are allowed (defaults to ALLOWED_TAGS).
generic_attrs:
[optional] a table specifying generic attributes (defaults to GENERIC_ATTRIBUTES).
Returns:
find_match()
value:
Filters XHTML removing all tags that are not explicitly allowed. The function parse_xml() is adapted from Roberto Ierusalmischy's collect() (see http://lua-users.org/wiki/LuaXml). (c) 2007, 2008 Yuri Takhteyev (yuri@freewisdom.org) License: MIT/X, see http://sputnik.freewisdom.org/en/License
patterns:
Filters XHTML removing all tags that are not explicitly allowed. The function parse_xml() is adapted from Roberto Ierusalmischy's collect() (see http://lua-users.org/wiki/LuaXml). (c) 2007, 2008 Yuri Takhteyev (yuri@freewisdom.org) License: MIT/X, see http://sputnik.freewisdom.org/en/License
Returns:
new() Creates a new instance of XSSFilter.
allowed_tags:
[optional] a table specifying which tags are allowed (defaults to ALLOWED_TAGS).
generic_attrs:
[optional] a table specifying generic attributes (defaults to GENERIC_ATTRIBUTES).
Returns: a new instance of XSSFilter.
parse_attributes() An auxiliary function to parse tag's attributes
s:
Filters XHTML removing all tags that are not explicitly allowed. The function parse_xml() is adapted from Roberto Ierusalmischy's collect() (see http://lua-users.org/wiki/LuaXml). (c) 2007, 2008 Yuri Takhteyev (yuri@freewisdom.org) License: MIT/X, see http://sputnik.freewisdom.org/en/License
Returns:
parse_xml() Parses simple XML.
s:
Filters XHTML removing all tags that are not explicitly allowed. The function parse_xml() is adapted from Roberto Ierusalmischy's collect() (see http://lua-users.org/wiki/LuaXml). (c) 2007, 2008 Yuri Takhteyev (yuri@freewisdom.org) License: MIT/X, see http://sputnik.freewisdom.org/en/License
xml:
XML as a string.
Returns: A table representing the tags.
test()
Returns:

License↑

Copyright (c) 2008 Yuri Takhteyev

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.