public class Safelist
extends java.lang.Object
Start with one of the defaults:
If you need to allow more through (please be careful!), tweak a base safelist with:
addTags(String... tagNames)
addAttributes(String tagName, String... attributes)
addEnforcedAttribute(String tagName, String attribute, String value)
addProtocols(String tagName, String attribute, String... protocols)
You can remove any setting from an existing safelist with:
removeTags(String... tagNames)
removeAttributes(String tagName, String... attributes)
removeEnforcedAttribute(String tagName, String attribute)
removeProtocols(String tagName, String attribute, String... removeProtocols)
The cleaner and these safelists assume that you want to clean a body
fragment of HTML (to add user
supplied HTML into a templated page), and not to clean a full HTML document. If the latter is the case, either wrap the
document HTML around the cleaned body HTML, or create a safelist that allows html
and head
elements as appropriate.
If you are going to extend a safelist, please be very careful. Make sure you understand what attributes may lead to XSS attack vectors. URL attributes are particularly vulnerable and require careful validation. See the XSS Filter Evasion Cheat Sheet for some XSS attack examples (that jsoup will safegaurd against the default Cleaner and Safelist configuration).
Modifier and Type | Class and Description |
---|---|
(package private) static class |
Safelist.AttributeKey |
(package private) static class |
Safelist.AttributeValue |
(package private) static class |
Safelist.Protocol |
(package private) static class |
Safelist.TagName |
(package private) static class |
Safelist.TypedValue |
Modifier and Type | Field and Description |
---|---|
private static java.lang.String |
All |
private java.util.Map<Safelist.TagName,java.util.Set<Safelist.AttributeKey>> |
attributes |
private java.util.Map<Safelist.TagName,java.util.Map<Safelist.AttributeKey,Safelist.AttributeValue>> |
enforcedAttributes |
private boolean |
preserveRelativeLinks |
private java.util.Map<Safelist.TagName,java.util.Map<Safelist.AttributeKey,java.util.Set<Safelist.Protocol>>> |
protocols |
private java.util.Set<Safelist.TagName> |
tagNames |
Constructor and Description |
---|
Safelist()
Create a new, empty safelist.
|
Safelist(Safelist copy)
Deep copy an existing Safelist to a new Safelist.
|
Modifier and Type | Method and Description |
---|---|
Safelist |
addAttributes(java.lang.String tag,
java.lang.String... attributes)
Add a list of allowed attributes to a tag.
|
Safelist |
addEnforcedAttribute(java.lang.String tag,
java.lang.String attribute,
java.lang.String value)
Add an enforced attribute to a tag.
|
Safelist |
addProtocols(java.lang.String tag,
java.lang.String attribute,
java.lang.String... protocols)
Add allowed URL protocols for an element's URL attribute.
|
Safelist |
addTags(java.lang.String... tags)
Add a list of allowed elements to a safelist.
|
static Safelist |
basic()
This safelist allows a fuller range of text nodes:
a, b, blockquote, br, cite, code, dd, dl, dt, em, i, li,
ol, p, pre, q, small, span, strike, strong, sub, sup, u, ul , and appropriate attributes. |
static Safelist |
basicWithImages()
This safelist allows the same text tags as
basic() , and also allows img tags, with appropriate
attributes, with src pointing to http or https . |
(package private) Attributes |
getEnforcedAttributes(java.lang.String tagName) |
protected boolean |
isSafeAttribute(java.lang.String tagName,
Element el,
Attribute attr)
Test if the supplied attribute is allowed by this safelist for this tag
|
protected boolean |
isSafeTag(java.lang.String tag)
Test if the supplied tag is allowed by this safelist
|
private boolean |
isValidAnchor(java.lang.String value) |
static Safelist |
none()
This safelist allows only text nodes: any HTML Element or any Node other than a TextNode will be removed.
|
Safelist |
preserveRelativeLinks(boolean preserve)
Configure this Safelist to preserve relative links in an element's URL attribute, or convert them to absolute
links.
|
static Safelist |
relaxed()
This safelist allows a full range of text and structural body HTML:
a, b, blockquote, br, caption, cite,
code, col, colgroup, dd, div, dl, dt, em, h1, h2, h3, h4, h5, h6, i, img, li, ol, p, pre, q, small, span, strike, strong, sub,
sup, table, tbody, td, tfoot, th, thead, tr, u, ul |
Safelist |
removeAttributes(java.lang.String tag,
java.lang.String... attributes)
Remove a list of allowed attributes from a tag.
|
Safelist |
removeEnforcedAttribute(java.lang.String tag,
java.lang.String attribute)
Remove a previously configured enforced attribute from a tag.
|
Safelist |
removeProtocols(java.lang.String tag,
java.lang.String attribute,
java.lang.String... removeProtocols)
Remove allowed URL protocols for an element's URL attribute.
|
Safelist |
removeTags(java.lang.String... tags)
Remove a list of allowed elements from a safelist.
|
static Safelist |
simpleText()
This safelist allows only simple text formatting:
b, em, i, strong, u . |
private boolean |
testValidProtocol(Element el,
Attribute attr,
java.util.Set<Safelist.Protocol> protocols) |
private static final java.lang.String All
private final java.util.Set<Safelist.TagName> tagNames
private final java.util.Map<Safelist.TagName,java.util.Set<Safelist.AttributeKey>> attributes
private final java.util.Map<Safelist.TagName,java.util.Map<Safelist.AttributeKey,Safelist.AttributeValue>> enforcedAttributes
private final java.util.Map<Safelist.TagName,java.util.Map<Safelist.AttributeKey,java.util.Set<Safelist.Protocol>>> protocols
private boolean preserveRelativeLinks
public Safelist()
basic()
,
basicWithImages()
,
simpleText()
,
relaxed()
public Safelist(Safelist copy)
copy
- the Safelist to copypublic static Safelist none()
Note that the output of Jsoup.clean(String, Safelist)
is still HTML even when using
this Safelist, and so any HTML entities in the output will be appropriately escaped. If you want plain text, not
HTML, you should use a text method such as Element.text()
instead, after cleaning the document.
Example:
String sourceBodyHtml = "<p>5 is < 6.</p>";
String html = Jsoup.clean(sourceBodyHtml, Safelist.none());
Cleaner cleaner = new Cleaner(Safelist.none());
String text = cleaner.clean(Jsoup.parse(sourceBodyHtml)).text();
// html is: 5 is < 6.
// text is: 5 is < 6.
public static Safelist simpleText()
b, em, i, strong, u
. All other HTML (tags and
attributes) will be removed.public static Safelist basic()
This safelist allows a fuller range of text nodes: a, b, blockquote, br, cite, code, dd, dl, dt, em, i, li,
ol, p, pre, q, small, span, strike, strong, sub, sup, u, ul
, and appropriate attributes.
Links (a
elements) can point to http, https, ftp, mailto
, and have an enforced
rel=nofollow
attribute.
Does not allow images.
public static Safelist basicWithImages()
basic()
, and also allows img
tags, with appropriate
attributes, with src
pointing to http
or https
.public static Safelist relaxed()
a, b, blockquote, br, caption, cite,
code, col, colgroup, dd, div, dl, dt, em, h1, h2, h3, h4, h5, h6, i, img, li, ol, p, pre, q, small, span, strike, strong, sub,
sup, table, tbody, td, tfoot, th, thead, tr, u, ul
Links do not have an enforced rel=nofollow
attribute, but you can add that if desired.
public Safelist addTags(java.lang.String... tags)
tags
- tag names to allowpublic Safelist removeTags(java.lang.String... tags)
tags
- tag names to disallowpublic Safelist addAttributes(java.lang.String tag, java.lang.String... attributes)
E.g.: addAttributes("a", "href", "class")
allows href
and class
attributes
on a
tags.
To make an attribute valid for all tags, use the pseudo tag :all
, e.g.
addAttributes(":all", "class")
.
tag
- The tag the attributes are for. The tag will be added to the allowed tag list if necessary.attributes
- List of valid attributes for the tagpublic Safelist removeAttributes(java.lang.String tag, java.lang.String... attributes)
E.g.: removeAttributes("a", "href", "class")
disallows href
and class
attributes on a
tags.
To make an attribute invalid for all tags, use the pseudo tag :all
, e.g.
removeAttributes(":all", "class")
.
tag
- The tag the attributes are for.attributes
- List of invalid attributes for the tagpublic Safelist addEnforcedAttribute(java.lang.String tag, java.lang.String attribute, java.lang.String value)
E.g.: addEnforcedAttribute("a", "rel", "nofollow")
will make all a
tags output as
<a href="..." rel="nofollow">
tag
- The tag the enforced attribute is for. The tag will be added to the allowed tag list if necessary.attribute
- The attribute namevalue
- The enforced attribute valuepublic Safelist removeEnforcedAttribute(java.lang.String tag, java.lang.String attribute)
tag
- The tag the enforced attribute is for.attribute
- The attribute namepublic Safelist preserveRelativeLinks(boolean preserve)
http://
.
Note that when handling relative links, the input document must have an appropriate base URI
set when
parsing, so that the link's protocol can be confirmed. Regardless of the setting of the preserve relative
links
option, the link must be resolvable against the base URI to an allowed protocol; otherwise the attribute
will be removed.
preserve
- true
to allow relative links, false
(default) to denyaddProtocols(java.lang.String, java.lang.String, java.lang.String...)
public Safelist addProtocols(java.lang.String tag, java.lang.String attribute, java.lang.String... protocols)
E.g.: addProtocols("a", "href", "ftp", "http", "https")
To allow a link to an in-page URL anchor (i.e. <a href="#anchor">
, add a #
:
E.g.: addProtocols("a", "href", "#")
tag
- Tag the URL protocol is forattribute
- Attribute nameprotocols
- List of valid protocolspublic Safelist removeProtocols(java.lang.String tag, java.lang.String attribute, java.lang.String... removeProtocols)
E.g.: removeProtocols("a", "href", "ftp")
tag
- Tag the URL protocol is forattribute
- Attribute nameremoveProtocols
- List of invalid protocolsprotected boolean isSafeTag(java.lang.String tag)
tag
- test tagprotected boolean isSafeAttribute(java.lang.String tagName, Element el, Attribute attr)
tagName
- tag to consider allowing the attribute inel
- element under test, to confirm protocolattr
- attribute under testprivate boolean testValidProtocol(Element el, Attribute attr, java.util.Set<Safelist.Protocol> protocols)
private boolean isValidAnchor(java.lang.String value)
Attributes getEnforcedAttributes(java.lang.String tagName)