A simple Django app that will give you a Cleaned HTML Field.
Project description
# Django CleanHtmlField
[![image](https://travis-ci.org/anexia-it/django-cleanhtmlfield.svg?branch=master)](https://travis-ci.org/anexia-it/django-cleanhtmlfield)
Django CleanHtmlField is a simple Django application (supporting Django
1.8, 1.11, 2.0 and 2.1) that defines an `HTMLField` that automatically
removes potentially malicious content. This app should work with Python
2.7+ and Python3.4+.
For instance, if you allow the user to freely input HTML Content, and
the user decides to inject a JavaScript snippet:
```html
<h1>Hello Friend</h1>
<script type="text/javascript">
steal_all_passwords();
</script>
<p>This is for you!</p>
```
`HTMLField` will filter this to
```html
<h1>Hello Friend</h1>
<p>This is for you!</p>
```
## Quick start
1. Download and install using `pip install` from [PyPi](https://pypi.python.org/pypi/django-cleanhtmlfield/):
```bash
pip install django-cleanhtmlfield
```
2. Create a field `HTMLField(strip_unsafe=True)` in your model:
```python
from django.db import models
from django_cleanhtmlfield.fields import HTMLField
class MyModel(models.Model)
some_content = HTMLField(strip_unsafe=True)
```
3. Don't forget to create and run migrations for changes on Django
models, e.g.:
```bash
python manage.py makemigrations
python manage.py migrate
```
## Requirements
For HTML content to be parsed and processed we depend on
`BeautifulSoup4` (this is installed as a dependency). As this is a
Django app, it obviously requires `Django` (though we expect this to be
already installed).
Optional: If you want a WYSIWYG Interface in your Admin Panel (or any
other Django Form), you need the `django-ckeditor` package.
![alt text](docs/ckeditor-wysiwyg.png "CKEditor")
## Field options
* `strip_unsafe` (Default: `False`) needs to be set to `True` to enable stripping of unsafe HTML content
* `widget_form_class` (Default: `None`) - allows overwriting the css form class for the widget (e.g., if you want to use `django-ckeditor`)
## Configuration options
The following Django Settings are available (see below for a full
example)
- `ACCEPTABLE_ELEMENTS` - tuple that contains all allowed HTML tags
(e.g., `'a', 'span', 'p', 'div', ...`)
- `ACCEPTABLE_ATTRIBUTES` - tuple that contains all allowed HTMl
attributes (e.g., `'alt', 'style', 'target', 'title',...`)
- `ACCEPTABLE_STYLES` - tuple that contains all allowed CSS styles
(e.g., `'background-color', 'border-color', 'font-size', ...`)
- `REMOVE_WITH_CONTENT` - tuple that contains potentially malicious
HTML tags that will automatically be removed (e.g., `'script',
'object', ...`)
Example:
```python
ACCEPTABLE_ELEMENTS = (
'a', 'abbr', 'acronym', 'address', 'area', 'aria-label', 'b', 'big',
'blockquote', 'br', 'button', 'caption', 'center', 'cite', 'code', 'col',
'colgroup', 'dd', 'del', 'dfn', 'dir', 'div', 'dl', 'dt', 'em',
'font', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img',
'ins', 'kbd', 'label', 'legend', 'li', 'map', 'menu', 'ol',
'p', 'pre', 'q', 's', 'samp', 'small', 'span', 'strike',
'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th',
'thead', 'tr', 'tt', 'u', 'ul', 'var', 'iframe', 'section', 'article',
)
ACCEPTABLE_ATTRIBUTES = (
'abbr', 'accept', 'accesskey',
'action', 'align', 'alt', 'axis', 'border', 'cellpadding', 'cellspacing',
'char', 'charoff', 'charset', 'checked', 'cite', 'class', 'clear', 'cols',
'colspan', 'color', 'compact', 'coords', 'data-mlang', 'data-equation', 'datetime', 'dir',
'enctype', 'for', 'headers', 'height', 'href', 'hreflang', 'hspace',
'id', 'ismap', 'label', 'lang', 'longdesc', 'maxlength', 'method',
'multiple', 'name', 'nohref', 'noshade', 'nowrap', 'prompt',
'rel', 'rev', 'rows', 'rowspan', 'role', 'rules', 'scope', 'shape', 'size', 'style',
'span', 'src', 'start', 'summary', 'tabindex', 'target', 'title', 'type',
'usemap', 'valign', 'value', 'vspace', 'width',
)
ACCEPTABLE_STYLES = (
'background-color', 'background', 'background-image', 'background-position', 'background-size', 'background-repeat',
'background-attachment', 'background-origin', 'background-clip',
'font-family', 'font-size', 'font-weight', 'font-style', 'color',
'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height', 'line-height',
'text-decoration', 'text-transform', 'text-align', 'border', 'border-style', 'border-width',
'border-top', 'border-bottom', 'border-left', 'border-right', 'border-top-style',
'border-bottom-style', 'border-left-style', 'border-right-style', 'border-top-width',
'border-bottom-width', 'border-left-width', 'border-right-width',
'border-color',
'border-top-color', 'border-bottom-color', 'border-left-color', 'border-spacing', 'border-collapse',
'border-right-color',
'border-radius',
'vertical-align', 'clear', 'float',
'margin', 'margin-left', 'margin-right', 'margin-top', 'margin-bottom',
'outline',
'padding', 'padding-left', 'padding-right', 'padding-top', 'padding-bottom',
)
REMOVE_WITH_CONTENT = ('script', 'object', 'embed', 'style', 'form', )
```
# Compatibility with Django REST Framework
If you are using Django Rest Framework you need to add the following
code to register a serializer/field handler:
```python
from django.utils.translation import ugettext_lazy as _
from rest_framework.serializers import ModelSerializer
from django_cleanhtmlfield.fields import HTMLField
from django_cleanhtmlfield.helpers import clean_html
class RestHtmlField(fields.CharField):
default_error_messages = {
'invalid': _('"{input}" is not a valid html.')
}
default_empty_html = False
initial = False
def __init__(self, **kwargs):
super(HtmlField, self).__init__(**kwargs)
def to_internal_value(self, data):
return clean_html(data, strip_unsafe=True)
ModelSerializer.serializer_field_mapping[HTMLField] = RestHtmlField
```
# Changelog
## 1.0.1
- Renamed `restricted` field option to `custom_css_class`
- Updated docs/readme
## 1.0
- Initial Release
# License
[MIT License](LICENSE)
# Development and Tests
The test app is located in the `tests` subfolder. Please run tests
against all Django and Python versions (e.g., using `tox` - see
`tox.ini`).
[![image](https://travis-ci.org/anexia-it/django-cleanhtmlfield.svg?branch=master)](https://travis-ci.org/anexia-it/django-cleanhtmlfield)
Django CleanHtmlField is a simple Django application (supporting Django
1.8, 1.11, 2.0 and 2.1) that defines an `HTMLField` that automatically
removes potentially malicious content. This app should work with Python
2.7+ and Python3.4+.
For instance, if you allow the user to freely input HTML Content, and
the user decides to inject a JavaScript snippet:
```html
<h1>Hello Friend</h1>
<script type="text/javascript">
steal_all_passwords();
</script>
<p>This is for you!</p>
```
`HTMLField` will filter this to
```html
<h1>Hello Friend</h1>
<p>This is for you!</p>
```
## Quick start
1. Download and install using `pip install` from [PyPi](https://pypi.python.org/pypi/django-cleanhtmlfield/):
```bash
pip install django-cleanhtmlfield
```
2. Create a field `HTMLField(strip_unsafe=True)` in your model:
```python
from django.db import models
from django_cleanhtmlfield.fields import HTMLField
class MyModel(models.Model)
some_content = HTMLField(strip_unsafe=True)
```
3. Don't forget to create and run migrations for changes on Django
models, e.g.:
```bash
python manage.py makemigrations
python manage.py migrate
```
## Requirements
For HTML content to be parsed and processed we depend on
`BeautifulSoup4` (this is installed as a dependency). As this is a
Django app, it obviously requires `Django` (though we expect this to be
already installed).
Optional: If you want a WYSIWYG Interface in your Admin Panel (or any
other Django Form), you need the `django-ckeditor` package.
![alt text](docs/ckeditor-wysiwyg.png "CKEditor")
## Field options
* `strip_unsafe` (Default: `False`) needs to be set to `True` to enable stripping of unsafe HTML content
* `widget_form_class` (Default: `None`) - allows overwriting the css form class for the widget (e.g., if you want to use `django-ckeditor`)
## Configuration options
The following Django Settings are available (see below for a full
example)
- `ACCEPTABLE_ELEMENTS` - tuple that contains all allowed HTML tags
(e.g., `'a', 'span', 'p', 'div', ...`)
- `ACCEPTABLE_ATTRIBUTES` - tuple that contains all allowed HTMl
attributes (e.g., `'alt', 'style', 'target', 'title',...`)
- `ACCEPTABLE_STYLES` - tuple that contains all allowed CSS styles
(e.g., `'background-color', 'border-color', 'font-size', ...`)
- `REMOVE_WITH_CONTENT` - tuple that contains potentially malicious
HTML tags that will automatically be removed (e.g., `'script',
'object', ...`)
Example:
```python
ACCEPTABLE_ELEMENTS = (
'a', 'abbr', 'acronym', 'address', 'area', 'aria-label', 'b', 'big',
'blockquote', 'br', 'button', 'caption', 'center', 'cite', 'code', 'col',
'colgroup', 'dd', 'del', 'dfn', 'dir', 'div', 'dl', 'dt', 'em',
'font', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img',
'ins', 'kbd', 'label', 'legend', 'li', 'map', 'menu', 'ol',
'p', 'pre', 'q', 's', 'samp', 'small', 'span', 'strike',
'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th',
'thead', 'tr', 'tt', 'u', 'ul', 'var', 'iframe', 'section', 'article',
)
ACCEPTABLE_ATTRIBUTES = (
'abbr', 'accept', 'accesskey',
'action', 'align', 'alt', 'axis', 'border', 'cellpadding', 'cellspacing',
'char', 'charoff', 'charset', 'checked', 'cite', 'class', 'clear', 'cols',
'colspan', 'color', 'compact', 'coords', 'data-mlang', 'data-equation', 'datetime', 'dir',
'enctype', 'for', 'headers', 'height', 'href', 'hreflang', 'hspace',
'id', 'ismap', 'label', 'lang', 'longdesc', 'maxlength', 'method',
'multiple', 'name', 'nohref', 'noshade', 'nowrap', 'prompt',
'rel', 'rev', 'rows', 'rowspan', 'role', 'rules', 'scope', 'shape', 'size', 'style',
'span', 'src', 'start', 'summary', 'tabindex', 'target', 'title', 'type',
'usemap', 'valign', 'value', 'vspace', 'width',
)
ACCEPTABLE_STYLES = (
'background-color', 'background', 'background-image', 'background-position', 'background-size', 'background-repeat',
'background-attachment', 'background-origin', 'background-clip',
'font-family', 'font-size', 'font-weight', 'font-style', 'color',
'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height', 'line-height',
'text-decoration', 'text-transform', 'text-align', 'border', 'border-style', 'border-width',
'border-top', 'border-bottom', 'border-left', 'border-right', 'border-top-style',
'border-bottom-style', 'border-left-style', 'border-right-style', 'border-top-width',
'border-bottom-width', 'border-left-width', 'border-right-width',
'border-color',
'border-top-color', 'border-bottom-color', 'border-left-color', 'border-spacing', 'border-collapse',
'border-right-color',
'border-radius',
'vertical-align', 'clear', 'float',
'margin', 'margin-left', 'margin-right', 'margin-top', 'margin-bottom',
'outline',
'padding', 'padding-left', 'padding-right', 'padding-top', 'padding-bottom',
)
REMOVE_WITH_CONTENT = ('script', 'object', 'embed', 'style', 'form', )
```
# Compatibility with Django REST Framework
If you are using Django Rest Framework you need to add the following
code to register a serializer/field handler:
```python
from django.utils.translation import ugettext_lazy as _
from rest_framework.serializers import ModelSerializer
from django_cleanhtmlfield.fields import HTMLField
from django_cleanhtmlfield.helpers import clean_html
class RestHtmlField(fields.CharField):
default_error_messages = {
'invalid': _('"{input}" is not a valid html.')
}
default_empty_html = False
initial = False
def __init__(self, **kwargs):
super(HtmlField, self).__init__(**kwargs)
def to_internal_value(self, data):
return clean_html(data, strip_unsafe=True)
ModelSerializer.serializer_field_mapping[HTMLField] = RestHtmlField
```
# Changelog
## 1.0.1
- Renamed `restricted` field option to `custom_css_class`
- Updated docs/readme
## 1.0
- Initial Release
# License
[MIT License](LICENSE)
# Development and Tests
The test app is located in the `tests` subfolder. Please run tests
against all Django and Python versions (e.g., using `tox` - see
`tox.ini`).
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Close
Hashes for django-cleanhtmlfield-1.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f33cdc3613f200817809115704dad1d7b40ed23de0df1e9757f76944e2c14a43 |
|
MD5 | 81088a4e40f6267cd71e822133de0a12 |
|
BLAKE2b-256 | 88881f740a984a91415680a029606db65a28cfc7dabe517e94bf4da16e14c893 |