com.coverity.security

Class Filter

java.lang.Object

com.coverity.security.Filter

public class Filter
extends Object

Filter is a small set of methods for filtering tainted data that cannot be escaped. These methods may change the semantics of the data if it cannot be determined to be safe, however great care has been taken in the design to ensure that they behave in a way that "makes sense" intuitively These methods fit into the nested escaper framework that the Escape class supports, and should be used as the innermost "escaper" to ensure correctness, e.g. <iframe src="${cov:htmlEscape(cov:asURL(param.web)}"> </iframe> Ensure that that param.web cannot escape the src attribute, but also ensures that it cannot be a URL that causes XSS. While Coverity's static analysis product references these escaping routines as exemplars and understands their behavior, there is no dependency on Coverity products and these routines are completely standalone. Feel free to use them! Just make sure you use them correctly.

Author:

Alex Kouzemtchenko, Romain Gaucher

Constructor Summary

Constructors

Constructor and Description
Filter()

Method Summary

Modifier and Type	Method and Description
static String	asCssColor(String color) asCssColor is useful when you need to insert dynamic data into a CSS color context, e.g.
static String	asCssColor(String color, String defaultColor) Identical to asCssColor, except you can provide your own default value
static String	asFlexibleURL(String url) This function should be semantically identical to the above function with the exception of using a scheme blacklist instead of a scheme whitelist.
static String	asNumber(String number) asNumber is useful for outputting dynamic data as a number in a JavaScript context, e.g.
static String	asNumber(String number, String defaultNumber) Identical to asNumber, except you can provide your own default value
static String	asURL(String url) URL filtering to ensure that the URL is a safe non-relative URL or transforms it to a safe relative URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Filter

public Filter()

Method Detail

asNumber

public static String asNumber(String number)

asNumber is useful for outputting dynamic data as a number in a JavaScript context, e.g. <script> var userNum = ${cov:asNumber(param.web)}; </script> It allows decimal and hex numbers (e.g. 0x41) through unmodified, unless they have leading 0s and may be interpreted as octal numbers, in which case the leading 0s are stripped.

Parameters:

number - the potential number to filter

Returns:

a sanitised number or 0 if there is no conversion

Since:

1.1

asNumber

public static String asNumber(String number,
                              String defaultNumber)

Identical to asNumber, except you can provide your own default value

Parameters:

number - the potential number to filter

defaultNumber - a default String to return if the number argument is not a Number

Returns:

a sanitised number or defaultNumber if there is no conversion

Since:

1.1

asCssColor

public static String asCssColor(String color)

asCssColor is useful when you need to insert dynamic data into a CSS color context, e.g. <style> .userprofile { background-color: ${cov:asCssColor(param.web)}; } </style> It should be used for colors since it is not possible to specify colors inside CSS strings This method validates that the parameter is a valid color, or returns the string "invalid". The string invalid was chosen since it is a token that is not valid in this context, so this rule will be ignored by the CSS parser, but additional rules will still be parsed properly. The effect of this is that it will be as if the CSS rule was never specified. We have chosen to provide an illegal token instead of a default such as "transparent" or "inherit" since the defaults are different for different color contexts, e.g. background-color defaults to transparent, while color defaults to inherit. This will essentially preserve those semantics.

Parameters:

color - the potential css color to filter

Returns:

the color specified or the string "invalid"

Since:

1.1

asCssColor

public static String asCssColor(String color,
                                String defaultColor)

Identical to asCssColor, except you can provide your own default value

Parameters:

color - the potential css color to filter

defaultColor - a default String to return if the color argument is not a potentially valid CSS color

Returns:

a sanitised color or defaultColor if there is no conversion

Since:

1.1

asURL

public static String asURL(String url)

URL filtering to ensure that the URL is a safe non-relative URL or transforms it to a safe relative URL. Specifically, if the URL starts with one of the following it will be unaltered:

• / to allow URLs of the form /path/from/root.jsp
• \\ to allow UNC paths of the form \\server\some\file.xls
• http:
• https:
• ftp:
• mailto:

Our research shows that these URLs will not cause an XSS defect by being accessed, and is intended to be used in cases where having a user point a URL at their own content is intended. Other URLs are made safe by turning them into URLs relative to the current document, e.g. file.html becomes ./file.html ?query becomse ./?query #hash becomes ./#hash javascript:alert(1) becomes ./javascript:alert(1) This methods will not prevent XSS if it is used to show active content such as:

• JavaScript src
• CSS src
• CSS \@import
• Embeded Flash files
• Java Applets
• Embeded PDFs
• Pretty much any other plugin
• etc

Parameters:

url - The potentially tainted URL to be Filtered

Returns:

a safe version of the URL or null if input is null

Since:

1.1

asFlexibleURL

public static String asFlexibleURL(String url)

This function should be semantically identical to the above function with the exception of using a scheme blacklist instead of a scheme whitelist. It disallows javascript, vbscript, data and about URL schemes and turns these URLs into relative URLs the same way the above does. It allows all other schemes as long as the scheme name is directly followed by a colon (:) The complexity of this function is necessary due to the parsing that browsers do when they encounter URLs, e.g. stripping new lines and NUL bytes.

Parameters:

url - The potentially tainted URL to be Filtered

Returns:

a safe version of the URL or null if input is null

Since:

1.1