OWASP Encoder Plugin
The OWASP Encoder Plugin creates a Velocity viewtool with a number of useful input-sanitization functions. Strategic use of such procedures in Velocity templates can help prevent XSS-based attacks.
Installation#
Please refer to the General Instructions under Plugin Examples.
Usage#
Once the plugin is installed, your Velocity context will include a new viewtool accessed by calling $owasp. Its capabilities can be seen in the table below; each method accepts a string as its input argument.
All for... methods perform encoding operations that escape or enclose terminating sequences or similar dangers, and return the modified input. More detailed documentation of these can be found in the Encoder class's Javadoc.
| Method | Description |
|---|---|
$owasp.validateUrl | Returns true if input is a valid URL, false otherwise. |
$owasp.urlHasXSS | Returns true if input contains a substring that may execute a script. |
$owasp.cleanUrl | If input is a valid URL, returns a version sanitized with the forHtmlAttribute method; returns null otherwise. |
$owasp.forCDATA | Encodes data for an XML CDATA section. Replaces ]]> with ]]>]]<![CDATA[> |
$owasp.forCssString | Sanitizes CSS strings using hexidecimal encodings; safe to use in both style blocks and attributes in HTML. Characters: "'\<&/> as well as a number of non-printing characters such as line and paragraph separators, null characters, etc. |
$owasp.forCssUrl | Encodes for CSS URL contexts. The context must be surrounded by url( and ). |
$owasp.forHtml | Encodes for both HTML text content and text attributes. Note that since this method handles both, it is less efficient than either forHtmlAttribute or forHtmlContent. Characters affected: &<>"' |
$owasp.forHtmlAttribute | This method encodes for HTML text attributes. Characters: &<"' (Note: Encoding > is not required for attributes.) |
$owasp.forHtmlContent | This method encodes for HTML text content. Characters: &<> |
$owasp.forHtmlUnquotedAttribute | Encodes for unquoted HTML attribute values. forHtml or forHtmlAttribute should usually be preferred over this method as quoted attributes are XHTML compliant. |
$owasp.forJava | Encodes for a Java string. This method will use \b, \t, \r, \f, \n, \", \', \\, octal and unicode escapes. Valid surrogate pairing is not checked. |
$owasp.forJavaScript | Encodes for a JavaScript string; safe for use in HTML script attributes (such as onclick), script blocks, JSON files, and JavaScript source. Escapes backspace, horizontal tab, line feed, form feed, carriage return, &"'\/, and more. |
$owasp.forJavaScriptAttribute | Encodes for Javascript within HTML script attributes such as onclick; not safe for use in script blocks. |
$owasp.forJavaScriptBlock | Encodes for Javascript within HTML script blocks; not safe for use in script attributes. |
$owasp.forJavaScriptSource | This method encodes for JavaScript strings contained within a JavaScript or JSON file; not safe for use in any context embedded in HTML. |
$owasp.forUri | Deprecated. Performs encoding of a URL, assumed valid. |
$owasp.forUriComponent | Performs percent-encoding for a component of a URI, such as a query parameter name or value, path or query-string. Ensures special characters are not interpreted as part of another component. |
$owasp.forXml | Encoder for XML and XHTML; see forHtml. |
$owasp.forXmlAttribute | Encodes XML attributes; see forHtmlAttribute. |
$owasp.forXmlContent | Encodes XML content; see forHtmlContent. |
$owasp.forXmlComment | Encpdes XML comments. Not for use with (X)HTML contexts, as comments may be misinterpreted by browsers. |
Examples#
The following input results in the subsequent output sequence:
#set($url = "https://www.google.com/search?q=maven+repository&oq=maven&aqs=chrome.1.<script>alert('test');</script>.2855j0j1&sourceid=chrome&ie=UTF-8") $owasp.validateUrl($url) $owasp.forHtmlAttribute($url) $owasp.urlHasXSS($url) $owasp.forHtml("<script>window.location='/bad-url?doBadThings=true';</script>")
true https://www.google.com/search?q=maven+repository&oq=maven&aqs=chrome.1.<script>alert('test');</script>.2855j0j1&sourceid=chrome&ie=UTF-8 true <script>window.location='/bad-url?doBadThings=true';</script>