customizing protection against cross site scripting …

��

CUSTOMIZING PROTECTION AGAINST CROSS SITE SCRIPTING (XSS)

Cross Site Scripting (or XSS) occurs when a user’s session is hijacked to perform some action on behalf of that user (usually with malicious intent). The dispatch mechanism in <Product Name> can shield the system against XSS-type attacks through enforcement of a security policy. This policy is designed so that all requests must either come from a rec-ognized referrer, originate from a recognized delegator, or the requested URI must be on a list of unenforced URIs.

DISABLING XSS PROTECTION

The policy that controls protection against XSS-type attacks is enabled by default in <Product Name>. You do not need to modify any configuration settings to be protected.

� Warning: Unprotected systems can be compromised, and administrative accounts can be created, modified, and deleted by unauthorized users. <Company Name> highly recommends that you do not disable XSS protection.

To disable XSS protection, use the following procedure:

� If you have not already done so, log in to the <Product Name> server as the administrative user.

� Open a command window (on Windows use Cygwin).

� At the prompt enter the following command to disable XSS protection:

��

� Stop and restart the Web server

Unix users will have to enter the root password in order to stop and restart the web server.

Your system will no longer be protected against XSS-type attacks. If you decide to reen-able XSS protection, you can use the steps described in the next section.

ENABLING XSS PROTECTION

� Note: Because XSS protection is enabled by default in <Product Name>, you should only use the following steps if you manually disabled XSS protection using the steps outlined in the previous section.

If you previously disabled XSS protection and now desire to reenable protection on your system, use the following procedure:

��



� At the prompt enter the following command to enable XSS protection:

��

� Stop and restart the Web server.

XSS protection will be enabled on your system using the default settings. If you want to customize your settings, use the information in the following sections.

MANAGING RESTRICTING LISTS

The security policy that protects against XSS attacks consists of three lists that restrict what different types of hosts can do within the <Product Name> URL subspace. The lists are:

• Referrer list. When users click a link in a Web page, they are sent to the target site, and information about the site where they linked from is sent to the target site in the form of a referrer header. If users type a URI into the address bar, or access a link in a browser bookmark list, the referrer header is blank.

The security policy that protects <Product Name> from XSS attacks analyzes the referrer header for every incoming request, and checks to see if the referring URI is on the referrer list.

The referrer list should contain all hosts other than the <Product Name> host that should be allowed to serve pages with links that target URIs in <Product Name>. If the policy is enabled and a referrer header indicates that the request is coming from a referrer not on the referrer list, then that request would be redirected to an error page.

The moniker for the referrer list that is used when issuing commands is:

��

� Note: In the HTTP Standard (at the code-level) referrer is misspelled as referer. This misspelling is maintained to be consistent with the standard. Whenever you issue a command, you must use referer in place of referrer.

• Delegator list. When requests are issued programmatically to the <Product Name> system by some external system, such requests do not contain a referrer header. Such requests are similar to a user entering a URL into a browser’s address bar, or a user clicking on a link in a bookmark list.

The security policy that protects <Product Name> from XSS attacks notes the lack of a referrer header and checks to see if the originating machine is on the delegator list.

The delegator list should contain all hosts other than the <Product Name> host that should be allowed to call <Product Name> URLs directly without a referrer header. If an incoming request did not contain a referrer header and was not from a host in the

��

��

delegator list, then the request would be redirected to an error page.

The moniker for the delegator list that is used when issuing commands is:

��

• Unenforced URI list. When requests are received by <Product Name>, the security policy that protects <Product Name> from XSS attacks first looks in a list of relative URIs to see if the referrer and delegator checks should be ignored.

As noted, the unenforced URI list should contain relative URIs in <Product Name> for which XSS security checks should not be enforced. These URIs should be relative to the <Product Name> URL context of /cp. For example, a full <Product Name> URI of http://<<Product Name>Host>/cp/home/check/pre would appear in this list as /home/check/pre.

You can add URIs to this list if they do not reveal sensitive material, have no side effects within <Product Name> or its datastores, or are meant to be hit without a referrer header, such as when being typed in, selected by bookmark, or activated spe-cifically by mechanisms like JavaScript’s document.location. URIs in this list are not protected against XSS attacks in any way. These pages are displayed regardless of the request type.

This list allows requests for specified URIs to succeed without a referrer header and without having to add all possible browser-containing client machines to the list of allowed delegators. An example of such a URI is found when the <Product Name> site is hit with no URI. This request is translated by the Web server to the index.html page in <Product Name>. This page contains JavaScript that uses document.location to load the fully-qualified <Product Name> host and a URI of /cp/home/check/pre, which eventually takes the user to the login page. That URI is not allowed by the pol-icy unless it is on the unenforced URI list.

The unenforced URI list can also specify URI prefixes. This is a URI that is termi-nated with an asterisk character (*). Such entries are handled differently from regular URI entries. For prefix entries, incoming URIs are first looked for as a whole unit in the unenforced URI list. If not found there, they are compared to all specified URI prefixes to see if they start with any of the specified prefix values up to but not including their asterisk. If they start with one of the specified prefixes, then they are accepted and are not checked against the referrer and delegator lists.

There is no need to protect URIs that do not have side effects within <Product Name>, and such URIs can be added to the unenforced URI list.

The moniker for the unenforced URI list that is used when issuing commands is:

��

�Warning: A URI for any action that may have security implications when per-formed by an authorized user should not be on the unenforced URI list. By adding items to the unenforced URI list, you run the risk of exposing your system to secu-rity holes. Only add URIs that you are certain do not have security implications.

��

��

Users who attempt to access a function in a way that mimics an XSS attack from a page that does not have a referrer header with a URI on the referrer list, and whose machine is not on the delegator list, and whose URI is not on the unenforced URI list are blocked from proceeding, and are shown a screen similar to the following:

Each restricting list has default settings that will protect the <Product Name> system from outside attacks. However, if users are getting Access Denied errors when accessing <Product Name>, you may need to make changes to the appropriate restricting list.

VIEWING CURRENT LIST CONTENTS

You can view the contents of any of the restricting lists by executing a <command line program name> command at a command prompt. When you issue the command to view the list, you are shown the contents of the list and the value of the count parameter.

To review the contents of one of the restricting lists, use the following procedure:



� At the prompt enter the following command to view the list:

��

��

��

For example, to view the contents of the unenforced URI list, you would enter the following command:

��

A list of URIs will be displayed. Each URI has a unique index number which is used to change a specific URI or to delete a URI from the list. A count parameter shows the value of the largest index number that is being actively applied against the security policy.

The count parameter is manually configured, and should be set to the largest index number in the list. Any URIs with index numbers larger than the value of the count parameter will be ignored by the system.

The count parameter appears in the list in the following format:

��

For example, look in the following unenforced URI list. The count parameter has a value of 6, which is set equal to the value of the largest index number in the list (dispatch.policy.host.unEnforcedURI.6=/email/cid*). However, there are only five URIs in the list, because there is no dispatch.policy.host.unEnforcedURI.3. There-fore, the count parameter does not necessarily reflect the total number of items in the list.

�� !��!��!��"��

��#�!��! �� !��

��$

��$�!��!��

��%�!��! �� !�&

��'�!��!��

If, in the above example, the count parameter were set to 5, then the following line would be ignored (as would any other URI with an index number greater than 5):

��$�!��!��

If you wanted to find out the value of the count parameter without reviewing the list contents, you could issue the following command:

��

��

For example, if you wanted to find out the value of the count parameter for the referrer list, you would issue the following command:

��

If you plan to add items to the list, you will need to note the value of the count parame-ter, as you will have to manually adjust this parameter when you have finished adding items to the list.

If you plan to delete items from the list, you will need to note the index number of the URI(s) that you wish to remove. You will use that value when you remove the item from

� ��

��

the list. You may also want to reduce the count parameter by one, if you remove the URI with the highest index number from the list. However, such a change is not necessary.

MODIFYING A LIST

You can modify a restricting list in two ways:

• Adding items to a list

• Removing items from a list

The following sections provide procedures for each type of modification. Users who are familiar with the export and import functions of the <command line program name> application can use those functions to make multiple changes at one time. For more infor-mation, refer to “Using configman” on page 4.7.

ADDING ITEMS TO A LIST

You can add individual URIs to the unenforced URI list by using the following procedure:



� Add the URI to the list by issuing the following command:

�� (��

For example, if there were 42 URIs already in the Unenforced URI list, and you wanted to unprotect all URIs under the URL http://<<Product Name>Host>/cp/wu, you would use the following command:

�� )�

!&��

You can repeat this command for each URI you wish to add to the list before pro-ceeding to the next step.

� If necessary, increase the count parameter by issuing the following command:

��

�� (��

Only complete this step if the URI you added to the list now has the largest index number. For example, in the previous example, you added a URI with an index number of 43 to the list. Since 43 is now the largest index number in the list, you would need to change the count parameter to 43. You would do this by issuing the following command:

��

�� )

�� !

��

� Note: The value of the count parameter must be set manually. See the section “View-ing current list contents” on page 1.4 for more information.


REMOVING ITEMS FROM A LIST

You can remove individual items from the restricting lists by using the following procedure:



� Delete the URI by issuing the following command:

��

��(��

In this command, replace <index number> with the number corresponding to the URI you wish to remove.

For example, suppose you had the following unenforced URI list:

��#�!��! �� !��$��$�!��!��%�!��! �� !�&��'�!��!��

To remove the URI dispatch.policy.host.unEnforcedURI.6=/email/cid* from the unenforced URI list, issue the following command:

�� $

You may repeat this command as many times as necessary before continuing to the next step.

� If desired, change the count parameter.

If you removed the URI with the highest index number, you can change the count parameter to match the URI with the next highest index number. This change is not necessary.

To change the count parameter, issue the following command:

�� (��

For example, in the previous step you removed the URI with the largest number, which was 6. Since the new largest number in the list is 5, you may wish to reset the count parameter to 5 with the following command:

��

��'

�" ��

��

If in the previous step, however, you had removed the URI dispatch.policy.host.unEnforcedURI.2=/cad/groupmgmt/edit from the list, the high-est index number would still be 6, and you would not change the count parameter.

� Note: The value of the count parameter must be set manually. See the section “View-ing current list contents” on page 1.4 for more information.


CHANGING THE ERROR PAGE

You can change the error page that is displayed to users when a request fails against the security policy by setting the dispatch.policy.host.redirect parameter. This setting must be a relative URI in the <Product Name> environment. To set the path to the custom error page, use the following procedure:



� On Solaris machines, su to root and source the .cprc file by executing the fol-lowing command (not necessary on Windows machines):

��!��*��+��!��

Replace <<Product Name> installation root> with the path of the <Product Name> installation. For example, if on your system <Product Name> is installed in opt/pipeline, you would use the following command:

��!��!��!��

� Set the path to the error page by issuing the following command:

�� ,�

All directories and their contents beneath <$ZZ_ROOT> are accessible to browsers using URLs relative to the <Product Name> application context of /cp. The only exceptions are the WEB-INF directory, and its subdirectories and any directory that matches part of any dynamic URI used by <Product Name>. For the latter, the directory on the <Product Name> server’s hard drive is hidden.

So suppose you created a page located on the hard drive on the <Product Name> server at <$ZZ_ROOT>/misc/noauth.html. This corresponds to a <Product Name> URL of http://<<Product Name>Host>/cp/misc/noauth.html. Therefore, to set the redirect URL to this page, you would issue the following command:

�� !��!

��

� Stop and Restart the Web server.

�� #

��

AUTOMATIC INCLUSION OF SPECIAL HOSTS

By default there are no URIs specified in either the referer list or the delegator list. However, there are four URIs that will be processed regardless of where they are coming from, or if they have a referrer header. When the server is started, the host policy adds these URIs to the delegator and referrer lists as described below.

The special hosts list allows the policy to attempt to discover all the possible names of the host on which it is running. The value 127.0.0.1 is the loopback address, and is a generic value that refers to the host system. It does not refer to any specific computer on any network. The value web.fqn is a variable that contains the fully qualified name of the <Product Name> server(s) that are associated with the installation. The value http.proxy-Host is a variable that contains the location of the proxy server being used by the <Product Name>. The value Localhost IP address refers to the IP address of the host machine.

USING LOG ENTRIES TO TROUBLESHOOT ACCESS PROBLEMS

A list of hosts that are being used by the policy, the list of unenforced URIs, and any rejected incoming requests can be discovered by activating logging for the security policy. If users are getting an Access Denied error when accessing <Product Name>, you should use the following procedures to enable logging and then review the logs to determine what requests are being denied. You can then modify the appropriate restricting lists so that your system runs as desired.

ENABLING AND DISABLING LOGGING

Logging can be enabled by modifying the following file:

-�.��+/!�� !�� "��

Added to List

Host Value Definition Delegators Referrers

127.0.0.1 The loopback address Y Y

web.fqn The fully qualified name of the <Product Name> host (this sup-ports multiple-machine deployment

Y Y

http.proxyHost The configured proxy server for the <Product Name> host

Y N

Localhost IP address The IP address of the local machine

Y Y

��

��

�Caution: Logging can cause significant degradation in <Product Name> perfor-mance. Logging should only be turned on during low-usage hours.

To enable logging, add the following instructions to the cplog4j.properties file, replac-ing variables with appropriate values.

0000000000000000�1��*��2�� 3��

�� "�� &��1��*��2�.�45��,� �

�� "��,� ��

�� "��,� �� "�� /�6��

�� "��,� ��/��,� �,��

�� "��,� ��7�(/�89��9�

�� "��,� ��7�(.��(��7�(��.��(�

��

�� "��,� �� "�*��,��

�� "��,� ��:��*��;�<�8=>$?%@!

;�<#@A�;�;�

0��

While you can modify these instructions as necessary for your institution, <Company Name> recommends the following values:

�� "�� /��!��

�� "�� 7�(/�89�%7.

�� "�� 7�(.��(�%?

Replace <drive path> with the directory path where you want to save the file. For example, if your <Product Name> server is installed on a Windows machine, and if you wanted to save the file to d:\LPlogs\policy.log, you would use the following command:

�� "�� /��A!,*�� !��

The recommended settings will cause the policy to log information to a file located at d:/policy.log. This file will only be allowed to grow to a size of one megabyte before being copied to a policy.log.1 backup file, and a new policy.log file will be started. When the new policy.log file reaches its one megabyte maximum size, the policy.log.1 file will be renamed to policy.log.2, and the policy.log file will be renamed to policy.log.1, and will start over with a new policy.log file. This process continues until there is a policy.log.10 file. At that point, the tenth file is replaced by the policy.log.9 file. With this process, the most recent ten log files are available, and the oldest logs are continually purged from the system.

Logging will begin shortly after you save the file. You do not need to stop and restart the server for logging to begin. To turn off logging, remove all the above lines of code, or comment them all out using the pound sign (#), and save the file. Logging will stop shortly after you save the file.

� Note: For information on modifying the cplog4j file, setting maximum log sizes, and adjusting rolling logs refer to the chapter on monitoring and managing your system in the System Administration Guide.

��

��

REVIEWING LOG FILES

Once logging is activated, you will see entries appear in the policy.log file whenever the server is running. In the following example, the machine on which this system was run-ning was slctests113.<Company Name>.com with the IP address of 149.24.206.133.

#?? �%%�?'�%$A%BA%)5?CC!&��1��*��A

6�� D% B�# �#?$�%))D��6�� 1��6��EF�

��

#?? �%%�?'�%$A%BA%)5?C>!&��1��*��A

��D��%%)��:��+��D��

��6�� 1��+��EF��D% B�# �#?$�%))D��6��

��

#?? �%%�?'�%$A%BA%)5?C>!&��1��*��A

6�� D��%%)��:��+��D��

��D:*G1=8HG2=76�+D��

#?? �%%�?'�%$A%BA%)5?>?!&��1��*��A

��D��%%)��:��+��D��

�� D:*G1=8HG2=76�+D��D% B�# �#?$�%))D��6��

��

#?? �%%�?'�%$A%BA%)5?>?!&��1��*��A

6�� D%#C�?�?�%D��

#?? �%%�?'�%$A%BA%)5?>?!&��1��*��A

6�� D&&&��(��:��+��D��

��D��(�1��D��

#?? �%%�?'�%$A%BA%)5?>?!&��1��*��A

��D&&&��(��:��+��D��

��D��(�1��D��D% B�# �#? �%D��6��

#?? �%%�?'�%$A%BA%)5?>%!&��1��*��A

:�� D��&��1��*��D

��A��

��A�D!��!��D

��A�%C

��D!��!��!��D

��D!��!��D

��D!��!��!6��"��D

��

��6��&��A�)

��D% B�# �#?$�%))D

��D%#C�?�?�%D

��D��%%)��:��+��D

��6��&��2� ��A�'

��D&&&��(��:��+��D

��D% B�# �#?$�%))D

��D%#C�?�?�%D

��D% B�# �#? �%D

��D��%%)��:��+��D

#?? �%%�?'�%$A%BA#)5?'%!&��1��*��A�8�� &��(��

��D!��D�

#?? �%%�?'�%$A%BA#)5?'#!&��1��*��A�:�� D!

��!��D��D!��!��!��D��

��

#?? �%%�?'�%$A%BA#)5?')!&��1��*��A�:�� D!

��

��

��!��!��:��"��D��D!��!��!��!��:��"��D��

��

��

You should note that on server startup, although the configured lists were left empty, the local host, its IP address, the loopback address, and a proxy machine address were added automatically to the list of referrers and delegators as described in “Automatic inclusion of special hosts” on page 1.9. The presence of these values in the referrers list indicates that the <Product Name> host can serve up pages that refer back to the <Product Name> system. These same values in the delegators list indicate that code on that machine can make direct calls to <Product Name> with no referrer header.

Note also that after the lists are printed, the code uses the first incoming request to con-vert the unenforced URI list from the web application relative URIs to <Product Name> host relative URIs by prepending the web application’s URI context value to each URI.

For example, in the above log, the following URI is shown on the UnEnforced URI list:

!��!��

When the first request comes in, the policy converts the URIs to <Product Name> host relative URIs by prepending the URI context value to each URI in the list, as shown below:

#?? �%%�?'�%$A%BA#)5?'%!&��1��*��A�8�� &��(��

��D!��D�

#?? �%%�?'�%$A%BA#)5?'#!&��1��*��A�:�� D!

��!��D��D!��!��!��D��

��

You can review the logs to see how incoming requests are being handled. In the follow-ing example, the URI /cp/content/style.css is found on the unenforced URI list, so the request is permitted.

#?? �%%�?'�%$A%BA ?5#')!&��1��*��A��I��D��!

��!��!��G��D��

#?? �%%�?'�%$A%BA ?5#'$!&��1��*��A��I��D��!

��!��!��G��D��

#?? �%%�?'�%$A%BA ?5)#'!&��1��*��A��I��D!��!��!

��D��8�� 1��

��

In the next example, the request URI either had a referrer header, or the host machine was on the delegator list.

#?? �%%�?'�%$A%BA ?5 '!&��1��*��A��I��D!��!��!

�� D��

#?? �%%�?'�%$A%BA ?5C' !&��1��*��A��I��D!��!&�!

4�:�� 3��#D��

��

#?? �%%�?'�%$A%BA ?5C''!&��1��*��A��I��D!��!&�!

4�:�� 3��#D��

��

��

IDENTIFYING EXTERNAL SYSTEM INTEGRATION PROBLEMS

With the default settings, <Product Name> users should not see the Access Denied mes-sage when linking from any pages within the <Product Name> system. However, if you integrate other systems with <Product Name>, or if you add functionality to <Product Name>, you may find that the system rejects requests that mimic XSS-type attacks.

<Product Name> Content Management System (CMS) is one example of an external system that will not integrate properly with <Product Name> without modifying the restricting lists. To integrate <CMS> with <Product Name>, you must add the fully-quali-fied domain name of the <CMS> host to the delegator list.

When users are encountering the Access Denied message when linking from integrated systems, the logs generated by the policy can be viewed to determine what requests are being denied. That information can be used to modify the configuration of the restricting lists to enable the desired integration.

For example, if your <Product Name> system were integrated with a <Another Product Name> Learning Management system, and if the <Another Product Name> URI /school/<Another Product Name>Frame were removed from the unenforced URI list, users would see the Access Denied screen if they clicked on the following link:

� Note: <Another Product Name> users do not have to add URIs to the unenforced URI list in order for <Another Product Name> to integrate properly with <Product Name>. <Another Product Name> URIs have been included on the unenforced URI list by default.

�6�� JG��J�1��/�J��A!!��%%)��:��+��!��!

��!�6��*��+��+��J��

��

�� <�� :��-��&,��

�&�6��EFK@�6��*��+��-��&��!��""

��##$�%��&��'��&�(��&"��"��"%)��*��

��&�(+��&�,��-��#./01/...#.!�5�D�6��*��+��-��&D5�

D��5��5&��$??5� �� ??5��9��DFK��

H��ED�6��*��+��-��&��EFD5�

'??FK��

��:��-��&,��L�� :��-��&,�� M��

�6��*��+��-��&K��KJ�

��7��J&��&��DDK��KJ�

This operation initiates a request using JavaScript’s window.open() method, and hence does not contain a referrer header, and since the URI is not on the unenforced URI list, the user is redirected to the Access Denied screen. The log that would be created for that request would be similar to the following:

#?? �%%�?'�%$A%BA )5#)>!&��1��*��A��I��D!��!��!

�6��*��+��/��D��

��

#?? �%%�?'�%$A%BA )5#)>!&��1��*��A��I��D!��!��!

�6��*��+��/��D��

#?? �%%�?'�%$A%BA )5#)B!&��1��*��A��I��D!��!��!

�6��*��+��/��D�� D% B�# �#?'�##>D��

��&��D�� D��"�� I��

��

��

This example shows that the URI /school/<Another Product Name>Frame was not found on the unenforced URI list, it did not have a referrer header, and the host machine (the user’s browser in this case) was not on the delegator list. For that reason the request failed, and the user was redirected to the Access Denied screen. To fix this error, the URI /school/<Another Product Name>Frame would need to be added to the unenforced URI list, or a mechanism for accessing that URI should be used that generates the appropriate referrer header.

If users are getting an Access Denied error when linking from external systems, enable logging on your system and look for URIs associated with rejected requests. If you deter-mine that there is no security risk associated with these URIs, you should add them to the unenforced URI list. If a security risk exists, then the URI must be accessed using a mech-anism that produces an acceptable referrer header, or the initiating machine must be added to the delegator list.

If you are having additional problems accessing <Product Name> or configuring XSS protection, contact <Company Name> <Product Name> Support.

customizing protection against cross site scripting …

Documents