Using the Cross-Site Scripting Detection Policy

Learn how to configure a tag white list to protect your web service from being exploited by cross-site scripting.

For information about using policies in the context of the developer portal, see Business Policies.

Table of Contents

  1. Introduction
  2. White List Default Policy
  3. Configuration
  4. Activating a policy
  5. Attaching a policy


The Cross-Site Scripting Detection Policy is an Operational policy that allows you to block potentially malicous HTML tags in the request message body using what is called a white list of tags. Notes:

  • The white list includes a list of HTML tags that will be accepted if they are found in the request message body.
  • You can use the default white list (Add Default HTML tags), customize the default list, or define your own set of tags and attributes that are allowed in the request message body.
  • If a white list tag is found, Network Director passes the request message to the downstream service.
  • Make sure you do not add malicious tags to the white list.
  • All tags specified in the white list are allowed. All other tags are disallowed. This is referred to as a "black list."

Say for example your web service includes an anchor <a> tag. When you attach a default Cross-Site Scripting Detection Policy to a REST service and send a request message to the Network Director container that is hosting the service, you will get an "HTTP 403 Forbidden" error response. This is because the <a> tag is not defined in the policy's "white list."

Back to top

White List (Default Policy)

The default policy state includes a white list with the tags shown below.

Back to top


Let's take a quick walkthrough of the Cross-Site Scripting Detection Policy configuration process to get you started.

Add Policy / Use System Policy

  • In Policy Manager, to create a Cross-Site Scripting Detection Policy instance, go to Policies > Operational Policies and choose Add Policy.
  • You can also take advantage of the pre-defined Cross-Site Scripting Detection Policy called WhiteListedCrossSiteScripting. This is an out-of-the-box System Policy that is preconfigured with the default white list. You can customize the white list configuration to suit your needs and then attach it directly to a web service or operation.

    If you use the default configuration, all tags in the white list are accepted when Network Director passes the request message to the downstream service.

Modify Policy

When you click Modify to make changes to the Cross-Site Scripting Detection policy on the Policy Details page, the initial policy looks like this:

If you use the default policy without defining a white list, all tags will be disallowed. If you define a white list, all tags in the white list will be accepted, and all other tags (the black list) will be forbidden when Network Director passes the request message to the downstream service. Instead, an HTTP 404 Forbidden error will be returned.

Configure White List / Custom Tags

The next step is to define your tag white list. These represent tags that comprise the HTML in your request message body and that you have designated as ones that could be potentially attacked. White list tags are allowed when Network Director passes the request message to the downstream service. The following options are available:

  • Use Add Default HTML Tags to add a default set of tags to your policy (the white list) and customize using the Remove Selected Row option.
  • Use Add Tag to add a custom tag and attributes (if applicable).

Activate and Attach Policy

After you've saved your policy, activate it. You can then attach it:

  • To an individual web service to apply it to that service
  • At the Organization level and the policy will be active for all services defined within the organization.

Back to top

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Back to top

Attaching a policy

To use the policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.

Back to top