https://github.com/ui/django-html_sanitizer

A set of HTML input sanitization or cleaning utilities for django models, forms and templates
https://github.com/ui/django-html_sanitizer

Last synced: about 1 month ago
JSON representation

A set of HTML input sanitization or cleaning utilities for django models, forms and templates

• Host: GitHub
• URL: https://github.com/ui/django-html_sanitizer
• Owner: ui
• License: mit
• Created: 2012-03-29T09:32:13.000Z (about 12 years ago)
• Default Branch: master
• Last Pushed: 2022-08-23T11:36:05.000Z (almost 2 years ago)
• Last Synced: 2024-05-03T00:56:23.825Z (about 2 months ago)
• Language: Python
• Homepage:
• Size: 30.3 KB
• Stars: 64
• Watchers: 8
• Forks: 25
• Open Issues: 8
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE.txt

Lists

• awesome-django-security - Django HTML Sanitizer
• awesome-django-security - Django HTML Sanitizer

README

        
=====================

Django HTML Sanitizer

=====================

Django HTML Sanitizer provides a set of utilities to easily sanitize/escape/clean

HTML inputs in django. This app is built on top of `bleach `_,

the excellent Python HTML sanitizer.

Dependencies

============

- `django `_: http://djangoproject.com/

- `bleach `_: http://github.com/jsocol/bleach

Installation

============

You'll first need to install the package (or download manually from

`pypi `_)::

    

    pip install django-html_sanitizer

And then add ``sanitizer`` to your INSTALLED_APPS in django's ``settings.py``::

    

    INSTALLED_APPS = (

        # other apps

        "sanitizer",

    )

Model Usage

===========

Similar to bleach, django sanitizer is a whitelist (only allows specified tags 

and attributes) based HTML sanitizer. Django sanitizer provides two model fields

that automatically sanitizes text values; ``SanitizedCharField`` and 

``SanitizedTextField``.

These fields accept extra arguments:

* allowed_tags: a list of allowed HTML tags

* allowed_attributes: a list of allowed HTML attributes, or a dictionary of

  tag keys with atttribute list for each key

* allowed_styles: a list of allowed styles if "style" is one of the allowed 

  attributes

* strip: a boolean indicating whether offending tags/attributes should be escaped or stripped

Here's how to use it in django models::

    

    from django.db import models

    from sanitizer.models import SanitizedCharField, SanitizedTextField

    class MyModel(models.Model):

        # Allow only , 
,  tags and "href" and "src" attributes

        foo = SanitizedCharField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes=['href', 'src'], strip=False)

        bar = SanitizedTextField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes=['href', 'src'], strip=False)

        foo2 = SanitizedCharField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes={'img':['src', 'style']}, 

                                 allowed_styles=['width', 'height'], strip=False)


Form Usage

==========

Using django HTML sanitizer in django forms is very similar to model usage::

    

    from django import forms

    from sanitizer.forms import SanitizedCharField

    class MyForm(forms.Form):

        # Allow only , 
,  tags and "href" and "src" attributes

        foo = SanitizedCharField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes=['href', 'src'], strip=False)

        bar = SanitizedCharField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes=['href', 'src'], strip=False, widget=forms.Textarea)

        foo2 = SanitizedCharField(max_length=255, allowed_tags=['a', 'p', 'img'], 

                                 allowed_attributes={'img':['src', 'style']}, 

                                 allowed_styles=['width', 'height'], strip=False)


Template Usage

==============

Django sanitizer provides a few differents ways of cleaning HTML in templates.

``escape_html`` Template Tag

----------------------------

Example usage::

    

    {% load sanitizer %}

    {% escape_html post.content "a, p, img" "href, src, style" "width"%}

Assuming ``post.content`` contains the string

'Examplealert("x")', the above tag will

output::

    'Example<script>alert("x")</script>'

On django 1.4 you could also use keyword arguments::

    {% escape_html 'bar' allowed_tags="a,img" allowed_attributes="href,src" allowed_styles="width" %}

``strip_html`` Template Tag

---------------------------

Example usage::

    

    {% load sanitizer %}

    {% strip_html post.content "a, p, img" "href, src" %}

If ``post.content`` contains the string

'Examplealert("x")', this will give you::

    'Examplealert("x")'

``escape_html`` Filter

----------------------

Escapes HTML tags from string based on settings. To use this filter you need to

put these variables on settings.py:

* ``SANITIZER_ALLOWED_TAGS`` - a list of allowed tags (defaults to an empty list)

* ``SANITIZER_ALLOWED_ATTRIBUTES`` - a list of allowed attributes (defaults to an empty list)

* ``SANITIZER_ALLOWED_STYLES`` - a list of allowed styles if the style attribute is set (defaults to an empty list)

For example if we have ``SANITIZER_ALLOWED_TAGS = ['a']``, 

``SANITIZER_ALLOWED_ATTRIBUTES = ['href']``, 

``SANITIZER_ALLOWED_STYLES = ['width']`` in settings.py, doing::

    

    {% load sanitizer %}

    {{ post.content|escape_html }}

If ``post.content`` contains the string

'Examplealert("x")', it will give you::

    'Example<script>alert("x")</script>'

``strip_html`` Filter

---------------------

Similar to ``escape_html`` filter, except it strips out offending HTML tags.

For example if we have ``SANITIZER_ALLOWED_TAGS = ['a']``, 

``SANITIZER_ALLOWED_ATTRIBUTES = ['href']`` in settings.py, doing::

    

    {% load sanitizer %}

    {{ post.content|strip_html }}

If ``post.content`` contains the string

'Examplealert("x")', we will get::

    'Examplealert("x")'

Changelog

=========

Version 0.1.5

-------------

* Fixes for smart_unicode and basestring (python 3.x support)

Version 0.1.4

-------------

* ``CharField``, ``TextField``, ``strip_html`` and ``escape_html`` now support

  ``allowed_styles`` (thanks `cltrudeau `_, 

* Added an example of template tag usage using kwargs now that Django 1.4 is out

Version 0.1.2

-------------

* ``allowed_tags`` and ``allowed_attributes`` in CharField and TextField now default to []