Policy (OWASP AntiSamy 1.6.4 API)

java.lang.Object
- org.owasp.validator.html.Policy

Direct Known Subclasses:

InternalPolicy
```
public class Policy
extends Object
```
Policy.java - This file holds the model for our policy engine.

## Schema validation behavior change starting with AntiSamy 1.6.0 ##

Prior to v1.6.0 AntiSamy was not actually enforcing it's defined XSD. Now, by default AntiSamy enforce the schema, and won't continue if the AntiSamy policy is invalid. However, we recognize that it might not be possible for developers to fix their AntiSamy policies right away if they are non-compliant, and yet still want to upgrade AntiSamy to pick up any security improvements, feature enhancements, and bug fixes. As such, we now provide two ways to (temporarily!) disable schema validation:

1) Set the Java System property: owasp.validator.validateschema to false. This can be done at the command line (e.g., -Dowasp.validator.validateschema=false) or via the Java System properties file. Neither requires a code change.

2) Change the code using AntiSamy to invoke: Policy.setSchemaValidation(false) before loading the AntiSamy policy. This is a static call so once disabled, it is disabled for all new Policy instances.

To encourage AntiSamy users to only use XSD compliant policies, AntiSamy will always log some type of warning when schema validation is disabled. It will either WARN that the policy is non-compliant so it can be fixed, or it will WARN that the policy is compliant, but schema validation is OFF, so validation should be turned back on (i.e., stop disabling it). We also added INFO level logging when AntiSamy schema's are loaded and validated.

## Disabling schema validation is deprecated immediately, and will go away in AntiSamy 1.7+ ##

The ability to disable the new schema validation feature is intended to be temporary, to smooth the transition to properly valid AntiSamy policy files. We plan to drop this feature in the next major release. We estimate that this will be some time mid-late 2022, so not any time soon. The idea is to give dev teams using AntiSamy directly, or through other libraries like ESAPI, plenty of time to get their policy files schema compliant before schema validation becomes required.

Logging: The logging introduced in 1.6+ uses slf4j. AntiSamy includes the slf4j-simple library for its logging, but AntiSamy users can import and use an alternate slf4j compatible logging library if they prefer. They can also then exclude slf4j-simple if they want to.

WARNING:: AntiSamy's use of slf4j-simple, without any configuration file, logs messages in a buffered manner to standard output. As such, some or all of these log messages may get lost if an Exception, such as a PolicyException is thrown. This can likely be rectified by configuring slf4j-simple to log to standard error instead, or use an alternate slf4j logger that does so.

Author:

Arshan Dabirsiaghi

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

protected static class Policy.ParseContext

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`Policy.ParseContext`

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACTION_FILTER`
`static String`	`ACTION_TRUNCATE`
`static String`	`ACTION_VALIDATE`
`static String`	`ALLOW_DYNAMIC_ATTRIBUTES`
`static String`	`ANCHORS_NOFOLLOW`
`static Pattern`	`ANYTHING_REGEXP`
`static String`	`CONNECTION_TIMEOUT`
`static int`	`DEFAULT_MAX_INPUT_SIZE`
`static int`	`DEFAULT_MAX_STYLESHEET_IMPORTS`
`protected static String`	`DEFAULT_POLICY_URI`
`protected Map<String,String>`	`directives`
`static String`	`DISALLOW_DOCTYPE_DECL`
`static String`	`EMBED_STYLESHEETS`
`static String`	`ENTITY_ENCODE_INTL_CHARS`
`static String`	`EXTERNAL_GENERAL_ENTITIES`
`static String`	`EXTERNAL_PARAM_ENTITIES`
`static String`	`FORMAT_OUTPUT`
`static String`	`LOAD_EXTERNAL_DTD`
`static String`	`OMIT_DOCTYPE_DECLARATION`
`static String`	`OMIT_XML_DECLARATION`
`static String`	`PRESERVE_COMMENTS`
`static String`	`PRESERVE_SPACE`
`protected Map<String,Tag>`	`tagRules`
`static String`	`USE_XHTML`
`static String`	`VALIDATE_PARAM_AS_EMBED`
`static String`	`VALIDATIONPROPERTY`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Policy(Policy.ParseContext parseContext)`
`protected`	`Policy(Policy old, Map<String,String> directives, Map<String,Tag> tagRules)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Policy`	`cloneWithDirective(String name, String value)` Creates a copy of this policy with an added/changed directive.
`TagMatcher`	`getAllowedEmptyTags()` Return all the allowed empty tags configured in the Policy.
`AntiSamyPattern`	`getCommonRegularExpressions(String name)`
`String`	`getDirective(String name)` Return a directive value based on a lookup name.
`Attribute`	`getDynamicAttributeByName(String name)` A method for returning one of the dynamic <global-attribute> entries by name.
`Attribute`	`getGlobalAttributeByName(String name)` A simple method for returning on of the <global-attribute> entries by name.
`static Policy`	`getInstance()` Construct a Policy using the default policy file location ("resources/antisamy.xml").
`static Policy`	`getInstance(File file)` Construct a Policy from the File object passed in.
`static Policy`	`getInstance(InputStream inputStream)` Construct a Policy from the InputStream object passed in.
`static Policy`	`getInstance(String filename)` Construct a Policy based on the file whose name is passed in.
`static Policy`	`getInstance(URL url)` Construct a Policy from the target of the URL passed in.
`protected static Policy.ParseContext`	`getParseContext(Element topLevelElement, URL baseUrl)`
`Property`	`getPropertyByName(String propertyName)` Retrieves a CSS Property from the Policy.
`TagMatcher`	`getRequiresClosingTags()` Return all the tags that are required to be closed with an end tag, even if they have no child content.
`static boolean`	`getSchemaValidation()` Deprecated. Temporary method to enable AntiSamy users to upgrade to 1.6.x while still using policy files that aren't schema compliant. AntiSamy plans to make schema validation mandatory starting with v1.7.0 (~mid/late 2022).
`protected static Policy.ParseContext`	`getSimpleParseContext(Element topLevelElement)`
`protected static InputSource`	`getSourceFromUrl(URL baseUrl)`
`Tag`	`getTagByLowercaseName(String tagName)` Get the Tag specified by the provided tag name.
`protected static Element`	`getTopLevelElement(InputSource source, Callable<InputSource> getResetSource)`
`protected static Element`	`getTopLevelElement(URL baseUrl)`
`static InputSource`	`resolveEntity(String systemId, URL baseUrl)` Resolves public and system IDs to files stored within the JAR.
`static void`	`setSchemaValidation(boolean enable)` Deprecated. Temporary method to enable AntiSamy users to upgrade to 1.6.x while still using policy files that aren't schema compliant. AntiSamy plans to make schema validation mandatory starting with v1.7.0 (~mid/late 2022).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ANYTHING_REGEXP
```
public static final Pattern ANYTHING_REGEXP
```
  - DEFAULT_POLICY_URI
```
protected static final String DEFAULT_POLICY_URI
```
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_INPUT_SIZE
```
public static final int DEFAULT_MAX_INPUT_SIZE
```
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_STYLESHEET_IMPORTS
```
public static final int DEFAULT_MAX_STYLESHEET_IMPORTS
```
    See Also:
    
    Constant Field Values
  - OMIT_XML_DECLARATION
```
public static final String OMIT_XML_DECLARATION
```
    See Also:
    
    Constant Field Values
  - OMIT_DOCTYPE_DECLARATION
```
public static final String OMIT_DOCTYPE_DECLARATION
```
    See Also:
    
    Constant Field Values
  - USE_XHTML
```
public static final String USE_XHTML
```
    See Also:
    
    Constant Field Values
  - FORMAT_OUTPUT
```
public static final String FORMAT_OUTPUT
```
    See Also:
    
    Constant Field Values
  - EMBED_STYLESHEETS
```
public static final String EMBED_STYLESHEETS
```
    See Also:
    
    Constant Field Values
  - CONNECTION_TIMEOUT
```
public static final String CONNECTION_TIMEOUT
```
    See Also:
    
    Constant Field Values
  - ANCHORS_NOFOLLOW
```
public static final String ANCHORS_NOFOLLOW
```
    See Also:
    
    Constant Field Values
  - VALIDATE_PARAM_AS_EMBED
```
public static final String VALIDATE_PARAM_AS_EMBED
```
    See Also:
    
    Constant Field Values
  - PRESERVE_SPACE
```
public static final String PRESERVE_SPACE
```
    See Also:
    
    Constant Field Values
  - PRESERVE_COMMENTS
```
public static final String PRESERVE_COMMENTS
```
    See Also:
    
    Constant Field Values
  - ENTITY_ENCODE_INTL_CHARS
```
public static final String ENTITY_ENCODE_INTL_CHARS
```
    See Also:
    
    Constant Field Values
  - ALLOW_DYNAMIC_ATTRIBUTES
```
public static final String ALLOW_DYNAMIC_ATTRIBUTES
```
    See Also:
    
    Constant Field Values
  - EXTERNAL_GENERAL_ENTITIES
```
public static final String EXTERNAL_GENERAL_ENTITIES
```
    See Also:
    
    Constant Field Values
  - EXTERNAL_PARAM_ENTITIES
```
public static final String EXTERNAL_PARAM_ENTITIES
```
    See Also:
    
    Constant Field Values
  - DISALLOW_DOCTYPE_DECL
```
public static final String DISALLOW_DOCTYPE_DECL
```
    See Also:
    
    Constant Field Values
  - LOAD_EXTERNAL_DTD
```
public static final String LOAD_EXTERNAL_DTD
```
    See Also:
    
    Constant Field Values
  - ACTION_VALIDATE
```
public static final String ACTION_VALIDATE
```
    See Also:
    
    Constant Field Values
  - ACTION_FILTER
```
public static final String ACTION_FILTER
```
    See Also:
    
    Constant Field Values
  - ACTION_TRUNCATE
```
public static final String ACTION_TRUNCATE
```
    See Also:
    
    Constant Field Values
  - tagRules
```
protected final Map<String,Tag> tagRules
```
  - directives
```
protected final Map<String,String> directives
```
  - VALIDATIONPROPERTY
```
public static final String VALIDATIONPROPERTY
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Policy
```
protected Policy(Policy.ParseContext parseContext)
          throws PolicyException
```
    Throws:
    
    PolicyException
  - Policy
```
protected Policy(Policy old,
                 Map<String,String> directives,
                 Map<String,Tag> tagRules)
```
- Method Detail
  - getTagByLowercaseName
```
public Tag getTagByLowercaseName(String tagName)
```
    Get the Tag specified by the provided tag name.
    
    Parameters:
    
    tagName - The name of the Tag to return.
    
    Returns:
    
    The requested Tag, or null if it doesn't exist.
  - getPropertyByName
```
public Property getPropertyByName(String propertyName)
```
    Retrieves a CSS Property from the Policy.
    
    Parameters:
    
    propertyName - The name of the CSS Property to look up.
    
    Returns:
    
    The CSS Property associated with the name specified, or null if none is found.
  - getSchemaValidation
```
@Deprecated
public static boolean getSchemaValidation()
```
    Deprecated. Temporary method to enable AntiSamy users to upgrade to 1.6.x while still using policy files that aren't schema compliant. AntiSamy plans to make schema validation mandatory starting with v1.7.0 (~mid/late 2022).
    
    Is XSD schema validation across all policies enabled or not? It is enabled by default.
    
    Returns:
    
    True if schema validation enabled. False otherwise.
  - setSchemaValidation
```
@Deprecated
public static void setSchemaValidation(boolean enable)
```
    Deprecated. Temporary method to enable AntiSamy users to upgrade to 1.6.x while still using policy files that aren't schema compliant. AntiSamy plans to make schema validation mandatory starting with v1.7.0 (~mid/late 2022).
    
    This can enable/disable the schema validation against AntiSamy XSD for the instantiated policies. It is enabled by default.
    
    Parameters:
    
    enable - boolean value to specify if the schema validation should be performed. Use false to disable.
  - getInstance
```
public static Policy getInstance()
                          throws PolicyException
```
    Construct a Policy using the default policy file location ("resources/antisamy.xml").
    
    Returns:
    
    A populated Policy object based on the XML policy file located in the default location.
    
    Throws:
    
    PolicyException - If the file is not found or there is a problem parsing the file.
  - getInstance
```
public static Policy getInstance(String filename)
                          throws PolicyException
```
    Construct a Policy based on the file whose name is passed in.
    
    Parameters:
    
    filename - The path to the XML policy file.
    
    Returns:
    
    A populated Policy object based on the XML policy file located in the location passed in.
    
    Throws:
    
    PolicyException - If the file is not found or there is a problem parsing the file.
  - getInstance
```
public static Policy getInstance(InputStream inputStream)
                          throws PolicyException
```
    Construct a Policy from the InputStream object passed in.
    
    Parameters:
    
    inputStream - An InputStream which contains the XML policy information.
    
    Returns:
    
    A populated Policy object based on the XML policy file pointed to by the inputStream parameter.
    
    Throws:
    
    PolicyException - If there is a problem parsing the input stream.
  - getInstance
```
public static Policy getInstance(File file)
                          throws PolicyException
```
    Construct a Policy from the File object passed in.
    
    Parameters:
    
    file - A File object which contains the XML policy information.
    
    Returns:
    
    A populated Policy object based on the XML policy file pointed to by the File parameter.
    
    Throws:
    
    PolicyException - If the file is not found or there is a problem parsing the file.
  - getInstance
```
public static Policy getInstance(URL url)
                          throws PolicyException
```
    Construct a Policy from the target of the URL passed in.
    
    NOTE: This is the only factory method that will work with <include> tags in AntiSamy policy files.
    
    For security reasons, the provided URL must point to a local file. Currently only 'file:' and 'jar:' URL prefixes are allowed. If you want to use a different URL format, and are confident that the URL points to a safe source, you can open the target of the URL with URL.openStream(), and use the getInstance(InputStream) constructor instead. For example, Spring has classpath: and Wildfly/Jboss supports vfs: for accessing local files. Just be aware that this alternate constructor doesn't support the use of <include> tags, per the NOTE above.
    
    Parameters:
    
    url - A URL object which contains the XML policy information.
    
    Returns:
    
    A populated Policy object based on the XML policy file pointed to by the File parameter.
    
    Throws:
    
    PolicyException - If the file is not found or there is a problem parsing the file.
  - getSimpleParseContext
```
protected static Policy.ParseContext getSimpleParseContext(Element topLevelElement)
                                                    throws PolicyException
```
    Throws:
    
    PolicyException
  - getParseContext
```
protected static Policy.ParseContext getParseContext(Element topLevelElement,
                                                     URL baseUrl)
                                              throws PolicyException
```
    Throws:
    
    PolicyException
  - getTopLevelElement
```
protected static Element getTopLevelElement(URL baseUrl)
                                     throws PolicyException
```
    Throws:
    
    PolicyException
  - getSourceFromUrl
```
protected static InputSource getSourceFromUrl(URL baseUrl)
                                       throws PolicyException
```
    Throws:
    
    PolicyException
  - getTopLevelElement
```
protected static Element getTopLevelElement(InputSource source,
                                            Callable<InputSource> getResetSource)
                                     throws PolicyException
```
    Throws:
    
    PolicyException
  - cloneWithDirective
```
public Policy cloneWithDirective(String name,
                                 String value)
```
    Creates a copy of this policy with an added/changed directive.
    
    Parameters:
    
    name - The directive to add/modify
    
    value - The value
    
    Returns:
    
    A clone of the policy with the updated directive
  - getGlobalAttributeByName
```
public Attribute getGlobalAttributeByName(String name)
```
    A simple method for returning on of the <global-attribute> entries by name.
    
    Parameters:
    
    name - The name of the global-attribute we want to look up.
    
    Returns:
    
    An Attribute associated with the global-attribute lookup name specified.
  - getDynamicAttributeByName
```
public Attribute getDynamicAttributeByName(String name)
```
    A method for returning one of the dynamic <global-attribute> entries by name.
    
    Parameters:
    
    name - The name of the dynamic global-attribute we want to look up.
    
    Returns:
    
    An Attribute associated with the global-attribute lookup name specified, or null if not found.
  - getAllowedEmptyTags
```
public TagMatcher getAllowedEmptyTags()
```
    Return all the allowed empty tags configured in the Policy.
    
    Returns:
    
    A String array of all the he allowed empty tags configured in the Policy.
  - getRequiresClosingTags
```
public TagMatcher getRequiresClosingTags()
```
    Return all the tags that are required to be closed with an end tag, even if they have no child content.
    
    Returns:
    
    A String array of all the tags that are required to be closed with an end tag, even if they have no child content.
  - getDirective
```
public String getDirective(String name)
```
    Return a directive value based on a lookup name.
    
    Parameters:
    
    name - The name of the directive we want to look up.
    
    Returns:
    
    A String object containing the directive associated with the lookup name, or null if none is found.
  - resolveEntity
```
public static InputSource resolveEntity(String systemId,
                                        URL baseUrl)
                                 throws IOException,
                                        SAXException
```
    Resolves public and system IDs to files stored within the JAR.
    
    Parameters:
    
    systemId - The name of the entity we want to look up.
    
    baseUrl - The base location of the entity.
    
    Returns:
    
    A String object containing the directive associated with the lookup name, or null if none is found.
    
    Throws:
    
    IOException - if the specified URL can't be opened.
    
    SAXException - This exception can't actually be thrown, but left in the method signature for API compatibility reasons.
  - getCommonRegularExpressions
```
public AntiSamyPattern getCommonRegularExpressions(String name)
```

Class Policy

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ANYTHING_REGEXP

DEFAULT_POLICY_URI

DEFAULT_MAX_INPUT_SIZE

DEFAULT_MAX_STYLESHEET_IMPORTS

OMIT_XML_DECLARATION

OMIT_DOCTYPE_DECLARATION

USE_XHTML

FORMAT_OUTPUT

EMBED_STYLESHEETS

CONNECTION_TIMEOUT

ANCHORS_NOFOLLOW

VALIDATE_PARAM_AS_EMBED

PRESERVE_SPACE

PRESERVE_COMMENTS

ENTITY_ENCODE_INTL_CHARS

ALLOW_DYNAMIC_ATTRIBUTES

EXTERNAL_GENERAL_ENTITIES

EXTERNAL_PARAM_ENTITIES

DISALLOW_DOCTYPE_DECL

LOAD_EXTERNAL_DTD

ACTION_VALIDATE

ACTION_FILTER

ACTION_TRUNCATE

tagRules

directives

VALIDATIONPROPERTY

Constructor Detail

Policy

Policy

Method Detail

getTagByLowercaseName

getPropertyByName

getSchemaValidation

setSchemaValidation

getInstance

getInstance

getInstance

getInstance

getInstance

getSimpleParseContext

getParseContext

getTopLevelElement

getSourceFromUrl

getTopLevelElement

cloneWithDirective

getGlobalAttributeByName

getDynamicAttributeByName

getAllowedEmptyTags

getRequiresClosingTags

getDirective

resolveEntity

getCommonRegularExpressions