Active content filtering

The zero.acf package contains an active content filter (ACF) that provides the support to:

• Validate whether an inbound request parameter includes active content (such as JavaScript, Applet, and ActiveX objects) based on filter rules.
• Remove active content from an inbound request parameter that includes active content (such as JavaScript, Applet, and ActiveX objects) based on filter rules.
• Remove active content from an outbound response message based on filter rules.

The following sections of this article provide information about ACF:

Programmatic API for processing inbound request parameters

When using ACF for a request parameter in your application, you need to invoke APIs that the zero.acf package provides. For a complete overview of the ACF and the APIs, see the javadoc for zero.acf.ACFFactory and zero.acf.ACFProcessor.

Examples using APIs

Use the following steps to validate if a request parameter includes active content.

1. Obtain a zero.acf.ACFProcessor instance using the z=ero.acf.ACFFactory=.
2. Invoke a validate() method of the ACFProcessor to see if the ACF detects any active content in the request parameter.

String parameter = ...;

zero.acf.ACFProcessor processor = zero.acf.ACFFactory.getActiveContentProcessor("text/html");
String detected = processor.validate(parameter);
if (detected != null) {
        // You can throw an exception to let clients know that the active content is detected or
        // You can use XML Encoder API to avoid execution of any active contents
}

Use the following steps to remove active content from a request parameter.

1. Obtain a zero.acf.ACFProcessor instance using the zero.acf.ACFFactory.
2. Invoke the process( method of the ACFProcessor to remove any active content from the request parameter.

String parameter = ...;

zero.acf.ACFProcessor processor = zero.acf.ACFFactory.getActiveContentProcessor("text/html");
String processedString = processor.process(parameter);
// use the processedString to write to the client since ACF has removed possible unwanted active content from the parameter.

Configuring the outbound response message

When you use the ACF for a response message in your application, include the following statement in your zero.config file:

@include "${/config/dependencies/zero.acf}/config/acf.config"

Configuring ACF

ACF runs based on filter rules. The zero.acf package provides a set of filter rules, by default. If you use ACF, you can use the predefined default filter rules or you can define your own custom filter rules.

When you use the ACF, you need to configure the following information in your zero.config:

uri (mandatory)

The URI pattern, which is protected. These are the same regex patterns that are supported as part of the condition operators in Zero. For further information see the Conditions operations section of the Configuration article.

filterRuleFile (optional)

The name of the file including your custom filter rules. ACF assumes that the configuration file is put in the config directory of your application. The schema of this file is shown in the ACF configuration file. If filterRuleFile is not defined then the default configuration file is used.

The following example shows a simple configuration:

@include "${/config/dependencies/zero.acf}/config/acf.config"{
	"uri":"/app(/.*)?"
}

This configuration provides an active content filter on all resources that match the URI pattern /app(/.*)?. In this example, the ‘default’ set of filter rules defined in ACF is used to filter active content.

Using the ACF configuration file

ACF filter rules are described in an XML file. You can use the default configuration file bundled in the zero.acf package or you can prepare your own configuration file.

The DTD structure of the ACF configuration file

The following example shows the DTD of the ACF configuration file:

<!ELEMENT config (filter-chain, filter-rule*) >

<!--  -->

<!ELEMENT filter EMPTY >
<!ATTLIST filter name ID #REQUIRED
class CDATA #REQUIRED
verbose-output (true|false) "false" >

<!ELEMENT filter-rule (target*) >
<!ATTLIST filter-rule id IDREF #REQUIRED >

<!ELEMENT target (rule*, disable-rule) >
<!ATTLIST target scope CDATA "default" >

<!ELEMENT rule EMPTY >

<!ELEMENT disable-rule (disable-target*) >
<!ELEMENT disable-target EMPTY >
<!ATTLIST disable-target scope CDATA #REQUIRED >

In this example, the following are used:

config

The root element of the ACF configuration file. It can be include only one filter chain.

filter

This element contains the basic information for each filter. This element can be used 0 (zero) or more times in the configuration file.

filter/@name

The name of the filter. You can specify an arbitrary name for the filter.

filter/@class

The name of the class that extends the com.ibm.trl.acf.api.Filter abstract class.

filter/@verbose-output (optional)

The default value is false. If it is set to true, comments are inserted wherever the active content is removed.

filter-rule

The actual filtering rule for each filter declared in the <filter> elements in the <filter-chain>. Each filter chain is required to have at least one filter rule.

filter-rule/@id

The associated ID of the filter rule that is specified in the <filter> as filter/@name.

target

This element specifies the filtering scope. You can create this element one or more times.

target/@scope

The value is described using the limited XPath. When the value is ‘default’, the rules are applied to the whole input. The valid XPath can contain only the following limited axis and expressions: ‘/’, ‘//’, ‘[]’ and ‘@=’. For example, ‘/html/body’ is valid but ‘//*[count(*)=3]’ is not.

rule

This element contains the parameters of the filter as custom attributes. The attributes that are defined depend upon the filter being configured.

disable-rule

This element has child elements that specify the scopes where the filter is not applied. Only the elements specified by the scope can be omitted.

disable-rule

This element has child elements that specify the scopes where the filter is not applied.

disable-target

You can specify a plurality of scopes where the filter is not applied.

Default filter rules

The zero.acf package provides the default filter rules shown in the following example:

<?xml version="1.0"?>
<config>
<filter-chain>
<filter name="base" class="com.ibm.trl.acf.basefilter.BaseFilter" verbose-output="false" />
</filter-chain>

<filter-rule id="base">
<target scope="">
<rule c14n='true' all='true' />

<rule attribute='on' attribute-criterion='starts-with' action='remove-attribute-value' />
<rule attribute='${' attribute-criterion='starts-with' action='remove-attribute-value' />
<rule attribute='href' value='javascript' value-criterion='starts-with' action='remove-attribute-value' />
<rule attribute='src' value='javascript' value-criterion='starts-with' action='remove-attribute-value' />
<rule attribute='dynsrc' value='javascript' value-criterion='starts-with' action='remove-attribute-value' />
<rule attribute='style' value='expression' value-criterion='contains' action='remove-attribute-value' />

<rule tag='iFrame' action='remove-tag'/>
<rule tag='applet' action='remove-tag' />
<rule tag='embed' action='remove-tag' />
<rule tag='object' action='remove-tag' />
<rule tag='script' action='remove-tag' />
<rule tag='link' attribute='rel' value='stylesheet' value-criterion='contains' action='remove-tag' />
<rule tag='style' action='remove-tag' />
</target>
</filter-rule>
</config>

If you do not specify the filterRuleFile argument when the API is used for the request parameter, or if you do not configure the filterRuleFile argument in your zero.config file for the response message, then the default rules are used.

The ACF, with the default filter rules, canonicalizes the attribute value before the ACF processing by doing the following:

• Decode the value based on data URL scheme (RFC2397)
• Resolve the entity reference
• Decode the URL encoding
• Remove any whitespaces (tab, carriage return, and line feed)

It removes the following tags:

• ‘iFrame’
• ‘applet’
• ‘embed’
• ‘object’
• ‘script’
• ‘style’

It also removes any:

• ‘ilink’ tags the ‘rel’ attribute value of which matches ‘stylesheet’
• attributes that start with ‘on’ or ‘${’
• ‘href’, ‘src’, and ‘dynsrc’ attributes the value of which starts with ‘javascript’
• ‘style’ attributes the value of which contains ‘expression’.

Note: ACF assumes the response message is UTF-8 encoded if the content type response header does not specify a charset.