OWASP Java HTML Sanitizer Project

2015-12-14T21:57:19Z

Rgm: Correct changelog link (.html to .md)

= Main =
<div style="width:100%;height:160px;border:0,margin:0;overflow: hidden;">[[File:OWASP_Project_Header.jpg|link=]]</div>

{| style="padding: 0;margin:0;margin-top:10px;text-align:left;" |-
| valign="top" style="border-right: 1px dotted gray;padding-right:25px;" |

== OWASP HTML Sanitizer Project ==

The OWASP HTML Sanitizer is a fast and easy to configure HTML Sanitizer written in Java which lets you include HTML authored by third-parties in your web application while protecting against XSS.
The existing dependencies are on guava and JSR 305. The other jars are only needed by the test suite. The JSR 305 dependency is a compile-only dependency, only needed for annotations.
This code was written with security best practices in mind, has an extensive test suite, and has undergone adversarial security review.
A great place to get started using the OWASP Java HTML Sanitizer is here: https://github.com/OWASP/java-html-sanitizer/blob/master/docs/getting_started.md.

== Benefits ==
* Provides 4X the speed of [https://www.owasp.org/index.php/Category:OWASP_AntiSamy_Project AntiSamy] sanitization in DOM mode and 2X the speed of AntiSamy in SAX mode.
* Very easy to use. It allows for simple programmatic POSITIVE policy configuration (see below). No XML config.
* Actively maintained by Mike Samuel from Google's AppSec team!
* Passing 95+% of AntiSamy's unit tests plus many more.
* This is code from the Caja project that was donated by Google. It is rather high performance and low memory utilization.
* Java 1.5+

==Licensing==
The OWASP HTML Sanitizer is free to use and is dual licensed under the [http://www.apache.org/licenses/LICENSE-2.0 Apache 2 License] and the [http://opensource.org/licenses/BSD-3-Clause New BSD License].

| valign="top" style="padding-left:25px;width:200px;border-right: 1px dotted gray;padding-right:25px;" |

== What is this? ==

The OWASP HTML Sanitizer Projects provides Java based HTML sanitization of untrusted HTML!

== Code Repo ==

[https://github.com/owasp/java-html-sanitizer OWASP HTML Sanitizer at GitHub]

== Email List ==

Questions? Please sign up for our [https://groups.google.com/forum/#!forum/owasp-java-html-sanitizer-support Project Support List ]

== Project Leaders ==

Author/Project Leader [https://www.owasp.org/index.php/User:Mike_Samuel Mike Samuel] [mailto:mikesamuel@gmail.com @] 
Project Manager [https://www.owasp.org/index.php/User:Jmanico Jim Manico] [mailto:jim.manico@owasp.org @]

== Related Projects ==

* [[XSS (Cross Site Scripting) Prevention Cheat Sheet]]
* [[OWASP JSON Sanitizer]]
* [[OWASP Java Encoder Project]]
* [[OWASP Dependency Check]]
* [https://www.owasp.org/index.php/Category:OWASP_AntiSamy_Project OWASP AntiSamy]
* [https://github.com/sourceclear/headlines Sourceclear Headlines]
* [https://code.google.com/p/keyczar/ Google KeyCzar]
* [http://shiro.apache.org/ Apache SHIRO]

== Ohloh ==

*https://www.ohloh.net/p/owasp-java-html-sanitizer

| valign="top" style="padding-left:25px;width:200px;" |

== Quick Download ==

[https://search.maven.org/remotecontent?filepath=com/googlecode/owasp-java-html-sanitizer/owasp-java-html-sanitizer/r239/owasp-java-html-sanitizer-r239.jar v239 at Maven Central] 
[http://owasp-java-html-sanitizer.googlecode.com/svn/trunk/distrib/javadoc/index.html JavaDoc v239] 

== News and Events ==
* [1 May 2015] Move to GitHub
* [2 July 2014] v239 Released
* [3 Mar 2014] v226 Released
* [5 Feb 2014] New Wiki
* [4 Sept 2013] v209 Released

== Change Log ==
For recent release notes, please visit the [https://github.com/OWASP/java-html-sanitizer/blob/master/change_log.md changelog on GitHub].

==Classifications==

{| width="200" cellpadding="2"
|-
| align="center" valign="top" width="50%" rowspan="2"| [[File:Owasp-incubator-trans-85.png|link=https://www.owasp.org/index.php/OWASP_Project_Stages#tab=Incubator_Projects]]
| align="center" valign="top" width="50%"| [[File:Owasp-builders-small.png|link=]]
|-
| align="center" valign="top" width="50%"| [[File:Owasp-defenders-small.png|link=]]
|-
| colspan="2" align="center" | [http://www.apache.org/licenses/LICENSE-2.0 Apache 2 License]
|-
| colspan="2" align="center" | [[File:Project_Type_Files_CODE.jpg|link=]]
|}

|}

= Creating a HTML Policy =

You can use prepackaged policies here: [https://github.com/OWASP/java-html-sanitizer/blob/master/src/main/java/org/owasp/html/Sanitizers.java https://github.com/OWASP/java-html-sanitizer/blob/master/src/main/java/org/owasp/html/Sanitizers.java].

PolicyFactory policy = Sanitizers.FORMATTING.and(Sanitizers.LINKS);
String safeHTML = policy.sanitize(untrustedHTML);

or the tests show how to configure your own policy here: [https://github.com/OWASP/java-html-sanitizer/blob/master/src/test/java/org/owasp/html/HtmlPolicyBuilderTest.java https://github.com/OWASP/java-html-sanitizer/blob/master/src/test/java/org/owasp/html/HtmlPolicyBuilderTest.java]

PolicyFactory policy = new HtmlPolicyBuilder()
.allowElements("a")
.allowUrlProtocols("https")
.allowAttributes("href").onElements("a")
.requireRelNofollowOnLinks()
.build();
String safeHTML = policy.sanitize(untrustedHTML);

... or you can write custom policies to do things like changing h1s to divs with a certain class ...

PolicyFactory policy = new HtmlPolicyBuilder()
.allowElements("p")
.allowElements(
new ElementPolicy() {
public String apply(String elementName, List<String> attrs) {
attrs.add("class");
attrs.add("header-" + elementName);
return "div";
}
}, "h1", "h2", "h3", "h4", "h5", "h6"))
.build();
String safeHTML = policy.sanitize(untrustedHTML);

You can also use the default "ebay" and "slashdot" policies. The Slashdot policy (defined here https://github.com/OWASP/java-html-sanitizer/blob/master/src/main/java/org/owasp/html/examples/SlashdotPolicyExample.java) allows the following tags ("a", "p", "div", "i", "b", "em", "blockquote", "tt", "strong"n "br", "ul", "ol", "li") and only certain attributes. This policy also allows for the custom slashdot tags, "quote" and "ecode".

= Questions =

How was this project tested? 
This code was written with security best practices in mind, has an extensive test suite, and has undergone [https://github.com/OWASP/java-html-sanitizer/blob/master/docs/attack_review_ground_rules.md adversarial security review].

How is this project deployed? 
This project is best deployed through Maven [https://github.com/OWASP/java-html-sanitizer/blob/master/docs/getting_started.md https://github.com/OWASP/java-html-sanitizer/blob/master/docs/getting_started.md]

__NOTOC__ <headertabs/>

[[Category:OWASP_Tool]]
[[Category:OWASP_Alpha_Quality_Tool]]
[[Category:OWASP_Project|Java HTML Sanitizer]]

OWASP - User contributions [en]

OWASP Java HTML Sanitizer Project