org.owasp.html
Class HtmlPolicyBuilder

java.lang.Object
  extended by org.owasp.html.HtmlPolicyBuilder

@NotThreadSafe
public class HtmlPolicyBuilder
extends java.lang.Object

Conveniences for configuring policies for the HtmlSanitizer.

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 call build() or toFactory().

 // 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 a canned 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 to require 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 or attribute policy when calling allow…. E.g. to convert headers into <div>s, you could use an element policy

     new 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:

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 of build(org.owasp.html.HtmlStreamEventReceiver), then binding policies to output channels is cheap so there's no need.

Author:
Mike Samuel

Nested Class Summary
 class HtmlPolicyBuilder.AttributeBuilder
          Builds the relationship between attributes, the values that they may have, and the elements on which they may appear.
 
Field Summary
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
HtmlPolicyBuilder()
           
 
Method Summary
 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(ElementPolicy policy, java.lang.String... elementNames)
          Allow the given elements with the given policy.
 HtmlPolicyBuilder allowElements(java.lang.String... elementNames)
          Allows the named elements.
 HtmlPolicyBuilder allowStandardUrlProtocols()
          A canned URL protocol policy that allows http, https, and mailto.
 HtmlPolicyBuilder allowStyling()
          Convert style="<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 attribute allow.
 HtmlPolicyBuilder disallowElements(java.lang.String... elementNames)
          Disallows the named elements.
 HtmlPolicyBuilder disallowUrlProtocols(java.lang.String... protocols)
          Reverses a decision made by allowUrlProtocols(java.lang.String...).
 HtmlPolicyBuilder disallowWithoutAttributes(java.lang.String... elementNames)
          Disallows the given elements from appearing without attributes.
 HtmlPolicyBuilder requireRelNofollowOnLinks()
          Adds rel=nofollow to links.
 PolicyFactory toFactory()
          Like build(org.owasp.html.HtmlStreamEventReceiver) but can be reused to create many different policies each backed by a different output channel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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.

Constructor Detail

HtmlPolicyBuilder

public HtmlPolicyBuilder()
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.

See Also:
DEFAULT_SKIP_IF_EMPTY, disallowWithoutAttributes(java.lang.String...)

disallowWithoutAttributes

public HtmlPolicyBuilder disallowWithoutAttributes(java.lang.String... elementNames)
Disallows the given elements from appearing without attributes.

See Also:
DEFAULT_SKIP_IF_EMPTY, allowWithoutAttributes(java.lang.String...)

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 attribute allow.

For this to have an effect you must call at least one of HtmlPolicyBuilder.AttributeBuilder.globally() and HtmlPolicyBuilder.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()
Adds rel=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 as javascript protocols if you might use this policy with untrusted code.


disallowUrlProtocols

public HtmlPolicyBuilder disallowUrlProtocols(java.lang.String... protocols)
Reverses a decision made by allowUrlProtocols(java.lang.String...).


allowStandardUrlProtocols

public HtmlPolicyBuilder allowStandardUrlProtocols()
A canned URL protocol policy that allows http, https, and mailto.


allowStyling

public HtmlPolicyBuilder allowStyling()
Convert style="<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 a HtmlStreamRenderer.

toFactory

public PolicyFactory toFactory()
Like build(org.owasp.html.HtmlStreamEventReceiver) but can be reused to create many different policies each backed by a different output channel.



Copyright © 2012 OWASP. All Rights Reserved.