django-xss-cleaner

django-xss-cleaner is a bleach-based Django XSSFilter toolkit that implements whitelist XSS filtering for GET and POST request parameters. The package ships with a set of built-in whitelisted HTML tags and attribute settings, and also supports custom extensions. Project address, https://github.com/shaowenchen/django-xss-cleaner

1. Installing and Configuring settings.py

Add the middleware xss_cleaner.middlewares.CleanXssMiddleware to settings

1
2
3
4
MIDDLEWARE_CLASSES = (
  'xss_cleaner.middlewares.CleanXssMiddleware',
  ...
)

It is recommended to place CleanXssMiddleware as early as possible, preferably first. This ensures that all data the backend receives has passed through the XSS filter, so that no XSS vector can be injected.

Configure the Clean XSS level [optional]

The default is ‘HIGHT’; available options: [‘LOW’, ‘HIGH’]

1
XSS_LEVEL = 'HIGH'

If set to ‘HIGHT’, the allowed tags and attributes are

1
2
3
4
5
6
7
{
    'tags': ['a', 'img', 'strong', 'p', 'div', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'table', 'ul', 'ol', 'tr', 'th', 'td', 'li'],
    'attributes': {'a': ['href', 'title', 'target'], 'img': ['width', 'height', 'src']},
    'styles': [],
    'strip': False,
    'strip_comments': False
}

If set to ‘LOW’, the allowed tags and attributes are

1
2
3
4
5
6
7
8
{
    'tags': ['a', 'img', 'br', 'strong', 'b', 'code', 'pre', 'p', 'div', 'em', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'table', 'ul', 'ol', 'tr', 'th', 'td', 'hr', 'li', 'u'],
    'attributes': {'a': ['href', 'title', 'target'], 'img': ['width', 'height', 'src', 'alt'],
              '*': ['class', 'style']},
    'styles': [],
    'strip': False,
    'strip_comments': False
}

The meaning of each parameter is described below.

Add a custom whitelist [optional]

Incrementally add new tags and attributes to the whitelist.

1
2
3
4
5
6
7
BLEACH_WHITE_LIST = {
    'tags': [],
    'attributes': {},
    'styles': [],
    'strip': False,
    'strip_comments': False
}

Parameter descriptions:

tags (list) – allowed tags; tags not in the whitelist are escaped
attributes (dict) – allowed attributes; attributes not in the whitelist are removed
styles (list) – allowed styles; styles not in the whitelist are removed
strip (bool) – whether to strip the escaped characters
strip_comments (bool) – whether to strip HTML comments

The tags, attributes, and styles in BLEACH_WHITE_LIST are added incrementally on top of the whitelist allowed by the Clean XSS level. If strip or strip_comments is set, it overrides the default setting.

Whether to print or log transfers [optional]

A switch is provided to make debugging easier by logging XSS Filter information:

1
BLEACH_SHOW = True

The default is True; available values: [True, False]

In local development, the transfer log is printed directly to the console. In production, it is printed as a warning log.

2. xss_cleaner Exemption Decorators

The xss_cleaner package provides two decorators for exempting requests from XSS Filter processing.

escape_clean, provides View-level exemption.

1
2
3
4
5
from xss_cleaner.decorators import escape_clean

    @escape_clean
    def home(request):
        pass

escape_clean_param, provides parameter-level exemption.

1
2
3
4
5
from xss_cleaner.decorators import escape_clean_param

    @escape_clean_param('param1', 'param2')
    def home(request):
        pass

3. xss_cleaner Processing Examples

The examples below use the default configuration: XSS_LEVEL = ‘HIGH’

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
转义非白名单标签
XSS Clean: Transfer  <b><i>an example</i></b>  To  &lt;b&gt;&lt;i&gt;an example&lt;/i&gt;&lt;/b&gt;

    删除非白名单样式
XSS Clean: Transfer  <p class="foo" style="color: red; font-weight: bold;">blah blah blah</p>  To  <p>blah blah blah</p>

    删除非白名单属性
XSS Clean: Transfer  <img click="de"  alt="an example" width=500>  To  <img width="500">

    自动补全，规范化 HTML
XSS Clean: Transfer  <a href=http://abc.com>my text; a b b  To  <a href="http://abc.com">my text; a b b</a>

The examples below use this configuration: XSS_LEVEL = ‘LOW’

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
转义非白名单标签
XSS Clean: Transfer  <b><i>an example</i></b>  To  <b>&lt;i&gt;an example&lt;/i&gt;</b>

删除非白名单样式
XSS Clean: Transfer  <p class="foo" style="color: red; font-weight: bold;">blah blah blah</p>  To  <p class="foo" style="">blah blah blah</p>

删除非白名单属性
XSS Clean: Transfer  <img click="de"  alt="an example" width=500>  To  <img alt="an example" width="500">

自动补全，规范化 HTML
XSS Clean: Transfer  <a href=http://abc.com>my text; a b b  To  <a href="http://abc.com">my text; a b b</a>

4. References

https://github.com/shaowenchen/django-xss-cleaner