Metadata-Version: 2.1
Name: input-sanitizer
Version: 0.1.6
Summary: Sanitizes input data to prevent XSS i.e. cross site scripting attacks.
Home-page: UNKNOWN
Author: Akshay Ghatul
Author-email: akshay.ghatul@trigensoft.com
License: MIT
Platform: UNKNOWN
Description-Content-Type: text/x-rst

A tool for removing malicious content from input data before saving data into database.
It takes input containing HTML with XSS scripts and returns valid HTML in the output.
It is a wrapper around Python's `bleach`_ library to easily integrate with Django framework.


Setup
-----


1. Install ``input-sanitizer`` via ``pip``::
    
    pip install input-sanitizer

2. Add ``input-sanitizer`` to your ``INSTALLED_APPS``:

   .. code-block:: python

        INSTALLED_APPS = [
            # ...
            'input_sanitizer',
            # ...
        ]

3. Add default configurations for allowed tags, etc in ``settings.py``. These configurations are optional and will defaults to using the ``bleach`` defaults. Refer to `bleach`_ documentation for their use:

    .. code-block:: python

        # tags which are allowed
        BLEACH_ALLOWED_TAGS = ["div", "section", "a", "i"]

        # remove all tags from input
        BLEACH_STRIP_TAGS = True

        # remove comments from input
        BLEACH_STRIP_COMMENTS = True


Usage
-----

In Django Models
****************

``input-sanitizer`` provides two custom model fields ``SanitizedCharField`` and ``SanitizedTextField`` to *automatically* remove malicious content from input before saving data into database, but beware it won't work with **bulk update**, **bulk create**, etc as these operations are done at the database level. You can still manually sanitize input data to use for **bulk update**, **bulk create**, etc.

.. code-block:: python

    # in models.py
    from django import models
    from input_sanitizer import sanitized_fields

    class User(models.Model):
        username = sanitized_fields.SanitizedCharField()
        info = sanitized_fields.SanitizedTextField()

``SanitizedCharField`` and ``SanitizedTextField`` may take following arguments to alter cleaning behaviour.
Please, refer `bleach`_ documentation for their use:

* ``allowed_tags``
* ``strip_comments``
* ``strip_tags``

``SanitizedCharField`` is a extension of Django's CharField and therefore, it will accept all normal CharField arguments.

``SanitizedTextField`` is a extension of Django's TextField and therefore, it will accept all normal TextField arguments.

In Views
********

To manually sanitize data, you can use ``get_sanitized_data`` function.
It can be used to sanitize data to be used for **bulk update**, **bulk create**, etc.

.. code-block:: python

    from input_sanitizer import sanitizers 
    cleaned_data = sanitizers.get_sanitized_data(data, bleach_kwargs)

``bleach_kwargs`` arguments are optional and will default to using the ``bleach`` defaults.
You may pass following arguments to alter cleaned output as per your requirement.

* ``allowed_tags``
* ``strip_comments``
* ``strip_tags``

.. _bleach: https://bleach.readthedocs.io/en/latest/clean.html

