Using the Cross-Site Scripting Detection Policy

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

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

Table of Contents

Introduction

The Cross-Site Scripting Detection Policy is an Operational policy that allows you to block potentially malicious HTML tags in the request message body using an allowlist of tags. Notes:

  • The allowlist includes a list of HTML tags that will be accepted if they are found in the request message body.
  • You can use the default allowlist (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 an allowlist tag is found, Network Director passes the request message to the downstream service.
  • Make sure you do not add malicious tags to the allowlist.
  • All tags specified in the allowlist are allowed. All other tags are disallowed. This is referred to as a denylist.

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 allowlist.

Default allowlist (Default Policy)

You can add a default allowlist that includes basic HTML tags such as those shown below. You can then modify the list.

Configuration

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 use the pre-defined Cross-Site Scripting Detection Policy called AllowListedCrossSiteScripting. This is an out-of-the-box System Policy that is preconfigured with the default allowlist. You can customize the allowlist 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 allowlist 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 an allowlist, all tags will be disallowed. If you define an allowlist, all tags in the allowlist will be accepted, and all other tags (the denylist) will be forbidden when Network Director passes the request message to the downstream service. Instead, an HTTP 404 Forbidden error will be returned.

Configure allowlist / Custom Tags

The next step is to define your tag allowlist. These represent tags that comprise the HTML in your request message body and that you have designated as ones that could be potentially attacked. Allowlist 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 allowlist) 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.

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.

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.