Whitelist Download from Tower for Proxy Cloud Web Security

The Whitelist Download from Tower for Proxy Cloud Web Security feature supports the download of whitelists from the Cloud Web Security tower.

This module provides more information about the feature and explains how to configure it.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

Prerequisites for Whitelist Download from Tower for Proxy Cloud Web Security

Install the Trusted Core Trust-Store certificate that can be obtained from http:/​/​www.cisco.com/​security/​pki/​trs/​ios_​core.p7b. One of the root certificates under the trust store is chained with the certificate used by Cloud Web Security Tower. This root certificate will validate the certificate from the Cloud Web Security tower and establish a Secure HTTP connection to fetch the exception lists.xml file.

To install the trust store directly on your Cisco router, configure the following command: 
Device(config)# crypto pki trustpool import url http://www.cisco.com/security/pki/trs/ios_core.p7b

Restrictions for Whitelist Download from Tower for Proxy Cloud Web Security

  • The Cloud Web Security tower does not support IPv6 addresses. Only IPv4 addresses with wild card masks are supported.

Information About Whitelist Download from Tower for Proxy Mode in Cloud Web Security

Whitelist Download from Tower Overview

In Cisco IOS Release 15.5(1)T and later releases, Cloud Web Security supports the download of whitelists from the Cloud Web Security tower. You can download host, user-agent, and IP-based whitelist from the tower. Prior to the introduction of this feature, network administrators had to configure a whitelist through the CLI on all devices in the network. When whitelists are downloaded from the tower, it helps maintain the same configuration across all devices in the network.

Use the whitelist dowload enable command to download whitelists from the tower at regular intervals.

The following section explains how the whitelist information is downloaded from the Cloud Web Security tower:

  • A router (for example, an Integrated Services Router [ISR] Generation 2) initiates a request for whitelist patterns from the Cloud Web Security tower.

  • Whitelist patterns are sent in the form of an XML file.

  • The communication between the router and the Cloud Web Security tower happens over secure HTTP (HTTPS). It is mandatory to have Certificate Authority (CA) certificate on the router without which the whitelist download will not work.

The Cloud Web Security tower validates the request from a device by using the x-Scansafe header fields. All header fields details are in encrypted form.

How Whitelist Download Works

Whitelisting bypasses the HTTP request-header matching traffic to a web server instead of the Cloud Web Security tower or server.

Header-based whitelisting includes domain-based whitelisting and user agent-based whitelisting. Domain-based whitelisting includes domain names and regex patterns. Whitelisting can either be configured through the CLI or as patterns that are downloaded from the Cloud Web Security tower in XML format.

When a device requests for the whitelist configuration, the Cloud Web Security tower sends the whitelist configuration file in XML format. This XML file is parsed to retrieve the encoding type and the list of whitelisted domain names, user-agent patterns, and IPv4 addresses. These parsed patterns are added to respective regex tree for whitelisting.

Whitelist patterns from the Cloud Web Security tower are not stored in the configuration. Whitelist patterns configured through the CLI are stored in the configuration. Whitelist patterns configured via the CLI and patterns downloaded from the tower can be used for whitelisting. To view the list of downloaded whitelist patterns, use the show cws tower-whitelist command.

When an XML file is received and parsed successfully, all previous domain names are removed and newly received domain names are saved. Locally configured domain names are not affected; only domain names from the tower are removed. If patterns added to the regex file fails, all successfully added patterns are retained for whitelisting.

The XML file consists of a list of domain names or patterns and the full IPv4 address of each domain. The maximum length of a domain should be 256 characters or less. Wild card characters supported for domain patterns are ., *, ^, +, ?, $, [], and [^]. The first character of a pattern cannot be + or *.

In IP-based whitelisting, the Cloud Web Security tower does not verify whether duplicate entries exist in access control lists (ACLs) configured through the CLI. Traffic matching any ACL entry configured through the CLI or downloaded from the tower is bypassed from Cloud Web Security tower redirection.

If header-based or IP-based whitelisting is enabled via the CLI and also downloaded from the tower, both whitelist configurations are applied to incoming packets. If the header-based or IP-based whitelisting is disabled via the CLI, only the whitelist configuration downloaded from the Cloud Web Security tower is applied to incoming packets.

Request and Response Handling for Whitelist Download

Request and response handling is supported for header-based and IP-based whitelisting.

The device on which Cloud Web Security is configured, uses secure HTTP (HTTPS), to request the exception list or the list of whitelisted traffic from the Cloud Web Security tower. The timestamp field in the HTTP header is used to check for updates or changes to the whitelist configuration.

If the whitelist configuration is not modified after the last whitelist download, the Cloud Web Security tower responds by indicating that there are no changes to the configuration.

If the whitelist configuration is modified after the last whitelist download, the Cloud Web Security tower sends the updated whitelist configuration file in XML format with the updated timestamp.

When you configure the whitelist download enable command without any time interval, devices send an HTTPS request to the Cloud Web Security tower every 60 minutes. To reflect changes to the whitelist configuration, you must reconfigure the timer to with a different value download the latest whitelist configuration file to the device.

How to Configure Whitelist Download from Tower for Proxy Cloud Web Security

Enabling Whitelist File Download

SUMMARY STEPS

    1.    enable

    2.    configure terminal

    3.    parameter-map type cws global

    4.    whitelist download enable [interval minutes]

    5.    end

    6.    show cws tower-whitelist [stats]


DETAILED STEPS
     Command or ActionPurpose
    Step 1 enable


    Example: 
    Device> enable
     
    Enables privileged EXEC mode.

    • Enter your password if prompted.

     
    Step 2 configure terminal


    Example: 
    Device# configure terminal
     

    Enters global configuration mode.

     
    Step 3 parameter-map type cws global


    Example: 
    Device(config)# parameter-map type cws global
     

    Configures a global Cloud Web Security parameter map and enters parameter-map type inspect configuration mode.

     
    Step 4 whitelist download enable [interval minutes]


    Example: 
    Device(config-profile)# whitelist download enable interval 20
     

    Enables the download of Cloud Web Security whitelist configuration file.

    • The default download interval is 60 minutes.

     
    Step 5 end


    Example: 
    Device(config-profile)# end
     

    Exits parameter-map type inspect configuration mode and returns to privileged EXEC mode.

     
    Step 6 show cws tower-whitelist [stats]


    Example: 
    Device(config-profile)# show cws tower-whitelist
     

    Displays a list of whitelist patterns downloaded from the Cloud Web Security tower.

     

    The following is sample output from the show cws tower-whitelist command: 

    Device# show cws tower-whitelist

Last modified time at tower : Wed, 06 Nov 2014 05:47:52 UTC
Domain names:
  .*redhat.*
  .*xerox.*
  .*yahoo.*.
Extended IP access list cws-internal-dnld-wl-acl
    10 permit ip 10.10.1.16 0.0.0.15 any
    20 permit ip any host 202.3.77.184
User-agent patterns:
  mozilla
  Safari

    The following sample output from the show cws tower-whitelist stats command displays information about whitelist download: 

    Device# show cws tower-whitelist stats

Total Connect Request:                                       13
Total Connect Response:                                      13
Total WL download request:                                   13
SSL failures:                                                0
WL download response:                                        13
     Total success response:                                 1
     Total no config change:                                 7
     Total no config:                                        0
     Total other responses(Other than 200/304/404):          5
     Total other failures(no encoding/HTTP version):         0
XML parse errors:                                            0
Memory failures:                                             0

XML parser stats:
  Src ACLs    Dst ACLs   Domain-name     User-agent
    1           1          1               2

    Configuration Example for Whitelist Download from Tower for Proxy Cloud Web Security

    Example: Enabling Whitelist File Download

    Device# configure terminal
Device(config)# parameter-map type cws global
Device(config-profile)# whitelist download enable interval 20
Device(config-profile)# end

    Additional References Whitelist Download from Tower for Proxy Cloud Web Security

    Related Documents

    Related Topic Document Title

    Cisco IOS commands

    Cisco IOS Master Command List, All Releases

    Security commands

    Technical Assistance

    Description Link

    The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

    To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

    Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

    http:/​/​www.cisco.com/​support

    Feature Information for Whitelist Download from Tower for Proxy Cloud Web Security

    The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

    Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.
    Table 1 Feature Information for Whitelist Download from Tower for Proxy Cloud Web Security

    Feature Name

    Releases

    Feature Information

    Whitelist Download from Tower for Proxy Cloud Web Security

    15.5(1)T

    The Whitelist Download from Tower for Proxy Cloud Web Security feature supports the download of whitelists to devices that have Cloud Web Security configured.

    The following command was introduced or modified: whitelist download enable and show cws tower-whitelist.