Class HtmlPolicyBuilder
- java.lang.Object
-
- org.owasp.html.HtmlPolicyBuilder
-
@NotThreadSafe public class HtmlPolicyBuilder extends java.lang.Object
Conveniences for configuring policies for theHtmlSanitizer
.Usage
To create a policy, first construct an instance of this class; then call
allow…
methods to turn on tags, attributes, and other processing modes; and finally callbuild()
ortoFactory()
.// Define the policy. Function
policyDefinition = new HtmlPolicyBuilder() .allowElements("a", "p") .allowAttributes("href").onElements("a") .toFactory(); // Sanitize your output. HtmlSanitizer.sanitize(myHtml. policyDefinition.apply(myHtmlStreamRenderer)); Embedded Content
Embedded URLs are filtered by
protocol
. There is acanned policy
so you can easily white-list widely used policies that don't violate the current pages origin. See "Customization" below for ways to do further filtering. If you allow links it might be worthwhile torequire
rel=nofollow
.This class simply throws out all embedded JS. Use a custom element or attribute policy to allow through signed or otherwise known-safe code. Check out the Caja project if you need a way to contain third-party JS.
This class does not attempt to faithfully parse and sanitize CSS. It does provide
one
styling option that allows through a few CSS properties that allow textual styling, but that disallow image loading, history stealing, layout breaking, code execution, etc.Customization
You can easily do custom processing on tags and attributes by supplying your own
element policy
orattribute policy
when callingallow…
. E.g. to convert headers into<div>
s, you could use an element policynew HtmlPolicyBuilder .allowElement( new ElementPolicy() { public String apply(String elementName, List
attributes) { attributes.add("class"); attributes.add("header-" + elementName); return "div"; } }, "h1", "h2", "h3", "h4", "h5", "h6") .build(outputChannel) Rules of Thumb
Throughout this class, several rules hold:
- Everything is denied by default. There are
disallow…
methods, but those reverse allows instead of rolling back overly permissive defaults. - The order of allows and disallows does not matter.
Disallows trump allows whether they occur before or after them.
The only method that needs to be called in a particular place is
build(org.owasp.html.HtmlStreamEventReceiver)
. Allows or disallows afterbuild
is called have no effect on the already built policy. - Element and attribute policies are applied in the following order: element specific attribute policy, global attribute policy, element policy. Element policies come last so they can observe all the post-processed attributes, and so they can add attributes that are exempt from attribute policies. Element specific policies go first, so they can normalize content to a form that might be acceptable to a more simplistic global policy.
Thread safety and efficiency
This class is not thread-safe. The resulting policy will not violate its security guarantees as a result of race conditions, but is not thread safe because it maintains state to track whether text inside disallowed elements should be suppressed.
The resulting policy can be reused, but if you use the
toFactory()
method instead ofbuild(org.owasp.html.HtmlStreamEventReceiver)
, then binding policies to output channels is cheap so there's no need.- Author:
- Mike Samuel
- Everything is denied by default. There are
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
HtmlPolicyBuilder.AttributeBuilder
Builds the relationship between attributes, the values that they may have, and the elements on which they may appear.
-
Field Summary
Fields Modifier and Type Field Description static com.google.common.collect.ImmutableSet<java.lang.String>
DEFAULT_SKIP_IF_EMPTY
The default set of elements that are removed if they have no attributes.
-
Constructor Summary
Constructors Constructor Description HtmlPolicyBuilder()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description HtmlPolicyBuilder.AttributeBuilder
allowAttributes(java.lang.String... attributeNames)
Returns an object that lets you associate policies with the given attributes, and allow them globally or on specific elements.HtmlPolicyBuilder
allowCommonBlockElements()
A canned policy that allows a number of common block elements.HtmlPolicyBuilder
allowCommonInlineFormattingElements()
A canned policy that allows a number of common formatting elements.HtmlPolicyBuilder
allowElements(java.lang.String... elementNames)
Allows the named elements.HtmlPolicyBuilder
allowElements(ElementPolicy policy, java.lang.String... elementNames)
Allow the given elements with the given policy.HtmlPolicyBuilder
allowStandardUrlProtocols()
A canned URL protocol policy that allowshttp
,https
, andmailto
.HtmlPolicyBuilder
allowStyling()
Convertstyle="<CSS>"
to simple non-JS containing<font>
tags to allow color, font-size, typeface, and other styling.HtmlPolicyBuilder
allowUrlProtocols(java.lang.String... protocols)
Adds to the set of protocols that are allowed in URL attributes.HtmlPolicyBuilder
allowWithoutAttributes(java.lang.String... elementNames)
Assuming the given elements are allowed, allows them to appear without attributes.HtmlSanitizer.Policy
build(HtmlStreamEventReceiver out)
Produces a policy based on the allow and disallow calls previously made.HtmlPolicyBuilder.AttributeBuilder
disallowAttributes(java.lang.String... attributeNames)
Reverse an earlier attributeallow
.HtmlPolicyBuilder
disallowElements(java.lang.String... elementNames)
Disallows the named elements.HtmlPolicyBuilder
disallowUrlProtocols(java.lang.String... protocols)
Reverses a decision made byallowUrlProtocols(java.lang.String...)
.HtmlPolicyBuilder
disallowWithoutAttributes(java.lang.String... elementNames)
Disallows the given elements from appearing without attributes.HtmlPolicyBuilder
requireRelNofollowOnLinks()
Addsrel=nofollow
to links.PolicyFactory
toFactory()
Likebuild(org.owasp.html.HtmlStreamEventReceiver)
but can be reused to create many different policies each backed by a different output channel.
-
-
-
Field Detail
-
DEFAULT_SKIP_IF_EMPTY
public static final com.google.common.collect.ImmutableSet<java.lang.String> DEFAULT_SKIP_IF_EMPTY
The default set of elements that are removed if they have no attributes. Since<img>
is in this set, by default, a policy will remove<img src=javascript:alert(1337)>
because its URL is not allowed and it has no other attributes that would warrant it appearing in the output.
-
-
Method Detail
-
allowElements
public HtmlPolicyBuilder allowElements(java.lang.String... elementNames)
Allows the named elements.
-
disallowElements
public HtmlPolicyBuilder disallowElements(java.lang.String... elementNames)
Disallows the named elements. Elements are disallowed by default, so there is no need to disallow elements, unless you are making an exception based on an earlier allow.
-
allowElements
public HtmlPolicyBuilder allowElements(ElementPolicy policy, java.lang.String... elementNames)
Allow the given elements with the given policy.- Parameters:
policy
- May remove or add attributes, change the element name, or deny the element.
-
allowCommonInlineFormattingElements
public HtmlPolicyBuilder allowCommonInlineFormattingElements()
A canned policy that allows a number of common formatting elements.
-
allowCommonBlockElements
public HtmlPolicyBuilder allowCommonBlockElements()
A canned policy that allows a number of common block elements.
-
allowWithoutAttributes
public HtmlPolicyBuilder allowWithoutAttributes(java.lang.String... elementNames)
Assuming the given elements are allowed, allows them to appear without attributes.
-
disallowWithoutAttributes
public HtmlPolicyBuilder disallowWithoutAttributes(java.lang.String... elementNames)
Disallows the given elements from appearing without attributes.
-
allowAttributes
public HtmlPolicyBuilder.AttributeBuilder allowAttributes(java.lang.String... attributeNames)
Returns an object that lets you associate policies with the given attributes, and allow them globally or on specific elements.
-
disallowAttributes
public HtmlPolicyBuilder.AttributeBuilder disallowAttributes(java.lang.String... attributeNames)
Reverse an earlier attributeallow
.For this to have an effect you must call at least one of
HtmlPolicyBuilder.AttributeBuilder.globally()
andHtmlPolicyBuilder.AttributeBuilder.onElements(java.lang.String...)
.Attributes are disallowed by default, so there is no need to call this with a laundry list of attribute/element pairs.
-
requireRelNofollowOnLinks
public HtmlPolicyBuilder requireRelNofollowOnLinks()
Addsrel=nofollow
to links.
-
allowUrlProtocols
public HtmlPolicyBuilder allowUrlProtocols(java.lang.String... protocols)
Adds to the set of protocols that are allowed in URL attributes. For each URL attribute that is allowed, we further constrain it by only allowing the value through if it specifies no protocol, or if it specifies one in the allowedProtocols white-list. This is done regardless of whether any protocols have been allowed, so allowing the attribute "href" globally with the identity policy but not white-listing any protocols, effectively disallows the "href" attribute globally.Do not allow any
*script
such asjavascript
protocols if you might use this policy with untrusted code.
-
disallowUrlProtocols
public HtmlPolicyBuilder disallowUrlProtocols(java.lang.String... protocols)
Reverses a decision made byallowUrlProtocols(java.lang.String...)
.
-
allowStandardUrlProtocols
public HtmlPolicyBuilder allowStandardUrlProtocols()
A canned URL protocol policy that allowshttp
,https
, andmailto
.
-
allowStyling
public HtmlPolicyBuilder allowStyling()
Convertstyle="<CSS>"
to simple non-JS containing<font>
tags to allow color, font-size, typeface, and other styling.
-
build
public HtmlSanitizer.Policy build(HtmlStreamEventReceiver out)
Produces a policy based on the allow and disallow calls previously made.- Parameters:
out
- receives calls to open only tags allowed by previous calls to this object. Typically aHtmlStreamRenderer
.
-
toFactory
public PolicyFactory toFactory()
Likebuild(org.owasp.html.HtmlStreamEventReceiver)
but can be reused to create many different policies each backed by a different output channel.
-
-