=============== Goals of Bleach =============== This document lists the goals and non-goals of Bleach. My hope is that by focusing on these goals and explicitly listing the non-goals, the project will evolve in a stronger direction. .. contents:: Goals ===== Always take a allowed-list-based approach ----------------------------------------- Bleach should always take a allowed-list-based approach to markup filtering. Specifying disallowed lists is error-prone and not future proof. For example, you should have to opt-in to allowing the ``onclick`` attribute, not opt-out of all the other ``on*`` attributes. Future versions of HTML may add new event handlers, like ``ontouch``, that old disallow would not prevent. Main goal is to sanitize input of malicious content --------------------------------------------------- The primary goal of Bleach is to sanitize user input that is allowed to contain *some* HTML as markup and is to be included in the content of a larger page in an HTML context. Examples of such content might include: * User comments on a blog. * "Bio" sections of a user profile. * Descriptions of a product or application. These examples, and others, are traditionally prone to security issues like XSS or other script injection, or annoying issues like unclosed tags and invalid markup. Bleach will take a proactive, allowed-list-only approach to allowing HTML content, and will use the HTML5 parsing algorithm to handle invalid markup. See the :ref:`chapter on clean() ` for more info. Safely create links ------------------- The secondary goal of Bleach is to provide a mechanism for finding or altering links (```` tags with ``href`` attributes, or things that look like URLs or email addresses) in text. While Bleach itself will always operate on a allowed-list-based security model, the :ref:`linkify() method ` is flexible enough to allow the creation, alteration, and removal of links based on an extremely wide range of use cases. Non-Goals ========= Bleach is designed to work with fragments of HTML by untrusted users. Some non-goal use cases include: Sanitize complete HTML documents -------------------------------- Bleach's ``clean`` is not for sanitizing entire HTML documents. Once you're creating whole documents, you have to allow so many tags that a disallow-list approach (e.g. forbidding ``