Cisco ACE Web Application Firewall User Guide

Transcription

1 Cisco ACE Web Application Firewall User Guide Software Version 6.1 Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax: Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. CCDE, CCENT, CCSI, Cisco Eos, Cisco HealthPresence, Cisco IronPort, the Cisco logo, Cisco Nurse Connect, Cisco Pulse, Cisco SensorBase, Cisco StackPower, Cisco StadiumVision, Cisco TelePresence, Cisco Unified Computing System, Cisco WebEx, DCE, Flip Channels, Flip for Good, Flip Mino, Flipshare (Design), Flip Ultra, Flip Video, Flip Video (Design), Instant Broadband, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn, Cisco Capital, Cisco Capital (Design), Cisco:Financed (Stylized), Cisco Store, Flip Gift Card, and One Million Acts of Green are service marks; and Access Registrar, Aironet, AllTouch, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Lumin, Cisco Nexus, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, Continuum, EtherFast, EtherSwitch, Event Center, Explorer, Follow Me Browsing, GainMaker, ilynx, IOS, iphone, IronPort, the IronPort logo, Laser Link, LightStream, Linksys, MeetingPlace, MeetingPlace Chime Sound, MGX, Networkers, Networking Academy, PCNow, PIX, PowerKEY, PowerPanels, PowerTV, PowerTV (Design), PowerVu, Prisma, ProConnect, ROSA, SenderBase, SMARTnet, Spectrum Expert, StackWise, WebEx, and the WebEx logo are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0910R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental. 2008, 2009 Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface ix Introducing the Cisco ACE Web Application Firewall 1-1 Securing Web Applications 1-1 Deployment Environment 1-2 About the ACE Web Application Firewall Manager 1-2 Securing Web Applications 2-3 Overview 2-3 Web Application Policy Components 2-4 Policy Development Steps for Web Application Security 2-5 Extending Rules and Signatures 2-5 Message-to-Handler Matching 2-5 Monitoring Web Application Security Activity 2-6 Updating the Base Configuration 2-7 First Steps 3-9 Logging In to the Manager Web Console 3-9 Navigating the Manager Web Console 3-11 Navigation Menu 3-12 Status Bar 3-12 Property Pages 3-12 Using Subpolicies to Organize the Policy 3-13 Adding Firewalls to the Manager s Control 3-13 Adding Firewalls to the Default Cluster 3-14 Logging Out of the Console Securely 3-15 Working with Virtual Web Applications 4-17 Creating a Virtual Web Application 4-17 Creating the Virtual Web Application Using Basic Virtual URL 4-18 Creating the Virtual Web Application using Custom Virtual URL With Filters 4-21 Using Monitor Mode 4-23 Creating Modifiers 4-25 Creating Modifiers Directly 4-25 Creating Incident-Based Modifiers 4-26 iii

4 Contents Working with Profiles 5-29 About Profiles 5-29 Built-In Profiles 5-30 Pass-through Profile 5-30 PCI Compliance 5-30 New Profile 5-30 Active Security Features 5-31 HTTP Header Processing 5-32 HTTP Exception Mapping 5-35 Referrer Enforcement 5-37 HTTP Cookie Security 5-37 Data Overflow Defense 5-40 Message Rewrite Rules 5-41 Message Inspection Rules 5-42 Developing Rules and Signatures 6-45 Overview 6-45 Message Normalization 6-46 Passive Normalization 6-46 normalize() Function 6-47 Developing Signatures 6-49 Viewing Existing Signatures 6-50 Basic Example 6-50 About the Quick Pattern 6-51 Built-In Signature Notes 6-52 Uploading Custom Signatures 6-52 General Signature Development Guidelines 6-53 Signature Syntax 6-53 Sample Signature File 6-54 Developing Rules 6-55 Viewing Existing Rules 6-56 Uploading Custom Rules 6-56 General Rule Development Guidelines 6-57 Rule Syntax 6-58 Rule Group Declaration 6-58 Message Inspection Rule Format 6-59 Message Rewrite Rule Format 6-59 Rule Statement Format 6-60 iv

5 Contents XML Threat Defense 7-67 About XML Threat Defense 7-67 Tuning Threat Defense Settings 7-67 Working with Ports and Hostnames 8-69 About HTTP Ports 8-69 Opening a Port 8-70 Listening on a Virtual Hostname 8-71 Configuring a Static Content Response 8-72 Configuring Destination Server Settings 9-75 About Destination Servers 9-75 Working with Destination HTTP Servers 9-75 Adding a Destination HTTP Server 9-76 Integrating with ACE Application Switches 9-77 Setting Up the Cisco ACE Virtual Device Connection 9-78 Generating Server Definitions from VIPs 9-79 Using an HTTP Echo Server 9-80 Removing a Server Definition 9-81 Securing Traffic with SSL/TLS About SSL/TLS Traffic Encryption Securing the Service Consumer Connection Securing the Service Provider Connection Managing Resource Files Types of Resource Files Generating a CSR Uploading a Keypair Resource Uploading a Certificate Authority Resource Deploying the Policy Deployment Overview Who Can Deploy Policies Deploying a Policy Selectively Rolling Back Policy Changes Reloading URL-Based Resources at Deployment Approval-Based Deployment Enabling Approval-Based Deployment v

6 Contents Viewing Approval Status and Requests Approved Policy Status Approval Request Status for Active Subpolicy Requesting Approval of Policy Changes Approving or Rejecting Policy Changes Deploying an Approved Policy Managing the Policy About Policies Working with Subpolicies About the Shared Subpolicy Creating a Subpolicy Changing the Active Subpolicy Deploying from a Subpolicy Deleting a Subpolicy Copying Objects Between Subpolicies Reorganizing the Policy Migrating Policy Objects Exporting and Importing Policies with PPF Files Exporting the Policy to a PPF Importing a Policy Miscellaneous Policy Administration Tasks Saving a Policy to the Archive History Restoring a Policy Comparing Policy Versions Automated Policy Review Discarding Policy Changes Policy Statistics Information Clearing the Policy History Policy Component Search by ID Monitoring System Status About Logged Information Event Logging Configuring Event Logging Client IP Logging Viewing the Event Log Monitoring Performance Filtering Performance Data by Time Viewing Performance Information vi

7 Contents Exporting Performance Information to a File Managing Web Console Users About Console Users Types of Web Console Users About the Administrator User Authentication Modes Creating User Accounts Changing User Roles Enabling Access to Subpolicies Setting the Authentication Mode Switching to LDAP Authentication Mode Switching to RADIUS Authentication Mode Switching to Local Authentication Mode Managing Firewall Clusters About Multiple Cluster Management What is the Default Cluster? Considerations for Using Multiple Clusters Working with Clusters Creating a Cluster Editing a Cluster Removing a Cluster Configuring the Manager Web Console Changing the Manager SSL Certificate Generating a CSR for the Manager Setting the Manager SSL Certificate Prompting URL-Based Resource Reload at Deployment Configuring User Idle Time-Out Settings Configuring Failed Login Attempt User Blocking Setting the Display Time Zone vii

8 Contents viii

9 Preface This preface contains the following major sections: Audience, page ix Organization, page ix Related Documentation, page x Obtaining Documentation and Submitting a Service Request, page xi Conventions, page xi Notices, page xii Audience This guide describes how to use the ACE Web Application Firewall Manager web console, the browser-based interface for configuring and administering the ACE Web Application Firewall and Manager. It is intended for the following personnel who are responsible for configuring, monitoring, and maintaining the Firewall: System administrator System operator Policy developer Organization This guide includes the following sections: Title Chapter 1, Introducing the Cisco ACE Web Application Firewall Chapter 2, Securing Web Applications Description Introduces the ACE Web Application Firewall and Manager, and describes how their capabilities can be used to secure backend web applications. Explains background concepts important for understanding how to configure and operate the ACE Web Application Firewall. ix

10 Preface Title Chapter 3, First Steps Chapter 4, Working with Virtual Web Applications Chapter 5, Working with Profiles Chapter 6, Developing Rules and Signatures Chapter 7, XML Threat Defense Chapter 8, Working with Ports and Hostnames Chapter 9, Configuring Destination Server Settings Chapter 10, Securing Traffic with SSL/TLS Chapter 11, Managing Resource Files Chapter 12, Deploying the Policy Chapter 13, Managing the Policy Chapter 14, Monitoring System Status Chapter 15, Managing Web Console Users Chapter 16, Managing Firewall Clusters Chapter 17, Configuring the Manager Web Console Description Lists procedures for accessing the ACE Web Application Firewall Manager web console, the development environment for the policy, and getting started configuring service routing in the ACE Web Application Firewall policy. Describes how to use virtual web application to secure web traffic. Details how to use profiles to define rules for securing and processing a class of traffic. Provides information on creating your own custom rules and signatures for web application security. Describes how the ACE Web Application Firewall can protect against XML-based security threats. Describes how to open HTTP listening ports. Describes how to set up virtual hosting for the Firewall. Provides information on configuring settings for backend server connections. Describes how to set up the consumer and backend service connections from the ACE Web Application Firewall to use Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL). Lists the types of resources used in an Firewall policy. Describes how to deploy the working policy in the ACE XML Manager web console to the ACE Web Application Firewall, where it is applied to network traffic. Explains how subpolicies can be used to organize large, complex policies. Lists the steps for exporting and importing policies as PPF files, as well as how to move objects between policies and subpolicies. Overviews the capabilities of the system for providing information on the activities of the system. Provides information on the user accounts and roles in the ACE XML Manager web console. Describes how to create and manage multiple clusters of ACE Web Application Firewalls from a single Manager. Lists and describes the configuration settings that control the behavior and appearance of the ACE XML Manager web console interface. Related Documentation For additional information on the Cisco ACE Web Application Firewall software, see the following documentation: Cisco ACE Web Application Firewall Getting Started Guide x

11 Preface Cisco ACE Web Application Firewall Administration Guide In addition, online help is available from the ACE Web Application Firewall Manager web console. The following sections provide sources for obtaining documentation from Cisco Systems. Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: Subscribe to the What s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0. Conventions This document uses the following conventions: Convention Indication bold font Commands and keywords and user-entered text appear in bold font. italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font. [ ] Elements in square brackets are optional. {x y z } Required alternative keywords are grouped in braces and separated by vertical bars. [ x y z ] Optional alternative keywords are grouped in brackets and separated by vertical bars. string A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks. courier font Terminal sessions and information the system displays appear in courier font. < > Nonprinting characters such as passwords are in angle brackets. [ ] Default responses to system prompts are in square brackets.!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line. Note Means reader take note. Caution Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data. xi

12 Preface Warning Means reader be warned. In this situation, you might perform an action that could result in bodily injury. Notices The following notices pertain to this software license. OpenSSL/Open SSL Project This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( This product includes cryptographic software written by Eric Young This product includes software written by Tim Hudson License Issues The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the OpenSSL License and the original SSLeay license apply to the toolkit. See below for the actual license texts. Actually both licenses are BSD-style Open Source licenses. In case of any license issues related to OpenSSL please contact openssl-core@openssl.org. OpenSSL License: Copyright The OpenSSL Project. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( 4. The names OpenSSL Toolkit and OpenSSL Project must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org. 5. Products derived from this software may not be called OpenSSL nor may OpenSSL appear in their names without prior written permission of the OpenSSL Project. 6. Redistributions of any form whatsoever must retain the following acknowledgment: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit ( THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT AS IS ' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN xii

13 Preface NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This product includes cryptographic software written by Eric Young This product includes software written by Tim Hudson Original SSLeay License: Copyright Eric Young All rights reserved. This package is an SSL implementation written by Eric Young The implementation was written so as to conform with Netscapes SSL. This library is free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson Copyright remains Eric Young s, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). The word cryptographic can be left out if the routines from the library being used are not cryptography-related. 4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: This product includes software written by Tim Hudson (tjh@cryptsoft.com). THIS SOFTWARE IS PROVIDED BY ERIC YOUNG AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. xiii

14 Preface The license and distribution terms for any publicly available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution license [including the GNU Public License]. xiv

15 CHAPTER 1 Introducing the Cisco ACE Web Application Firewall This chapter introduces the Cisco ACE Web Application Firewall. It covers these topics: Securing Web Applications, page 1-1 Deployment Environment, page 1-2 About the ACE Web Application Firewall Manager, page 1-2 Securing Web Applications The Cisco ACE Web Application Firewall, a member of the Cisco Application Control Engine (ACE) family of products, helps to ensure the security of your web application. The Cisco ACE Web Application Firewall is a reverse proxy that protects important backend resources from security threats or misuse. It provides a traffic inspection and processing layer between the application and its users, so that security policies can be defined and maintained across the network. While traditional firewalls operate on messages at the envelope level, the Cisco ACE Web Application Firewall can look inside the message body. It can identify, block, or rewrite messages with harmful content based on the rules in its policy. The ACE Web Application Firewall includes built-in rules for preventing many common types of attacks and threats to a system. Its built-in capabilities help you meet a range of requirements for backend web application security, including those specified by the Payment Card Industry (PCI) Data Security Standard. The Cisco ACE Web Application Firewall secures web application traffic as directed by its policy. Two key components in the policy for securing web application traffic are signatures and rules. A signature is a content pattern that identifies content of interest to the Cisco ACE Web Application Firewall. The signature is applied to message traffic by a rule, which also indicates the portion of the message to be inspected for a signature match, along with other properties. The Cisco ACE Web Application Firewall includes a library of built-in rules and signatures you can use to secure your web application and its users. Built-in rules exist for stopping many common types of attacks and threats to a system, such as cross-site scripting attacks, SQL and LDAP injection attacks, and command injection attacks. Content screening rules help to ensure that sensitive credit card information is not inappropriately emitted by backend applications. 1-1

16 Deployment Environment Chapter 1 Introducing the Cisco ACE Web Application Firewall Deployment Environment A deployed Cisco ACE Web Application Firewall resides in the network between clients and backend applications you want to protect. For high availability, multiple appliances should reside behind a load balancer. In processing traffic, the ACE Web Application Firewall receives requests from clients, applies the policy to them, and passes qualifying requests to the destination server. As a full reverse proxy, the ACE Web Application Firewall appears as the client to the backend system and the server to the client. The backend server directs responses through the ACE Web Application Firewall. The ACE Web Application Firewall can ensure that responses do not contain sensitive information. The Cisco ACE Web Application Firewall ensures that security policies are applied across application consistently, in an easily auditable way. It does not impose requirements to change the client or backend application. When it detects content of interest, it can block the message, modify the content, or simply log the event. In generally, it modifies messages only as specified by message processing configuration. When message content matches a signature applied by a rule, the message can be blocked, modified, or passed through with an event log. About the ACE Web Application Firewall Manager The policy development and administration interface for the system is the ACE Web Application Firewall Manager web console. The web console is a browser-based development environment for the ACE Web Application Firewall policy. It includes tools and capabilities that significantly ease the task of deploying the system to your network and configuring traffic processing. 1-2

17 CHAPTER 2 Securing Web Applications This document describes how to secure Web applications with the Cisco ACE Web Application Firewall. It covers these topics: Overview Web Application Policy Components Policy Development Steps for Web Application Security Extending Rules and Signatures Message-to-Handler Matching Monitoring Web Application Security Activity Overview You secure a backend web application by creating a virtual web application object for it in the policy. A virtual web application associates a particular backend application with a set of rules and processing actions to be applied to traffic for the application. A request can be matched to only one virtual web application in the policy. Clients access an application proxied at the Firewall by sending requests to the consumer interface defined for the application in the policy. Only traffic that matches the traffic filtering criteria of a virtual web application at the ACE Web Application Firewall is accepted. All other traffic is dropped. The ACE Web Application Firewall can validate and process the request in a variety of ways. It can look for potentially harmful content in the request, such as character patterns that indicate a potential command injection attack or cross-site scripting attack. It can also add or remove HTTP headers, validate cookies, and perform other tasks. Once the message is validated and processed, it is forwarded to the backend application. From the backend application s perspective, the ACE Web Application Firewall is a full reverse proxy; the application views the ACE Web Application Firewall as the source of requests. (If needed, the ACE Web Application Firewall can use an HTTP header such as X-Forwarded-For to identify the actual message source to the backend system). When the ACE Web Application Firewall gets back the response, it can similarly inspect and process the response, for example, by screening sensitive information, encrypting cookies, or mapping error responses. A virtual web application policy object determines how traffic is processed for an external web application. It is made up of these key features: The consumer request filter, which selects incoming requests for this virtual web application to handle. 2-3

18 Web Application Policy Components Chapter 2 Securing Web Applications A profile reference, which determines the validation and processing measures applied to traffic for this virtual web application. A server reference, which determines the destination of outgoing requests. In the Cisco ACE Web Application Firewall policy, each virtual web application definition belongs to a virtual web application group. Groups make it easier to administer multiple related virtual web applications. They also provide an organizational unit for logging and reporting purposes. In the Web App Firewall Incidents report, for instance, you can screen the display to show only events applicable for a given group. Web Application Policy Components Before you start developing the Firewall policy for web application security, you should be familiar with the policy components used to secure web applications. Message Rules A rule is a policy component that represents a single check to be performed on a message. It identifies the part of the message to be checked and the signature used to perform the check. There are two types of rules: A message inspection rule checks messages for particular content and, if matched, acts upon the entire message (by blocking the message or allowing it to pass with an event logged). This type of rule is generally used for identifying and blocking harmful messages. A content rewriting rule can change matched content in a message with a replacement character. This type of rule helps to ensure that private information is not being inappropriately emitted by a backend system. Signatures A rule is applied to message based on a match of a signature to the message content. A signature is a pattern that is applied to message content to match content of interest. As with rules, signatures are organized by groups. Signatures match traffic content through either a fixed set of characters, including numbers and characters, or through a regular-expression pattern. Profiles A rule is applied to a class of traffic at the Firewall by a profile. A profile is a named collection of rule group and active security settings. A profile indicates which rule groups are enabled in the context of the profile (other profiles may enable rules differently) and values for their configurable settings. Configurable rule settings include, for example, the action to be performed of a rule match. A profile is applied to traffic from a virtual web application configuration. Virtual Web Applications A virtual web application is the primary policy object for securing traffic for a specific backend application. It associates traffic for a particular backend application to a set of rules and actions for processing and securing message traffic. 2-4

19 Chapter 2 Securing Web Applications Policy Development Steps for Web Application Security Modifier A virtual web application can contain modifiers. Like a virtual web application, a modifier applies rules and security actions to selected traffic. However, a modifier selects traffic only from the traffic handled by the virtual web application. A modifier applies traffic processing settings to a subset of the traffic handled by the containing virtual web application. They are typically used to define an exemption to the rules defined in the virtual web application. Policy Development Steps for Web Application Security Developing a policy for web application security is typically an iterative process, with repeated steps for development, testing, and deploying. In general, the workflow for developing an effective policy will follow this order: 1. Construct the initial profile. Generally, you should start with a profile that is stricter than needed, and add leniency to the profile as guided by testing (if in doubt, you should start with a copy of PCI compliance). 2. Create virtual web applications that use the profile in monitor mode. (You may choose to enable the option to create new virtual web application in monitor mode.) 3. Deploy the policy. 4. Test the policy by sending a large volume of expected traffic to the web application through the ACE Web Application Firewall. Because traffic inspection is in monitor mode, no requests are blocked. 5. Check the incident report to see which rules caused the most incidents. Identify the false positives from the incidents and modify the profile as needed to avoid the false positive by disabling or exempting unneeded rules or signatures. 6. Repeat this process as many times as needed to reduce the possibility of false positives while maintaining security. Once the policy is deployed to the production environment, it is important to monitor the incidents report for false positives or possible malicious activity. Extending Rules and Signatures The Cisco ACE Web Application Firewall includes a library of built-in rules and signatures you can use to secure your web application and its users. Built-in rules exist for stopping many common types of attacks and threats to a system, such as cross-site scripting attacks, SQL and LDAP injection attacks, and command injection attacks. In addition, you can supplement the built-in rules and signatures with ones you create. The ACE Web Application Firewall system includes a rule and signature writing syntax that allows you to extend the system with application-specific rules and signatures. Message-to-Handler Matching An incoming request is matched to a given virtual web application based on the consumer interface defined for the application at the ACE Web Application Firewall. To avoid message matching ambiguity, the Manager prevents you from configuring two virtual web applications with identical consumer interfaces. However, through the use of prefix matching, regular expressions, or other consumer interface filtering conditions, it s possible to configure a policy in which multiple virtual web applications can be matched by a single request. 2-5

20 Monitoring Web Application Security Activity Chapter 2 Securing Web Applications When a message matches more than one virtual web application, the application with the more specific consumer interface wins. For the virtual URL, for instance, this means that the consumer interface with the longer path wins. That is, given two virtual web applications that use prefix matching with these URLs: Requests to will be handled by the first virtual web application, even though it matches the second as well. For applications with identical virtual URLs, other consumer interface features can be used to determine specificity, including: HTTP method GET/POST parameters HTTP headers In determining specificity based on these properties, the ACE Web Application Firewall follows these guidelines: 1. Exact match paths between the request URL and consumer interface URL are always considered the most specific. 2. Prefix and regular expression paths are compared by length, with longer paths considered more specific. 3. If the virtual URL cannot be used to make the determination, then parameter and HTTP header matching criteria are considered. The consumer interface that defines more parameters or HTTP header requirements is considered more specific. If a multiple handler match for a message cannot be resolved by the specificity preference, the ACE Web Application Firewall chooses one of the matching handlers, although how the ambiguity is resolved cannot be predicted at policy design time. In general you should avoid configuring the policy in a way that introduces ambiguous handler matches. Monitoring Web Application Security Activity The monitoring tools in the ACE Web Application Firewall system give you broad visibility on its message processing activities. At policy-development time, the monitoring tools help you create an effective policy and troubleshoot interoperability issues. After the policy is deployed to the production environment, the monitoring tools are important for identifying threats to your network and for evaluating workload on network and application resources. The ACE Web Application Firewall presents information on web application security activities in several forms. The traffic monitor graphs on the Dashboard page provide dynamic information on traffic handling rates by handler. The service health summary displays a high-level view of web application security incidents. An incident is any event in which a web application profile feature, such as a message inspection rule message rewrite rule, or active security feature, is applied to a message in monitor or enabled mode. The Dashboard provides an overview of system activities and events. For greater detail, you can use the event log and web application firewall incidents report. The event log provides detailed information on all system activities. The web app firewall incidents page, on the other hand, displays statistical information specifically on the web application security activities of the Cisco ACE Web Application Firewall. 2-6

21 Chapter 2 Securing Web Applications Updating the Base Configuration The incidents report shows how many messages have been received at a particular virtual web application and how many times a particular rule applied by it has been triggered. It lets you quickly determine the types of threats that are seen at the ACE Web Application Firewall and where they are directed. Note that a virtual web application or rule can operate in monitor mode. When a message is processed in monitor mode, all rules it violates are reported. On the other hand, in enabled mode, the message is rejected at the first instance in which a blocking rule is triggered; it is not further evaluated against other rules in the profile. This means that the event log or incidents report will show only the rule that caused the message to be blocked and not any other rules that it may have violated had processing continued. Note The incidents report only displays information on the most recent 24,000 events. When this limit is exceeded, information on oldest events is not represented in the statistics. If archiving historical information is important in your deployment, be sure to regularly export the incidents information to a file from the Web App Firewall Incidents page. To use the incidents report, click the Web App Firewall Incidents link in the navigation menu. In the page, you can set the view as follows: URL Shows the statistics organized by client request URL. Virtual Web App Shows statistics organized by virtual web application objects in the policy. Web App Group Shows statistics organized by virtual web application group. Rule Set Shows statistics organized by rule group. Note that incidents related to virtual web applications that have subsequently been removed from the policy are only reflected in the statistics in rule set sorting. When the display is sorted by URL or virtual web application, incidents for virtual web applications that have been removed from the policy are not reflected in the statistics. You can also filter the view by time, showing statistics that occurred between a particular time range you specify. The Export Raw Data button allows you to export the information in the display to a file for archiving or analysis purposes. It writes the statistics to either a comma-separated values file or an XML-formatted file. Note that the exported data reflects the time frame selection currently in the page. Note When viewing incident reports, note that handlers that have been moved between subpolicies are identified by internal object number, rather than by handler name, for their activity in the former subpolicy. Updating the Base Configuration The base configuration contains the built-in artifacts and resources used in the Cisco ACE Web Application Firewall to secure web applications, including built-in signatures, rules, and profiles. Cisco may occasionally issue updates to the base configuration or certify base configuration updates by third parties. The updates will generally contain enhancements or extensions to the built-in signatures, rules, and profiles. Applying a base configuration update introduces the new rules and signatures to your system. 2-7

22 Updating the Base Configuration Chapter 2 Securing Web Applications Base configuration updates should only be performed with Cisco-certified base configuration files. This feature is not intended for uploading user-created files. A base configuration package consists of a signed archive file that contains the new base configuration data. To apply a new base configuration, in the Rules & Signatures page, click the Update Base Configuration button. In the Update Base Configuration page, load the base configuration update file. Updating the base configuration does not affect your existing policy settings. That is, current settings that rely on built-in signatures, rules, and profiles will remain in place after the base configuration update has been applied. Base configurations have a version identifier in the format YYYYMMDDXX, where: YYYY is the year of issue MM is the month number of issue with leading zero DD is the day number of issue with leading zero XX is a 2-decimal digit counter of issues within day When you upload a base configuration, the Manager makes sure that the base configuration you are installing was issued after the one that is already installed. If it was not, the Manager warns you but does not prevent you from loading the older base configuration file. However, updating a new base configuration with an older one is not recommended. It will result in compilation errors in configurations that rely on rule or signatures from the newer base configuration. 2-8

23 CHAPTER 3 First Steps This chapter introduces the ACE Web Application Firewall Manager web console. It covers these topics: Logging In to the Manager Web Console, page 3-9 Navigating the Manager Web Console, page 3-11 Using Subpolicies to Organize the Policy, page 3-13 Adding Firewalls to the Manager s Control, page 3-13 Logging Out of the Console Securely, page 3-15 Logging In to the Manager Web Console Once the ACE Web Application Firewall Manager is installed on your network, you can log into the browser-based environment for developing the ACE Web Application Firewall policy, the ACE Web Application Firewall Manager web console. The ACE Web Application Firewall Manager web console works with recent versions of most types of browsers. It is specifically supported on Mozilla Firefox x and x and Microsoft Internet Explorer 5.5 and 6. JavaScript functionality must be enabled in the browser for many ACE Web Application Firewall Manager web console features to work properly. To log in to the ACE Web Application Firewall Manager web console: Step 1 On a computer accessible by network to the ACE Web Application Firewall Manager appliance, open a browser and go to the following address: Where <hostname> is the IP address or hostname of your ACE Web Application Firewall Manager. Notice that secure HTTP (HTTPS) is used for the connection and the default port on which the ACE Web Application Firewall Manager listens for console requests is The browser displays the login page, as shown in Figure

24 Logging In to the Manager Web Console Chapter 3 First Steps Figure 3-1 ACE Web Application Firewall Manager web console login Step 2 Step 3 The hostname for the ACE Web Application Firewall Manager is configured at initial installation time. If you don't know the path to the login page for your installation, ask your administrator. Other users who are already logged into the web console are listed on the login page. It is important to note when other users are logged into the console. The ACE Web Application Firewall Manager does not prevent you from overwriting each others' changes (the last save wins if a single settings page is edited by multiple users at the same time). For this reason, it is important that you check your work carefully and test new policies in a testing environment before deploying them to production. If this ACE Web Application Firewall Manager is used to administer multiple clusters of ACE Web Application Firewalls, a menu may appear that allows you to choose which cluster policy you want to access. In this case, choose the name of the cluster to edit from the menu. Enter your username in the Username field. For example, if you are the administrator, enter administrator in this field. This is a preconfigured user account with full privileges to the console. Note For details on adding user accounts for the ACE Web Application Firewall Manager web console, see Chapter 15, Managing Web Console Users. Step 4 Enter the password in the Password field. Note The default password for the Administrator user is swordfish. For security reasons, be sure to change the default password. Step 5 Click the Log In button. If you do not enter a valid username and password combination, an error message appears. Depending on how your administrator has configured Manager access, you may have a limited number of failed login attempts before the ACE Web Application Firewall Manager exits unconditionally and disables the user account (three, by default). This security feature applies to all user accounts except the administrator user account. (It does apply to user accounts created with the administrator user type). For information on this feature and restoring a user account, see Configuring Failed Login Attempt User Blocking section on page

25 Chapter 3 First Steps Navigating the Manager Web Console If you enter a valid username/password combination, one of several pages may appear: The license error page appears if a license has not yet been configured for the ACE Web Application Firewall Manager. See the Cisco ACE Web Application Firewall Administration Guide for more information on acquiring and applying licenses for the ACE Web Application Firewall and Manager. The Welcome page appears if the ACE Web Application Firewall Manager has a valid license and the policy is not yet configured for service routing. From the Welcome page, you can start defining virtual services. If the policy contains virtual services, the Dashboard page appears. The Manager Dashboard provides an overview of system events and activities. It is recommended that you change the password from the one assigned to you upon first login. To do so, click on your username at the top right of the page. In the User Information window, click the Change Password button to specify a new password. By default, the console requires passwords to meet a minimum level of complexity. The password must be at least eight characters long, it should not consist of a dictionary word as more than a minimum percentage of the overall password, and it should not resemble a social security number or national ID number. In general, it is recommended that you use a combination of letters, numerals, and special characters in your password. Navigating the Manager Web Console Figure 3-2 shows the main parts of the ACE Web Application Firewall Manager web console interface. Figure 3-2 ACE Web Application Firewall Manager Dashboard 3-11

26 Navigating the Manager Web Console Chapter 3 First Steps As shown in Figure 3-2, the ACE Web Application Firewall Manager web console is organized into these areas: Navigation Menu Status Bar Property Pages Navigation Menu The navigation menu appears at the left side of the console. It provides links to the primary settings and monitoring pages in the console, organized into these categories: Policy section contains links for pages for defining the rules and processing operations applicable to traffic handled by the ACE Web Application Firewall. Resources section links to pages for managing the resource files used in the policy. For more information, see Chapter 11, Managing Resource Files. Reports & Tools links to pages for monitoring the status of the ACE Web Application Firewall and the network. Administration has links to pages that allow console administrators to control the ACE Web Application Firewall Manager itself, for example, for licenses, user accounts, audit logging, and diagnostics. The Quick Links button ( ) appears next to the Policy heading of the navigation menu. It provides access to common tasks, including importing a WSDL file, creating a virtual service, and creating an authenticator (the policy object used to control access to services). Status Bar The status bar appears at the top of every page in the console. It displays the currently active subpolicy and the username of the user account currently accessing the console. It provides buttons for common operations in the console, such as deploying the policy and logging out. Administrator users can configure banner text that appears in the status bar, for example, to post notifications or other types of information for other console users. A subpolicy is a container for organizing objects within a policy. The Shared subpolicy is a built-in subpolicy that s present whether or not you are using subpolicies to organize your work. It contains the common objects used throughout all subpolicies. If subpolicies besides Shared exist in the policy in your environment, the Switch button appears next to the subpolicy label. Click the Switch button to change your working context to another subpolicy. For more information on subpolicies, see Working with Subpolicies section on page Property Pages A property page displays information or settings for a particular area of the system s operations. In general, the property page provides access to the configuration controls for any configurable settings associated with the feature. 3-12

27 Chapter 3 First Steps Using Subpolicies to Organize the Policy Using Subpolicies to Organize the Policy You can organize related objects in a policy with subpolicies. A subpolicy is a subset of the objects in a given policy. Access to subpolicies can be controlled, so that only console users with privileges to a subpolicy can make changes to it. The system includes a built-in subpolicy named Shared. When you first log in to the web console for a newly installed ACE Web Application Firewall Manager, the Shared subpolicy is active. The Shared subpolicy is the only subpolicy whose objects that can be accessed from other subpolicies. Otherwise, settings and objects cannot be used across subpolicies. The best organizational strategy for subpolicies that is, how you choose which objects are created in particular subpolicies or in Shared will likely vary from one implementation to another. In general, however, the Shared subpolicy should hold resources needed across projects, such as port settings, certificate authorities, common back-end HTTP servers, and so on. Subpolicies, on the other hand, usually hold application-specific objects, such as virtual services and authentication objects. If subpolicies are used in your policy, it is important to be aware of which subpolicy is active in the ACE Web Application Firewall Manager web console before making configuration changes or adding policy objects. When you create a policy object in a given subpolicy, it will be editable only in the context of that subpolicy, and only by users who have privileges to modify that subpolicy. Subpolicies help you to manage and secure your policy development environment. Approval-based deployment provides a similar benefit. With approval-based deployment, a console administrator must approve a policy deployment for it to be propagated to the ACE Web Application Firewalls. This feature helps to control and manage the policy change and deployment process. While subpolicies provide a means of organizing objects within a policy, large implementations may require the use of different policies to partition work. The multiple cluster management feature of the ACE Web Application Firewall Manager allows you to develop different policies in a given ACE Web Application Firewall Manager instance and deploy them to different ACE Web Application Firewall clusters. Adding Firewalls to the Manager s Control As described in the Cisco ACE Web Application Firewall Administration Guide, an ACE XML appliance can operate in one of three modes: in gateway, manager, or standalone mode (in which the appliance operates as both gateway and manager mode). For a standalone appliance, after initial configuration, the ACE Web Application Firewall Manager is already configured for self-management (that is, an entry for itself exists in the Manager s managed Firewall list). You can start working on the policy immediately, without having to add Firewalls to the configuration. However, if the appliance is in Manager-only mode, you will need to add a Firewall to the Manager s administrative control before you can deploy and test a policy, as described here. Note For a standalone appliance, the ACE Web Application Firewall Manager can control other Firewall appliances as well as its own Firewall instance. Therefore, these steps are also applicable if you want to add Firewalls to the administrative control of a Manager on a standalone appliance. An ACE Web Application Firewall should not be configured to be in the control of more than one ACE Web Application Firewall Manager at a time. This restriction applies to management by actual Manager appliances or Manager instances created with the Multiple Cluster Management feature. 3-13

28 Adding Firewalls to the Manager s Control Chapter 3 First Steps The general steps for adding a Firewall to the Manager s control are: 1. When configuring the operating mode of the Firewall from the appliance shell interface, specify the IP address of the Manager that is to control this Firewall. Note For more information, see the Cisco ACE Web Application Firewall Administration Guide. 2. In the web console for the ACE Web Application Firewall Manager, add the Firewall to one of the Manager s cluster pools, such as to its default cluster. 3. Check the licensing status of the added ACE Web Application Firewall in the web console. If needed, request and apply a license. This section describes step 2, how to add a Firewall to one of the Manager s clusters. Once the Firewall belongs to a cluster group, it can receive policy deployments from the Manager. In turn, the Firewall reports on its activities back to the Manager, which aggregates logging information for all Firewalls in its control. For more information on steps 1 and 3, see the Cisco ACE Web Application Firewall Administration Guide. Note An ACE Web Application Firewall Manager can control more than one cluster of Firewalls. While all Firewalls in a single cluster should have the same policy version, multiple clusters in the Manager s control can apply different policy versions. For more information, see Chapter 16, Managing Firewall Clusters. Adding Firewalls to the Default Cluster To add an ACE Web Application Firewall to the Manager s control, you add it to a cluster in the Manager configuration. As noted, you do not need to perform these steps for a standalone appliance; they are needed only if configuring a Manager-only appliance or to add additional Firewalls to a standalone appliance s administrative control. The Manager comes with a preconfigured cluster named Default Cluster to which you can add ACE Web Application Firewalls. Notice that you can rename the default cluster and make other changes to its settings. You should not add new clusters to the Manager configuration unless you specifically intend to maintain separate ACE Web Application Firewall environments. For more information, see Chapter 16, Managing Firewall Clusters. To add an ACE Web Application Firewall to the default cluster: Step 1 Step 2 Step 3 As a user with administrator privileges in the Manager web console, click the Cluster Management link from the navigation menu. The cluster management page should show a cluster named Default Cluster. On the Manager of a standalone mode appliance, the Default Cluster lists this appliance as the only member. Otherwise, new installations will show the default cluster as empty. Add the Firewall to the cluster by clicking the edit link next to the Default Cluster. Optionally, modify the preconfigured settings for the default cluster, such as its name and HTTPS port and the security certificate used for SSL access to the Manager web console. The SSL Certificate shown on this page applies to the connection from a web browser to the Manager web console. As indicated in the menu, the Manager provides a temporary certificate that is used by default. It is recommended that you replace the built-in certificate with a server certificate you generate. 3-14

29 Chapter 3 First Steps Logging Out of the Console Securely Step 4 Step 5 Step 6 If the Manager and development workstations will be operating within a secure network, you may choose to use a self-signed certificate. However, for greater security it is recommended that you use a CA-signed certificate, particularly if the cluster is deployed in a production environment. You can generate a new certificate to use for the browser connection by clicking the Manage SSL Certificates button on the Cluster Management page. From there, use the Generate CSR button to generate a certificate signing request. For more information, see Generating a CSR section on page Once the server certificate is generated and uploaded in the Manager, choose it from the menu on this page to apply it to the browser connection. In the Cluster Members text field, type the IP address and administration port of each ACE Web Application Firewall you want to add to this cluster. The address for each Firewall should be on its own line in the text field, such as: The administration port used by the Manager and Firewall to exchange administrative information, such as log events, is If you have a specific network prerequisite that prevents you from using it, you can specify another port by appending it to the IP address. Click Save Changes. After being added to a cluster, the Firewall usually needs to be configured with a license. To check the license status of the Firewall, open the License Management page in the web console. If a license is required for the Firewall, refer to the Cisco ACE Web Application Firewall Administration Guide for information on acquiring and applying product licenses to the appliance. The ACE Web Application Firewall should appear as a member of the cluster in the Cluster Management page. You can now deploy the policy from the ACE Web Application Firewall Manager to the ACE Web Application Firewalls in its control. For more information on working with clusters, see Chapter 16, Managing Firewall Clusters. Logging Out of the Console Securely For security reasons, it is extremely important that you do not leave any user session with the ACE Web Application Firewall Manager web console unattended. After using web console, you should log out and close all browser windows you used. If you do not, other users could view pages cached by your browser during the user session. Take the following steps to log out of the ACE Web Application Firewall Manager securely: Step 1 Step 2 Step 3 Click the Logout button. In the confirmation dialog, click the OK button to log out. Close all browser windows used in your console session. For additional security, clear your browser's cache after you log out of the ACE Web Application Firewall Manager. 3-15

30 Logging Out of the Console Securely Chapter 3 First Steps 3-16

31 CHAPTER 4 Working with Virtual Web Applications This chapter describes how to configure web application security. It covers these topics: Creating a Virtual Web Application Using Monitor Mode Creating Modifiers Creating a Virtual Web Application A virtual web application applies a set of rules and security operations to a particular class of traffic. In general, a single virtual web application will need to be added to the policy for each actual backend web application you want to protect. However, the exact correspondence between virtual web applications and the actual backend application will vary based on the nature of the application. In creating a virtual web application, you define the consumer interface that selects messages to which it applies. To avoid message matching ambiguity, the Manager prevents you from configuring two virtual web applications with identical traffic filtering criteria. However, through the use of prefix matching, regular expressions, or other overlapping filtering conditions, it is nevertheless possible to deploy multiple virtual web applications that can be matched by a single message. When a message is compatible with multiple virtual web applications, the one with the more specific consumer interface wins. In terms of the consumer interface, more specific means, for instance, a virtual URL that has a longer path or a greater number of selection parameters. There are two basic modes in which you can create a new virtual web application: Using the Basic Virtual URL option, in which the Manager automatically generates various settings for the consumer interface for the virtual web application based on the URL you enter. Using the Custom Virtual URL with Filters option, which provides fine grain control of the consumer interface generated for the virtual web application, including the ability to select traffic based on parameter or HTTP header values. The virtual URL and request filter settings comprise the client interface for the virtual web application. If advanced traffic selection criteria are not required for this application, such as request parameter filtering, you can use the Basic Virtual URL menu option to configure the interface. Note that the settings provided by the custom virtual URL option are available for a virtual web application created using the basic virtual URL option. Therefore, in most cases, it will make sense to create the virtual web application in basic virtual URL mode and modify its advanced filtering properties later, if needed. 4-17

32 Creating a Virtual Web Application Chapter 4 Working with Virtual Web Applications Messages to virtual web applications are processed by the Reactor processing engine. When configuring a virtual web application, it is important to keep this in mind they are compatible only with Reactor-enabled port and server definitions in the policy. Port or server definitions that are configured to use Flex Path only are not available in the user interface when assigning these attributes to a virtual web application. A policy compilation error is generated if, after the virtual web application is created, its port or server definition is changed to use Flex Path. Creating the Virtual Web Application Using Basic Virtual URL To create a new virtual web application using the basic virtual URL mode: Step 1 Step 2 Step 3 Click the Virtual Web Applications link in the navigation menu. Click the New Virtual Web Application button to create a new virtual web application definition in the policy. A virtual web application encapsulates settings for a particular backend application for which you want to process and validate traffic at the ACE Web Application Firewall. Configure the virtual web application using the information in the following table: Table 4-1 Virtual Web Application settings Label Name Web App Group Description A descriptive name used to identify this virtual web application definition in the policy. This name must be unique for virtual web applications in the policy. This name will appear in log descriptions for events associated with this virtual web application, so it should be sensible for users of the event log. The group in which this virtual web application should be created. You can choose from an existing group listed in the menu or create a new group for the application by choosing new Web App Group and typing a name for the group. In general, a group should hold all virtual web applications that need to be managed and monitored together. Management operations that can be performed on a group include operating mode setting and virtual web application disabling. Groups are a reference point for monitoring as well, since the Web App Firewall Incidents report presents information by group. 4-18

33 Chapter 4 Working with Virtual Web Applications Creating a Virtual Web Application Label Basic Virtual URL Matching Mode (Custom Virtual URL with Filters setting) Description With this option, specify a distinguishing portion of the request URL in incoming requests to be handled by this virtual web application, such as This is the address at which consumers will address requests to the Firewall. It is used to perform a prefix match against request URLs. Requests for this URL or any sub-path are matched to this virtual web application, such as to The trailing parts of the request URL, if any, are propagated to the outgoing request. The host portion of the URL can be a hostname or an IP address. Only specify an IP address if it is also configured at the network interface of the ACE Web Application Firewall to which the policy will be deployed. If it is not, the Reactor process at the Firewall will be unable to start after policy deployment. The Virtual URL value you enter will be used to populate several properties of the virtual web application, as follows: The host portion of the value is used to create a new port/hostname object, if one does not already exist for the host and port combination. By default, a server definition is created based on the request host, and is set as the destination server for the new virtual web application object. The non-hostname portion of the path is used as the Path value for the virtual web application object. The path along with the port hostname composes the URL at which the web application is exposed by the Cisco ACE Web Application Firewall to clients. While the port/hostname object generated by the virtual web application editor can be configured later to allow regular expression matching on the virtual hostname, regular expressions cannot be entered directly into the Virtual URL field when creating the virtual web application. The field accepts only letters, numbers, dots, and hyphen characters. Based on the path you entered, choose how you want the ACE Web Application Firewall to use the value to match requests. Also choose whether you want the value to be matched in a case-insensitive manner by selecting the checkbox for this option. For more information, see the preceding description for the Path field. 4-19

34 Creating a Virtual Web Application Chapter 4 Working with Virtual Web Applications Label Destination Server Description The HTTP server that serves as the backend destination for this virtual web application. The Cisco ACE Web Application Firewall sends traffic that is qualified by this virtual web application to this destination host. The servers that appear in this menu are those that have been configured in the Destination HTTP Servers page. If set to same as virtual URL, the destination server will automatically be set to the host identified in the Virtual URL field. With the custom virtual URL option selected, the destination server maps to the Port/Hostname field. Note A virtual web application can be assigned to a destination server that uses Reactor processing only; it is not compatible with destination servers that use Flex Path processing. In the virtual web application configuration pages, destination servers that use Flex Path processing do not appear in the destination server selection menu. If a virtual web application is assigned to a destination server that later is modified to use Flex Path processing, the virtual web application will not work correctly and results in an error while policy compilation. Also the same is true for HTTP ports. Timeout Firewall Profile Monitor Mode The amount of time that the ACE Web Application Firewall should wait for a response from the destination server for each request. The traffic processing and validation profile that you want to apply for this web application. A profile is a named collection of rule and active security settings. The settings include whether a given rule is enabled and its configuration parameters. If the profile you want to use does not yet exist, you can set the profile to one of the built-in profiles and change it later. If selected, sets the initial operating mode of the virtual web application to monitor mode. In monitor mode, a message that triggers a message inspection rule in the applied profile is not blocked. Instead it is passed through with an event logged. When first deploying and testing the virtual web application configuration, it is often useful to set it to monitoring mode. This allows you to check for false positives (that is, legitimate traffic that nevertheless matches an attack signature) without effecting live production traffic. If the virtual web application generates false positives, you can quickly create a modifier that exempts the matched traffic from the rule that triggered the blocking event from the log description for the event. Note that message rewrite rules are applied to traffic handled by the virtual web application in monitor mode. Also note that, in enabled mode, messages are rejected at the first instance in which they violate a rule and are not further evaluated against other rules in the profile. The event log or incidents report will only show the rule that caused the message to be blocked, not any other rule that a message may have violated had its processing continued. On the other hand, in monitor mode, all rules violated by a message are indicated. 4-20

35 Chapter 4 Working with Virtual Web Applications Creating a Virtual Web Application Step 4 When finished, click Save Changes to commit the new virtual web application to the working policy. Creating the Virtual Web Application using Custom Virtual URL With Filters To create a new virtual web application using the custom virtual URL with filters mode, follow the steps in Creating the Virtual Web Application Using Basic Virtual URL section on page However, instead of the Basic Virtual URL option, choose Custom Virtual URL With Filters, and configure the settings specific to this option: Table 4-2 Virtual URL filter settings Label Port/Hostname (Custom Virtual URL with Filters setting) Description The port object on which the virtual web application should listen for traffic for this web application. The port defines a listening port number and virtual hostname. It also provides configuration settings for a static response page that can be used for health checks on the Cisco ACE Web Application Firewall. If the port is not in the menu, create it on the HTTP Ports & Hostnames page. If the Destination Server option is set to same as virtual URL, the value of port/hostname will be automatically propagated as the destination service for the virtual web application. To change the port and hostname value while keeping the existing destination server setting, change the Destination Server from the same as virtual URL option to a specific server definition. Note A virtual web application can be assigned to the ports that use Reactor processing only; it is not compatible with ports that use Flex Path processing. In the virtual web application configuration pages, ports that use Flex Path processing do not appear in the port section menu. If a virtual web application is assigned to a port and later is modiffied to use Flex Path processing, the virtual web application will not work correctly and results in error while policy compilation. Also the same is true for the HTTP servers. 4-21

36 Creating a Virtual Web Application Chapter 4 Working with Virtual Web Applications Label Path (Custom Virtual URL with Filters setting) Matching Mode (Custom Virtual URL with Filters setting) Methods (Custom Virtual URL with Filters setting) Description The path addressed by incoming requests that you want to be matched to this virtual web application. As specified by the Matching Mode setting for the path, the path may be: The exact request path in messages that you want to match, such as: oakinsurance/customer This will only match requests that specify as the request path the entire string, without additional characters A prefix to the request path, such as: oakinsurance/ This path will match any request address that begins with oakinsurance/, such as oakinsurance/customer/getquote or oakinsurance/partners A path made that includes regular expression components, such as: oakinsurance/.*/getquote In this case, the regular expression command sequence (.*) is used to match any characters, so that both oakinsurance/customer/getquote and oakinsurance/partners/getquote would be matched. A backslash character can be used in this field to escape regular expression command characters. The regular expression implementation in the Web Application Security features of the Cisco ACE Web Application Firewall is based on PCRE (Perl-Compatible Regular Expressions). Based on the path you entered, choose how you want the ACE Web Application Firewall to use the value to match requests. Also choose whether you want the value to be matched in a case-insensitive manner by selecting the checkbox for this option. For more information, see the preceding description for the Path field. The HTTP request method of the requests to be matched to this virtual web application. The method appears as the first token in the request line of the request, such as GET in GET /images/logo.gif HTTP/1.1. Options are: ignore The HTTP request method is not considered. basic HTTP methods (GET/POST/HEAD) matches only the methods listed, excluding requests with other methods such as DELETE or TRACE. any standard HTTP 1.x method The request must be one that is defined as a standard HTTP 1.0 or 1.1 method, including GET, POST, HEAD, PUT, DELETE, OPTIONS, or TRACE. specified HTTP 1.x methods Standard HTTP 1.0 or 1.1 methods that you select. custom Any method name that you specify. If entering more than one, specify one method name per line. The name should match exactly the method specified in the first line of the request. Note that the method names you type are automatically converted to uppercase. They are matched to messages in a case-sensitive manner. 4-22

37 Chapter 4 Working with Virtual Web Applications Using Monitor Mode Label HTTP Headers (Custom Virtual URL with Filters setting) Parameters (Custom Virtual URL with Filters setting) Description Configure this option to have requests matched to this virtual web application based on the presence or value of one or more HTTP headers in the request. Requests that do not have the specified HTTP headers or values are not handled by this virtual web application. HTTP header names are matched in a case-insensitive manner, while their values are matched case-sensitive. Configure this option to have requests matched to this virtual web application based on the presence or value of one or more request parameters. Requests with parameters that do not match your requirements are not handled by this virtual web application. Parameter names and values are compared to messages in a case-sensitive manner. Parameters can be URL arguments in the request or parameters in the body of POST requests. URL arguments appear as ampersand-delimited name-value pairs in the request URL, as illustrated by the zip and session parameters: oakinsurance/partners/getquote?zip=94114&session=01234 You can set requirements for parameters using Perl-style regular expressions or by identifying the parameter by name. Specify request parameter requirements using these operators: exists The message must have the named parameter. matches regex The value of the named parameter must match the regex you specify. is The value of the named parameter must match the characters you specify, case-sensitive. is not The value of the named parameter must not match the characters you specify, case-sensitive. Note that specifying a matching or a non-matching ( is not ) requirement does not require that the parameter be present in the request. That is, if a request that otherwise matches the filter does not contain a parameter for which you ve specified a matching or non-matching value, it is accepted. Using Monitor Mode The processing mode for a virtual web application can be one of: enabled The ACE Web Application Firewall blocks messages that violate message inspection rules and applies content rewrite rules and active security features. monitor mode If selected, the ACE Web Application Firewall does not block traffic that matches a message inspection rule or violates an active security setting. Instead, it logs the event. This mode is useful for testing a configuration or monitoring the prevalence of potentially malicious traffic without affecting the traffic flow. Message rewrite rules, HTTP processing, exception mapping, and cookie security are applied to traffic even if the virtual web application is in monitor mode. disabled Stops the ACE Web Application Firewall from receiving traffic on the consumer interface defined for the virtual web application. Note that traffic is blocked unless a less specific virtual web application consumer interface exists that matches the messages that would have been matched by the disabled virtual web application. 4-23

38 Using Monitor Mode Chapter 4 Working with Virtual Web Applications The monitor mode is particularly useful for testing and developing the policy. In enabled mode, messages are rejected at the first instance at which they violate a rule; they are not further evaluated against other rules in the profile. The event log or incidents report will only show the rule that caused the message to be blocked, not any other rule that a message may have violated had its processing continued. On the other hand, in monitor mode, if a message is found to violate a rule, it continues to be processed by the other rules in the profile. This allows you to view in the log all rules that a message would violate, not just the first blocking rule triggered. You can set the operating status in the policy at several contexts: for a rule in a profile for an individual virtual web application for a group for all virtual web applications in the policy. You can also specify a default mode for newly created virtual web applications. Since it is usually advisable to observe the interaction of a virtual web application with network traffic in passive mode, before it affects the network traffic. For a given virtual web application, monitor mode works the same way whether set policy-wide, from the group, or just for the virtual web application. To set the operating mode policy-wide: Step 1 Step 2 Click the Virtual Web Applications link from the navigation menu. From the Set all virtual web apps to menu on the Virtual Web Applications, choose the desired operating mode: enabled, monitor mode, or disabled. To set the operating mode by group: Step 1 Step 2 Step 3 Click the Virtual Web Applications link from the navigation menu. Click on the name of the virtual web application group that you want to set. The group names appear in the green-shaded headings. From the Set all virtual web apps to menu in the group page, choose the desired operating mode, enabled, monitor mode, or disabled. To set the operating mode for an individual virtual web application: Step 1 Step 2 Step 3 Step 4 Click the Virtual Web Applications link from the navigation menu. Click on the name of the virtual web application that you want to set. The group names appear in the green-shaded headings. From the edit link next on the right side of the overview header. Click the Monitor Mode check box at the bottom of the page. The mode change is applied as a one-time event; that is, after setting the monitor mode with this control, the operating mode of groups or virtual web applications can be changed individually. 4-24

39 Chapter 4 Working with Virtual Web Applications Creating Modifiers Creating Modifiers A virtual web application can contain one or more modifiers. Like a virtual web application, a modifier applies rules and security actions to selected traffic. However, a modifier selects traffic only from the traffic handled by the virtual web application. A modifier applies traffic processing settings to a subset of the traffic handled by the containing virtual web application. While the settings in a modifier are originally derived from the virtual web application, they are otherwise independent of that virtual web application. That is, messages selected by a modifier are subject only to its processing settings (not to the modifier s as well as the virtual web application settings). You can create modifiers directly or from the event log. For events associated with virtual web applications rules, the event log descriptions contain a Create Exemption link, which allow you to quickly modify a policy to avoid false positives. It creates a new modifier page for the virtual application with a preset configuration based on the event. Note A modifier should be used only when you have a distinct subclass of traffic at a virtual web application that you want to process or validate differently. In many cases, the quality of a request that generated a false positive could be present in requests to other parts of the web application as well, not just to the subclass of traffic selected by the modifier. In this case, it is likely more appropriate to address a false positive through a profile-level change rather than by the addition of a modifier. When you create a modifier, its traffic filter is prepopulated with any required filter criteria from the virtual web application. If you attempt to change required settings, an error message appears in the interface. If you change the virtual web application filter criteria to be incompatible with modifiers that already exists, a compile time error is generated. Creating Modifiers Directly To create a modifier directly (that is, not through an event log incident): Step 1 Step 2 Step 3 Step 4 Click the Virtual Web Applications link in the navigation menu. Click on the name of the virtual web application for which you would like to create a modifier. Click the add modifier link. In the Request Filter for Firewall Modifier page, specify traffic-selection criteria to which this modifier applies. The settings are prepopulated with the traffic selection criteria of the virtual web application. Keep in mind that a modifier selects traffic from the traffic flow handled by the virtual web application based on its request filter criteria. Therefore, the modifiers selection criteria must be more specific, but also compatible with that of the virtual web application. For a modifier that selects by URL path, for instance, this means that the modifier path must extend the path of the virtual web application. Configure the filter settings described in the following table. 4-25

40 Creating Modifiers Chapter 4 Working with Virtual Web Applications Table 4-3 FIlter settings Label Path Methods HTTP Headers Parameters Description The request path that selects the messages to which you want this modifier to apply. The modifier selects messages from the traffic stream handled by the virtual web application; therefore, the path must extend the path of the virtual web application. For example, with a virtual web application path of /oakinsurance, the modifier path could be /oakinsurance/customer or /oakinsurance/partners/quotes/. From the HTTP methods accepted by the virtual web application, choose the subset of this modifier should accept. Notice that the methods accepted by the virtual web application are prepopulated in the request filter. Specifies traffic selection criteria based on HTTP header values in incoming requests. Specifies traffic selection criteria based on parameters in incoming requests. Step 5 Step 6 Step 7 Click Save Changes. The Edit Firewall Modifier page displays the profile as applied by the parent virtual web application. Modify its configuration as desired for processing traffic by this modifier by clicking the override link for a rule. You can configure specialized security actions, message inspection rules, and message rewrite rules to be applied by the modifier. When finished click the Exit to Virtual Web App Group link. Creating Incident-Based Modifiers The ACE XML Manager enables you to quickly adjust the policy based on incidents generated by actual traffic at the Firewall. This feature allows you to quickly configure the policy to accept the traffic that generated an incident, typically as a result of a false positive (that is, for legitimate messages that are incorrectly categorized as security threats). Note An incident-based modifier generates very specific traffic selection criteria, by default. It should be created only to have a distinct subclass of traffic at a virtual web application processed or validated differently. In many cases, the quality of a request that generated a false positive could be present in requests to other parts of the web application as well, not just to the subclass of traffic selected by the modifier. In this case, it is likely more appropriate to address a false positive through a profile-level change rather than by the addition of a modifier. To create an incident-based modifier: Step 1 Step 2 Step 3 Click the Event Log link from the navigation menu. Locate a log description for an event from which you want to create a modifier. You may need to adjust the log view filtering criteria at the top of the page. Event descriptions associated with web application security events include a Create Exemption link. Clicking the Create Exemption link for the item. A page opens in which you can create a modifier based on the event. 4-26

41 Chapter 4 Working with Virtual Web Applications Creating Modifiers Step 4 Adjust the default settings as needed and save the configuration. For details on modifier configuration, see Creating Modifiers Directly section on page

42 Creating Modifiers Chapter 4 Working with Virtual Web Applications 4-28

43 CHAPTER 5 Working with Profiles This chapter describes profiles. It covers these topics: About Profiles Built-In Profiles New Profile Active Security Features Message Rewrite Rules Message Inspection Rules About Profiles A profile is a named collection of rule group and active security settings that determine how traffic is processed and validated for a virtual web application. The system includes built-in profiles, which you can supplement with your own, application-specific profiles. In general, implementing web application security will involve creating a profile for each class of traffic handled at the ACE Web Application Firewall. The profile settings include whether a given rule is off or on and values for its configurable settings. It also specifies the action resulting from a rule match, whether to block the rule or continue processing. The built-in profiles are the Pass-through profile and PCI Compliance profile. The built-in profile settings cannot be modified directly. Instead, to make modifications to the settings of a built-in profile, you will need to create a new profile based on it and modify the settings of the newly created profile. A profile you create can be applied in a virtual web application directly or it can similarly serve as a settings template for creating additional profiles. To view settings for a profile, click the Profiles link in the navigation menu and then click on the name of the profile to view. For built-in profiles, you can view rule settings by clicking the view link next to the name of the rule or active security feature. For a user-created profile, you can view or modify the profile rule settings by clicking the edit link next to the rule in the profile page. A profile has three types of message processing and validation rules: active security features, message rewrite rules, and message inspection rules. 5-29

44 Built-In Profiles Chapter 5 Working with Profiles Built-In Profiles A built-in profile is a profile with a preset rule configuration. The configuration is usually intended to address a particular set of requirements, such as the PCI compliance requirements. While the rule settings for a built-in profile cannot be modified directly, you can create new profiles based on a built-in profile, which can then be modified as needed. Built-in profiles are part of the system s based configuration. The base configuration can be updated, resulting in additional built-in profiles or enhancements to the existing built-in profiles. Base configuration updates must be Cisco-certified, and cannot be modified directly. The default base configuration contains these built-in profiles: Pass-through Profile PCI Compliance Pass-through Profile The Pass-through profile is a built-in profile in which all rules are disabled, making it in effect a blank profile. The pass-through profile is useful for performing initial system testing. Since it is designed not to affect traffic in any way, it can be used to test connectivity or other initial configuration settings. It can also serve as a basis for creating new profiles. PCI Compliance The PCI Compliance profile provides base settings intended to help meet elements of the requirements specified by the Payment Card Industry DSS (Data Security Standard). The profile helps protect against cross-site scripting (XSS) attacks (PCI 6.5.4), buffer overflow attacks (PCI 6.5.5), and injection flaws, such as SQL injection (PCI 6.5.6). It also specifies credit card number rewriting rule on responses. This rewrite rule is intended to prevent customer credit card data from being inadvertently transmitted in responses. For details on the profile s settings, click on the profile name in the Profiles page. Note While you cannot change the built-in PCI Compliance profile, you can create a profile based on it, which can be modified as desired. For more information on PCI compliance, see the Cisco PCI Solution for Retail 2.0 Design and Implementation Guide. Also see New Profile To define and use a customized profile configuration, you create a new profile. Creating a profile involves several steps first you create the profile with its initial settings, such as its name and description. You can then customize the rule settings for the profile, enabling the rules and security actions desired and setting their parameter values and severity levels. To create a new profile: 5-30

45 Chapter 5 Working with Profiles Active Security Features Step 1 Step 2 Step 3 Click the Profiles link in the navigation menu. Click the New Profile button. Configure the profile using the settings described in the following table. Table 5-1 Profile settings Label Profile Name Description Copy Settings From Description A unique, descriptive name for the profile. This name is used to identify the profile in the policy. An optional description of the profile. This value can help to document the profile within the web console to other web console users. The value of the description does not appear outside the console. Uses as the initial rule and active security settings for the profile those of an existing profile. Note that the settings from the source profile are propagated to the new profile only at the time the profile is created; that is, subsequent changes to a profile used as the source are not automatically propagated to profiles generated from it. To create the profile without preconfigured settings, keep the default selection, none. Step 4 Step 5 Click the Create Profile button. The new profile is created based on the settings you specify and its settings page appears. From the profile settings page, modify the rule and active security features as desired for the profile. Click the edit link next to a rule to enable it or reconfigure it in the context of this profile. After configuring the active security and inspection and rewriting rules in the profile, you can apply the profile in virtual web applications. Active Security Features The active security features in a profile perform specialized message processing and security tasks, such as data overflow defense, HTTP header processing, and cookie encryption/decryption. Note Unlike rules or signatures, active security features cannot be added to the system or otherwise customized except as provided for in their configuration settings. In general, for virtual web applications in monitor mode, the ACE Web Application Firewall applies the security rules to traffic but does not block message that violate the rules. Most active security features remain in effect for virtual web applications in monitor mode, including HTTP header processing, HTTP exception mapping, and cookie security. However, data overflow defense and referer enforcement are subject to monitor mode; that is, when triggered, they do not cause message blocking although an event is logged. 5-31

46 Active Security Features Chapter 5 Working with Profiles In general, to view or modify active security settings for a profile, click the Profiles link in the navigation menu and then click on the name of the profile to view. Next to the active security feature name, click the view link (for a built-in profile) or the edit link (for a user-created profile) to access its settings. The following sections provide more information on each security feature. HTTP Header Processing As a reverse proxy, the ACE Web Application Firewall processes and populates certain HTTP headers in messages automatically. For example, it populates the Date and Content-Length headers with appropriate values when it processes a message. However, other types of HTTP headers found in messages are passed through without modification. Rather than passing headers through, you can have the ACE Web Application Firewall modify, add, or remove specific headers in messages. The HTTP Header processing page provides controls for configuring the HTTP headers that often need to be manipulated at a reverse proxy, such as the Server and X-Forwarded-For header. In addition, you can configure special handling for any HTTP header identified by name. HTTP header processing can be specified on either the request or response side. The values of certain types of headers cannot be set in the policy. In general, these headers are populated with values determined at runtime, such as the Date and Content-Length header. In addition, header passthrough does not apply to what are considered hop-by-hop headers, which are significant only in the context of a single transport-level connection, such as: Accept-Encoding Connection Keep-Alive Proxy-Authenticate Proxy-Authorization TE Trailers Transfer-Encoding Upgrade The following table describes the HTTP Header processing settings. 5-32

47 Chapter 5 Working with Profiles Active Security Features Table 5-2 HTTP Header processing settings Label Insert "X-Forwarded-For" header with client's IP address Insert Client SSL Certificate DN in header named Rewrite Host header with destination server hostname Description Reverse proxy servers often use the X-Forwarded-For HTTP header to identify the client that originated the request to the backend system. You can use this header to indicate to the backend application the IP address that appeared as the request source as received by the ACE Web Application Firewall. The header is added as specified by one of these options: if the header does not already exist Adds the header only if it does not appear in the message. If the header is already present, the header is passed through with its original value. replacing any existing value Removes the existing header and adds the custom header. in addition to any existing value Adds the header whether or not it is already in the message. If a header with this name already exists in the message, there will be two instances of the header. appending to any existing value If the header already exists, appends a comma and the IP address of the source to the existing header. If the message does not have a header, it is added. (This option is suggested for best interoperability, particularly with the widely used Squid open source web proxy.) Inserts as a new header the distinguished name of the subject of a client SSL certificate included in the message. The DN value is added to a header with the name you specify. The header is added as specified by these options: if the header does not already exist Adds the header only if it does not appear in the message. If the header is already present, the header is passed through with its original value. replacing any existing value Removes an existing header and adds the custom header. in addition to any existing value Adds the header regardless of whether it is already present in the message. If present, there will be two instances of this header. appending to any existing value If the header already exists, appends a comma and the certificate DN to the existing header. If the message does not have a header, it is added. For the certificate DN value to be added to the header by this option, the SSLVerifyClient setting must be set to optional_no_ca value, as specified in the I/O Process Settings page. If it is not, the header will be added with a blank value. If selected, replaces the Host header value in requests with the name of the destination backend host, as derived from the destination server specified for the virtual web application definition. 5-33

48 Active Security Features Chapter 5 Working with Profiles Label Custom Header Processing Replace Server header value with Description For request messages, performs the following action on the named HTTP headers. Configure header processing by specifying these values: In the first field, enter the name of the header to be processed. The operation menu specifies how the header is to be processed: strip Removes all instances of the named header you specify from the message. Note that this does not imply that the header is expected; that is, it is not an error if absent. set if empty If the named header does not exist, inserts it with the value specified. If it does exist, does nothing. The resulting message will have at least one header with the name you configure. replace value Strips any existing occurrences of the named header and inserts a new instance of it with the value specified. add value Inserts a new instance of the header with the name and value specified. This option does not affect existing headers with the same name. Therefore, it will result in a message with at least one but possibly multiple headers with the same name. append Appends a comma followed by the configured value to an existing header with the same name. If the request does not have the named header, it is added. If it has multiple headers with the same name, the value is appended to only one of the headers. The operations are performed in the order in which they appear in the interface. In the text field that follows the operation (unless the strip option is selected), enter the desired value. This field supports dynamic values in the form of Reactor expressions, e.g., $(REQUEST_HEADER['Date']) For more information on the Reactor expression syntax, see the Cisco ACE Web Application Firewall User Guide. By default, in responses handled by virtual web applications, the Server header value received from the backend system is passed through to the outgoing response. Alternatively, you can have the ACE Web Application Firewall rewrite the Server header to the value specified in this field. 5-34

49 Chapter 5 Working with Profiles Active Security Features Label Custom Header Processing Description For response messages, performs the following action on the named HTTP headers. Configure header processing by specifying these values: In the first field, enter the name of the header to be processed. The operation menu specifies how the header is to be processed: strip Removes all instances of the named header you specify from the message. Note that this does not imply that the header is expected; that is, it is not an error if absent. set if empty If the named header does not exist, inserts it with the value specified. If it does exist, does nothing. The resulting message will have at least one header with the name you configure. replace value Strips any existing occurrences of the named header and inserts a new instance of it with the value specified. add value Inserts a new instance of the header with the name and value specified. This will not affect existing occurrences with the same header name, so it may result in a message with at least one but possibly multiple headers the name. append Appends a comma followed by the configured value to an existing header with the same name. If the response does not have the named header, it is added. If it has multiple headers with the same name, the value is appended to only one of the headers. The operations are performed in the order in which they appear in the interface. In the text field that follows the operation (unless the strip option is selected), enter the desired header value. HTTP Exception Mapping An HTTP exception is a response message that signals an error or other unexpected event in the course of request processing. The exception may result from an error in the request itself or an error in the backend system processing or network. In some cases, HTTP exceptions passed from the backend application can contain sensitive information to potential attackers that hackers can use, such as a web server stack trace. By mapping exceptions at the Cisco ACE Web Application Firewall, you can ensure that only generic error messages are passed to the client. When exception mapping is enabled, rather than returning specific error information, the ACE Web Application Firewall returns the response you configure. You can configure mapping of all 400 and 500 errors to a generic 500 error, for instance, or configure a specific response for some errors. The following table describes the HTTP Exception processing settings. 5-35

50 Active Security Features Chapter 5 Working with Profiles Table 5-3 HTTP Exception processing settings Label For server errors (status code 400 and above) not specified below Status Codes Status Code Content-Type Other Headers Response Body Description Use this option to map any error response from the backend system that has an HTTP status code of 400 or greater to a generic error response to be returned to the client. By default, such responses are passed through to the client. The generic HTTP 500 status code response reports a server error with the following description: The server encountered an internal error and was unable to complete your request. You can enable this error mapping option along with the custom response mapping options below it. The custom response configuration takes precedence over this generic mapping for a response with an error code to which both are applicable. If this option is set for pass through and there are specific status codes mapped to an exception, the Server header value for error responses received by clients will vary those passed through will have the Server value set by the backend system, while mapped errors will have the Server value set in the ACE Web Application Firewall configuration, if specified by the policy configuration. Rather than mapping all error responses to a generic response, you can configure a custom response message for specific HTTP error codes received from the backend system. To configure this behavior, in the Status Codes field, type the numeric error status codes of responses to be mapped to the custom response. You can enter the numbers individually or as a range, such as 400, 403, Ranges and single values must be separated by a comma. When deployed, responses from the backend network with the specified error code will be mapped to the response you configure for delivery to the client. This configuration takes precedence over the generic mapping setting, if also configured. The status code for the outgoing response message, with the options of passing through the status code from the incoming response or of using a pre-set status code. The content encoding type for the outgoing response message, with text/html by default. Any other HTTP headers that you want to be included in the response. Note that certain HTTP headers cannot be specified in this field. The Date and Content-Length header values, for instance, are passed through from the backend response and cannot be manually specified here. Also, the Server header value is either passed through from the backend system (the default) or populated by a more specific configuration in the HTTP header processing settings. The body of the HTTP response to be sent to the client. 5-36

51 Chapter 5 Working with Profiles Active Security Features Referrer Enforcement The referrer HTTP request header (or Referer, as incorrectly spelled in the standard) indicates the address of the resource from which the request obtained the Request-URI. The referrer enforcement feature can protect against a type of attack called Cross Site Request Forgery (CSRF). A common example of a CSRF attack involves a user who has an active browser session to a sensitive web application, such as an online banking application. If, while the authenticated session remains active, the user can be induced to click on a link on another web site that initiates an operation against the bank application, such as a funds transfer to the attacker s account, the operation can be fulfilled. The link may be presented on a web site controlled by the attacker, in an , or elsewhere, such as on a public forum. Such attacks can be avoided by restricting messages based on the host indicated in the Referer header. If the host identified by the referrer value is not the host of the web application itself, the request can be rejected. This blocks requests in which the request URL for performing a sensitive operation was obtained elsewhere, such as from a link on a third-party web site or in an . The following table describes the referrer enforcement settings. Table 5-4 Referrer enforcement settings Label If the Referer header is present, require that its value matches requested host name Never check Referer header on GET requests Monitor Mode Description If selected, requires requests that contain a Referer header to have as its value a URI with a hostname that matches the one in the request URL. In other words, the referrer must identify the web application addressed by the request, not an external application or web site. Since HTTP GET requests are not usually used in this type of attack, you can disable checking for GET requests. The checking will apply to POST requests or incoming messages with other HTTP methods. When selected, if the host identified in the Referer header does not match the request URL, the event is logged but the message is allowed. HTTP Cookie Security Web applications often use HTTP cookies to store information regarding a particular user or session. The server embeds the cookie in the response sent to the client, and the browser returns the cookie unchanged in subsequent requests. It s possible for cookies to contain private information or to form the basis of a session hijacking attack. In most cases, the cookie content should not be modified except by the backend application. Whether cookie security is enabled or not, cookies in messages are subject to the data overflow and HTTP header processing settings you configure in the profile. With cookie security enabled, the ACE Web Application Firewall can apply cookie-specific validation measures and ensure the security of cookies by encrypting or signing cookie before delivery to the client. After processing a cookie, when the ACE Web Application Firewall receives the cookie in subsequent requests from the client, it checks the signature or decrypts the cookie before forwarding it to the backend web application. The ACE Web Application Firewall can thereby ensure that the cookie has not been modified or viewed from the Firewall to the client. 5-37

52 Active Security Features Chapter 5 Working with Profiles When cookie security is enabled, the ACE Web Application Firewall removes cookies that are found to be invalid based on its inability to verify the signature, decrypt the cookie, or validate the cookie for correctness. (When cookie security is disabled, cookies are propagated through the ACE Web Application Firewall unchanged.) Cookies are considered invalid if their values contain unclosed quotes, duplicate attributes, and certain forbidden characters, such as commas (, ), semi-colons ( ; ), double-quotes ( ), equals ( = ), and whitespaces. Note Cookie security should not be used with applications that use Javascript to set or modify cookies at the client. For example, client-side Javascript may set a cookie to indicate the browser type to the backend application. Since client-modified cookies will fail validation or decryption, cookie security should be disabled in such cases. Note that with cookie signature enabled, new cookies added at the client will be dropped by the Gateway; however, with encryption enabled, new cookies will be accepted. In either case, cookies that are modified at the client are dropped. Cookie header validation occurs when cookie security is explicitly enabled through the use of cookie encryption or signing. The following table describes the settings for the active cookie security feature. Table 5-5 Cookie security features Label Sign (HMAC-SHA1) Description Select this option to have cookies in the response digitally signed before being sent to the client and validated upon being returned in subsequent requests. Digital signatures help to ensure the integrity of cookies. It can prevent cookies that have been maliciously tampered with (for example, in a session spoofing attempt) from being forwarded to protected applications. If the cookie signature is invalid, the cookie is stripped from the request. The Cisco ACE Web Application Firewall signs the cookie using the keyed-hash Message Authentication Code (HMAC or KHMAC) based on a secret key you specify in the passphrase field of the policy configuration. The same signing passphrase needs to be used by any ACE Web Application Firewall cluster that may receive requests with cookies that were processed by another ACE Web Application Firewall cluster. The effects of cookie signing should be considered if also using data overflow defense in this profile. When signing a cookie, the Cisco ACE Web Application Firewall adds an extra header (a signature cookie) to the outbound message. The signature is always eight characters in length, while the name of the cookie header is three characters longer. Therefore, the total size of the signature cookie header will be larger than the size of the original cookie if the original cookie value attribute is 10 characters or less. Take, for instance, the following cookie: Cookie: NAME= a If signed, the message will include a signature cookie in the following form (not an actual signature): Cookie: NAMESig= As shown, the cookie value is always represented by eight characters. However, three characters are also added to the name. 5-38

53 Chapter 5 Working with Profiles Active Security Features Label Encrypt (AES) Cookies with Passphrase Description Select this option to have the Cisco ACE Web Application Firewall encrypt cookies in messages prior to delivery to the client. When it receives the encrypted cookie in a subsequent request from the client, it decrypts the cookie prior to delivery to the backend application. Cookie encryption serves to obscure cookie data from the client. Note that cookies can be generated by clients as well as servers. If it receives a request with an unencrypted cookie (which suggests a client-generated cookie), the ACE Web Application Firewall allows it through. It s important to note, therefore, that while in general encryption can provide a form of integrity protection, in this case, because the ACE Web Application Firewall doesn t require every cookie to be encrypted, encryption cannot be relied on to enforce cookie integrity. The Cisco ACE Web Application Firewall encrypts the cookie using AES (Advanced Encryption Standard), a symmetric key-based cipher encryption standard. The cipher text is generated with the secret key you specify in the passphrase field. The effects of cookie encryption should be considered if also using data overflow defense, which can impose a limit on the size of the cookie headers. For encryption, cookies will become larger by a number of bytes proportional to the size of the original cookie value. Specifically, the length of the encrypted cookie can be anticipated using the following formula. Since they are encrypted separately, take the length of each of the cookie s name and value and round that value up to the next multiple of 16. Then divide by 3 (rounding up if there's a remainder) and multiply by 4. For example, if the name is 10 characters, = 11, round up to 16, divide by 3 and round up = 6, multiply by 4 = 24. Some name/value example lengths, with their post-encryption sizes: 0 15 becomes 24 characters becomes 44 characters becomes 64 characters Use the result of this calculation to determine the appropriate data overflow settings to use. The secret key for encrypting or signing cookies. The passphrase you enter should be at least five characters long, and can include any combination of numbers, letters or special characters. While the passphrase may be 5 characters long, for best security, you should enter a passphrase that is significantly longer. Ideally, it should be around 20 characters in length. When the policy is deployed, the Manager transmits the passphrase to all Cisco ACE Web Application Firewalls in the cluster. If separately managed clusters may receive subsequent requests from the same client, those clusters should be configured with the same passphrase. 5-39

54 Active Security Features Chapter 5 Working with Profiles Data Overflow Defense Data overflow defense allows you to configure security based on the size or number of various attributes in a message. Messages that do not comply with the data overflow defense settings can be blocked or passed through with an event logged at a configurable severity level. Note The processing settings for the virtual web application itself can affect the size of message components. For instance, cookie signing or encryption can introduce new headers or enlarge existing headers. The data overflow defenses are applied to the message after cookie processing. For more information, see HTTP Cookie Security section on page The following table describes the data overflow defense settings. Table 5-6 Data overflow defense settings Label Enforce the following data limits on requests Maximum Number of HTTP Headers Maximum Size of Any HTTP Header Maximum Cookie Size Maximum Total HTTP Header Size Description Select this option to enable data overflow protection and make the configuration settings for data overflow defense available. The number of HTTP headers permitted in messages. The maximum size of any HTTP header, in bytes. This does not apply to cookies. The maximum size of any HTTP cookie or encrypted cookie headers in bytes. The maximum size of all the HTTP headers together, including cookies, in KB. Maximum Size of Request URL The maximum size of request URLs, in bytes. This values includes the requested hostname, resource, and all URL parameters. Maximum Size of GET Query String Maximum Number of Request Arguments Maximum Size of Any Argument Maximum Total Size of Request Body Monitor mode The maximum size of GET query string in the URL, in bytes. Query string appears in the request following a question mark symbol, such as: Maximum number of arguments in a GET or POST request. In GET requests, arguments appear as ampersand-separated parameters to the URL, such as In POST requests, they appear as similar name-value pairs in the body of the request. Maximum size of any one argument in a POST or GET request, including the size of the name and value of the argument, in bytes. The maximum total size of the POST body in a request, in bytes. If selected, requests that violate the data overflow settings result in an event being logged at the configured severity level, but are not blocked. 5-40

55 Chapter 5 Working with Profiles Message Rewrite Rules Label Event Log Response Description Controls the severity level of the log event resulting from this action being triggered when it is applied in monitor mode, either at the rule group level or at the virtual web application level. By default, these events are logged at the Warning level. However, when the rule is applied in monitor mode, it may be appropriate to have a reduced severity level. If a message violates the data overflow defense settings, the action the ACE Web Application Firewall should take. Options are: Return an HTTP error response with status code 400, Client Error Return an HTTP error response with status code 500, Server Error Return a custom HTTP error response you configure. Allow message is similar to monitor mode; a signature match event is reported but the message is allowed to pass through. Message Rewrite Rules While a message inspection rule operates on the entire message, in either blocking or allowing it through, a rewrite rule modifies the message by replacing matched content before passing it through. Also, while message inspection rules operate on requests, message rewrite rules operate on responses. Message rewrite rules help to ensure that backend applications do not emit sensitive information, such as user credit card numbers or social security numbers. The portion of the response that matches the signature in a rewrite rule is replaced by the replacement character. A message rewrite rule can match multiple instances of the signature pattern in a response. When enabled in a policy, message rewrite rules modify messages even if the virtual web application is set to monitor-mode only. That is, message rewriting occurs whether the virtual web application is in monitor or enabled mode. Content Rewriting and Response Compression Special considerations exist if configuring content replacement for responses that may be compressed. When it receives responses that have been compressed by backend systems, the Cisco ACE Web Application Firewall can pass through the responses. However, message rewriting rules will not work on compressed responses. If content replacement is important to your system and the backend system performs response compression, you will need to ensure that the Firewall receives uncompressed responses by stripping the HTTP header used to indicate acceptance of compressed responses (ACCEPT-ENCODING) from outgoing requests. You can specify header stripping in the virtual web application by configuring HTTP header processing in which the ACCEPT-ENCODING header is removed from outgoing requests. As a result, the response from the backend server will not be compressed. To enable and configure rewrite rules, click the edit link next to the rewrite rule group in the profile. Rewrite rules have the following settings. 5-41

56 Message Inspection Rules Chapter 5 Working with Profiles Table 5-7 Rewrite Rule settings Label Rule Set Mode view rule set details Rewrite Rules Description Whether the rule group will be enabled in the virtual web applications that use this profile. Enabling this option displays the rules in this rule group, which can be individually enabled or disabled. The options are: Enabled The rules in this rule group are applied to message traffic for virtual web applications that use this profile. Disabled The rules are not applied to traffic for this profile. Note that enabled rewrite rules apply even if the virtual web application is in monitor mode. Displays the source code of the current rule group. Each rewrite rule in the group can be individually enabled or disabled. If enabled, the rule is applied to message traffic. When a rule is triggered by a signature match, each character of the matched text is replaced by a replacement character for the rule. The character is indicated in the Rewrite Char. column for the rule, which you can view by clicking the view rule set details link. Message Inspection Rules Message inspection rules examine requests for potentially malicious content. The rules use signatures to identify content of interest in messages directed to a web application. Built-in message inspection rules exist, for example, to detect command injection or cross site scripting attacks. When the content is detected, the ACE Web Application Firewall can block the request or allow it through with an event logged. For a message-inspection rule set, you can specify a strictness level to be applied in the profile basic, moderate, or strict. The severity level controls which rules in the set are enabled; only rules that have the same or lesser severity are enabled. Choosing moderate severity, for instance, enables the moderate and basic rules in the rule set. Instead of a specific level, you can manually choose which rules to enable with the custom option. To enable and configure rewrite rules, click the edit link next to the message inspection rule group in the profile. Inspection rules have the following settings. 5-42

57 Chapter 5 Working with Profiles Message Inspection Rules Table 5-8 Inspection Rule settings Label Rule Set Mode Level Exemptions Description Whether the rule group will be enabled in the virtual web applications that use this profile. Enabling this option displays the rules in this rule group at a particular severity level. The options are: Enabled The rules in this rule group are applied to message traffic for applications that use this profile. Monitor If a message triggers any enabled rule, the event is logged at the severity level specified in the rule configuration (Warning, by default), but the message is not blocked. Disabled The rules in this rule group are not applied to traffic for this profile. The severity level of the rules in the group that you want to be applied. Each rule is described by its severity level. The severity is usually differentiated by the number and scope of signatures in the rule or the scope of the message to be inspected. Choosing a severity level for the group causes the ACE Web Application Firewall to apply only the rules in the group that have the same severity level. The levels, in increasing order of severity, are basic, moderate, and strict. Choose Custom to choose directly which rules are enabled. Exemptions allow you to fine-tune how rules are applied. An exemption excludes certain signatures from evaluation. If a message matches an exempted signature, the match is ignored. For instance, it may make sense to exempt the signature that looks for a single tick ( ) in parameters that represent user names, since the parameter may have the following legitimate value: /path?lastname=o neill For these cases, you can exempt the lastname parameter from the single-tick pattern signature. The same effect can be achieved with custom signatures, however, using the exemption feature simplifies the configuration. An exemption can be specified in the base profile, as performed here, or (as may be appropriate in most cases) in the profile of a modifier to the virtual web application. In the exemption configuration, indicate the scope of the exemption, whether it should apply to the entire request, to parameters, or to HTTP headers. Also, indicate whether a specific signature or all signatures are to be exempted. For a named signature, indicate the signature by signature identifier, such as: In parameter: lastname ignore signature: CrossScriptXSS.52 To get the signature identifiers for the signatures in the policy, click View Signatures from the Rules & Signatures page. If the exemption applies to a message, the following item is logged at the information level: CROSSITESCRIPT.CrosSiteScript1:CrossScriptXSS.52:REQUEST_GETPARA M['firstname'] detected by a Limit, but an override deactivated it. 5-43

58 Message Inspection Rules Chapter 5 Working with Profiles Label Event Log Response Description Specifies the severity level of the log event resulting from this rule being triggered when it is applied in monitor mode, either at the rule group level or at the virtual web application level. By default, these events are logged at the Warning level. However, when the rule is applied in monitor mode, it may be appropriate to have a reduced severity level for the rule. Use to configure the response message returned to the client in the event of a rule signature match. Options are: Return an HTTP error response with status code 400, Client Error Return an HTTP error response with status code 500, Server Error Return a custom error response you configure Allow message is similar to monitor mode; a signature match event is reported but the message is allowed to pass through. 5-44

59 CHAPTER 6 Developing Rules and Signatures This chapter describes how to develop custom web application security rules and signatures. It covers these topics: Overview, page 6-45 Message Normalization, page 6-46 Developing Signatures, page 6-49 Developing Rules, page 6-55 Overview The Cisco ACE Web Application Firewall includes an extensive library of rules and signatures you can use to secure web applications out-of-the-box. Built-in rules exist for stopping many types of server attacks, such as cross-site scripting attacks, SQL and LDAP injection attacks, and command injection attacks. Nevertheless, applications often have unique security and content privacy concerns. The built-in resources may not address all requirements specific to your application or environment. For such cases, the Cisco ACE Web Application Firewall enables you to create your own custom rules and signatures. This extensibility enables you to tightly mold the capabilities of the Cisco ACE Web Application Firewall to your specific requirements. You create custom rules and signatures using the Reactor rules language, as described here. After you have uploaded your rules and signatures into the Manager, they can be applied in web application profiles in the same manner as built-in rules. In most cases, rule development will be motivated by a requirement to apply new signatures based on new or emerging attack patterns. Therefore, rule development projects will typically involve development of new signatures along with new rules. The general steps for developing signatures and rules are: 1. Create the signatures needed to match the traffic you want to be processed or secured by the rules. Both signatures and rules are created and loaded into the system as text files. However, since the Manager treats rules and signatures as separate resources, you should create them in separate text files. 2. Create custom rules and rule groups in a separate text file. The rules can rely on built-in signatures or custom signatures. 6-45

60 Message Normalization Chapter 6 Developing Rules and Signatures 3. Load the signature file into the Manager (before loading any rule that relies upon the custom signatures). The Manager validates the signatures in the file, and indicates problems on the web console page. 4. Upload the custom rules file. When importing the rules, the Manager checks that signatures referenced in the rules exist in the system, and performs other validation checks on the rules. Once uploaded, the custom rules are available to be applied in profiles. Also, note that the rules can be modified later directly from the Manager interface. While these steps describe development that includes signatures along with rules, there are cases in which developing new rules will not depend on new signatures. For example, you may need to apply one of the built-in unused rules, or you may want to apply a built-in signature differently from how it is applied by the built-in rules. Most commonly, you may need to write a rule that does not use signatures. For example, to implement a rule that checks for data overflow, you would have a rule statement such as: REQUEST_PARAMS.count() gt 100 As another example, checking a specific parameter against a regular expression could be achieved with an expression such as: REQUEST_PARAM['username'] nre '[A-Za-z0-9]+' The following sections provide more information on the rule development steps and requirements. Message Normalization To simplify rule development, the ACE Web Application Firewall automatically normalizes the message before evaluating rules against it. This alleviates you from having to deal with various types of message variations in the rules and signatures you create. For example, you do not need to create one version of a signature or rule for ISO based attacks and another for the same attack in UTF-8. It can also sanitize message content. Message normalization does not affect the message that is actually passed through the ACE Web Application Firewall to the destination (except for NULL-byte screening and header unfolding); it is performed only on a copy of the message, or, more precisely, on the values from the message used to populate the variables that are used for rule evaluation, such as REQUEST_PARAMS or REQUEST_URL (see Rule Variables, page 6-61). While normalization does not itself modify the output message (except for header whitespace unfolding), it can affect the output if you use variables in other contexts of the policy, such as in custom error messages or HTTP header processing. For instance, you can normalize a part of a request and use it to populate an outgoing header value. Messages are subject to two types of message normalization. The first is called passive normalization. It happens to every message automatically. The second type of normalization is invoked directly from rules using the normalize() function. Passive Normalization Passive normalization affects messages as follows: Any message that contains a NULL byte is rejected. (The presence of null bytes are treated as fatal errors. The ACE Web Application Firewall will respond with a 400/client error and generate a warning-level event that indicates a malformed request.) In the request URL (including any GET arguments) and the body of any POST, the Firewall: 6-46

61 Chapter 6 Developing Rules and Signatures Message Normalization Decodes URL-encoded (that is, percent-encoded) characters into UTF-8 encoded characters. For rule and signature composition, this means that: For ASCII characters, to match an argument that contains a percent-encoded character such as %27 (the URL-encoded single tick character), your custom signature can simply look for '. You can use Unicode characters in rules and signatures (such as certain cyrillic characters), which will be successfully matched, although the uploaded signature or rules file must be in UTF-8 format. To look for a non-character decoded value in a signature, you can do so by putting a hex expression in the signature or regular expression, such as \x09, to look for a byte that just represents 9. Decodes %u-encoded characters (non-standard Microsoft-used unicode encoding) to UTF-8. In the request path only (this does not include the query string, that is, anything after? ), the Firewall normalizes potentially obfuscating path commands like self-references (./) and back-references (../). This also helps properly match traffic to virtual web applications (that is, requests for /app/../path actually match the handler for /path rather than mistakenly matching the /app prefix handler.) In HTTP headers, the Firewall: Applies whitespace unfolding ( where multiple-line headers are converted to a single line. Note Whitespace unfolding is the only aspect of normalization that affects the output message. Other HTTP header are unchanged, except for the Host header. For the Host header, the Firewall changes URL-encoded or %u-encoded values to UTF-8. The entire header value is converted to lowercase, since hostnames are not intended to be evaluated in a case-sensitive manner. Host header normalization facilitates Referer header checking. normalize() Function The purpose of the normalization process described in Passive Normalization section on page 6-46 is to alleviate signatures and rules from having to be written to contend with many low-level encoding issues in evaluated message content. However, except for path normalization (which helps to assign a request to a handler), this level of normalization is not intended to prevent higher-level obfuscations, such as excessive whitespace, encoded entities (such as using <script instead of <script), and breaking up attack strings with comments. The second level of normalization, direct normalization, is intended to deal with just this type of obfuscation. To use direct normalization, you invoke the normalize() function on a part of a message, as follows: VARIABLE['fieldName'].normalize() op testvalue Such as: REQUEST_HEADER['My-Header'].normalize(charset uunicode) re 'attack!' In this case, the value of the HTTP header, My-Header, is normalized prior to being tested against the regular expression, attack!. 6-47

62 Message Normalization Chapter 6 Developing Rules and Signatures In the case of GET and POST parameters and POST bodies, many of the normalization processes described here are applied automatically, and do not need to be applied again with this function. However HTTP headers, multipart content disposition, and so on, are not extensively normalized by passive normalization and are subject to manual normalization through the normalize function. The normalize() function can apply all processing that is applied to GET or POST arguments automatically (that is, URL-decoding and %u-decoding). In addition, it can: 1. Convert letters to lowercase. 2. Collapse all whitespace runs (any type of whitespace char) into a single space character (equivalent to ASCII 32). 3. Strip C language and CSS-style comments (in the form: /*... */) as well as HTML/XML comments (in the form: <! >). These can be used to disguise attacks by interrupting the sequence of characters checked for by regular expression-type scanners with unrelated characters that will ultimately be ignored by the destination parser. 4. Decode HTML, hexadecimal (&#xnn), and decimal (&#N...N;) entities. 5. Decode JavaScript- and C-language-style encoding, such as \t, \001. \xaa, \hhh, \0OOO. While the primary intent of normalize() is to deter obfuscation attempts, it also eases signature and rule authoring. For instance, instead of writing a regular expression to look for an arbitrary amount of whitespace between an attribute name and its value, you can assume there will be zero or one space. Executing normalize() on a value when running an expression against it (such as in the example, REQUEST_HEADER['My-Header'].normalize(charset uunicode) re 'attack!') does not alter the value of the parameter Name. The normalized value will be produced and used only for this particular regular expression evaluation. In general, you should apply normalize() to any value before running a content-based signature (such as command injection) against it. However, there may be cases where running normalize() renders an attack unrecognizable, and in which the attack can only be caught in its raw form. You can also use normalize() in any place in the virtual web application configuration in which you an output content, such as in custom error response messages or in headers. For example, you can replace a raw header with a sanitized version in the HTTP header processing configuration, that is, by replacing the value of header Custom-header with REQUEST_HEADER['Custom-header'].normalize(). Thus, while a normalized version of the message is not propagated to the outgoing request, you can use the HTTP header processing feature to normalize the headers propagated to the outgoing message. Note Note that while you can completely reconstruct the header list using HTTP header processing, you cannot currently rewrite GET or POST parameters. To use the normalize() function, you must identify the aspect of normalization you want to apply to the message as a parameter. The supported parameters follow. You can pass multiple parameters using the pipe operator ( ): url Performs URL-decoding, that is, %-encoded characters into their binary equivalents. This may result in normal readable characters or in non-character bytes. Generally, this option would be used together with the charset option. charset Takes any non-character bytes from the previous step and turns them into UTF-8 encoding (using the assumption that the original encoding was ISO ). This option would generally by used with the url argument, although it can be used alone as well (for example, if you have a value that is not URL-encoded, such as an HTTP header, that you want to inspect for extended-ascii injection). 6-48

63 Chapter 6 Developing Rules and Signatures Developing Signatures uunicode Converts %u-encoded characters to UTF-8 equivalents. htmlent Converts all types of entities (&...;), including decimal and hex, into their non-entity equivalents. escapes Converts C-style backslash-escaped characters into their non-escaped equivalents. nullsp Converts embedded NULL characters to spaces. Note that requests with NULL bytes are rejected during passive normalization, so that this aspect of normalization does not usually need to be performed on requests. However, it s provided as a mechanism for inspecting other types of content for NULL characters. nullremove Strips embedded NULL characters. Note that requests with NULL bytes are rejected during passive normalization, and this aspect of normalization does not usually need to be performed on requests. However, it s provided as a mechanism for inspecting other types of content for NULL characters. ccomment Strips C-/Javascript-style comments. xmlcomment Strips XML/SGML-style comments. backslash Strips backslashes \ selfref Strips self-reference paths:./ backref Strips back-reference paths:../ trailingslash Strips the trailing slash from a path white Normalizes and collapses whitespace runs to a single space character (ASCII 32) lower Converts all letters in string to lowercase. Developing Signatures A signature contains at least one content pattern designed to match messages of interest to rules. Messages matched by the signature are subject to the rule action. The system includes numerous built-in signatures. In addition you can create and apply your own, as described here. You first create signatures in a text file that you then upload to the Manager. The text file may contain one or more signatures, each of which must belong to a signature group. A rule applies a signature through a reference to its signature group, as illustrated in Figure 6-1. Figure 6-1 Ruleset and signature set file ruleset_file_1 signature_file_1 Rule Group sig_group_1 rule_1 rule_2 Rule_2 sig_group_1 sig_1 sig_ While the system does not impose requirements on how you organize signatures by groups, organizing signatures sensibly can help optimize performance. Since the ACE Web Application Firewall compiles each signature group into a single executable unit, multiple signatures in a single group can be applied 6-49

64 Developing Signatures Chapter 6 Developing Rules and Signatures to traffic more rapidly than the same number of signatures in multiple groups. As a general rule, signatures that target a particular class of attack should be grouped together into a single signature group. Keep in mind that if a particular signature within a group is not applicable for a given web application, policy developers can use a modifier to exempt the non-applicable signature for the application. A signature statement consists of an identifier for the signature, its group, and several other properties. One of the properties is the regex attribute, which contains a regular expression to be applied to message content. The regular expression implementation employed by web application security features of the Cisco ACE Web Application Firewall is PCRE (Perl-Compatible Regular Expressions). The regular expression can include PRCE regular expression special characters, such as a dollar ($) to match the end of a string or a caret (^) to match the start of a string. A backslash escapes special characters, causing them to be evaluated as simple characters. Not all PCRE features are supported. Specifically, referencing captured groups is not supported. Note For more information on the PCRE syntax, see Viewing Existing Signatures When creating your own signatures or rules, it is usually helpful to start from an example provided by one of the built-in resources. There are two views to the source code of the signatures loaded in the policy, the formatted view and the raw view: For the formatted view, click the View Signatures button in the Rules & Signatures page. All signature groups loaded in the system appears in the window. To view signatures in a given group, click the group s expander control. When expanded, the source of the regular expression pattern that comprises the signature appears. For the raw view, click the Rules & Signatures menu link, and then the Manage Signatures button. Click on the name of the signature set resource to view the source code of resource file in a new browser window. The raw view is helpful when you are first creating the signature source file. The formatted view is useful to quickly find regular expression patterns used in the system for various attack signatures. Basic Example As shown in the signature source code view, a basic signature declaration appears as follows: SQLInjection_m.drop:DROP regex: ;\s*\bdrop\b nocase: true name: DROP The sample has one signature, drop, which belongs to the signature group SQLInjection_m. Along with the signature name and group declaration, the signature has these properties: After the name declaration is a quick pattern expression, DROP, in this case. When used with a regular expression, this expression serves as an optimized, preliminary content test. You compose quick pattern expressions using a subset of the regular expression language features available for the regex attribute. For more information, see About the Quick Pattern section on page regex is the regular expression intended to match message content of interest. The regular expression pattern include the DROP string surrounded by the word boundary expression. 6-50

65 Chapter 6 Developing Rules and Signatures Developing Signatures nocase indicates whether the regular expression is applied with case-sensitivity enabled. By default, comparisons are performed in a case-insensitive manner. You can specify a case-sensitive comparison by including this attribute and setting its value to false. name is a descriptive name for the signature which appears in the web console interface. A rule applies a signature to traffic by referencing the name of the signature group, as follows: RULEGROUPNAME.RuleName:REQUEST_ALL sig SQLInjection_m The identifier following the sig keyword, SQLInjection_m, identifies the signature group. The following sections provide more information on the parts of a signature. About the Quick Pattern A signature can apply a regular expression to message content in two phases: the first is the quick pattern expression. If a message matches the quick pattern and the regex attribute also appears in the signature, the full regular expression in the regex attribute is applied to the message content. The quick pattern is an optimization feature that allows the ACE Web Application Firewall to quickly disqualify messages from signature applicability. It uses a limited regular-expression-like syntax to do a very fast initial check of the message. If the quick pattern matches a message, the ACE Web Application Firewall applies the full regular expression (if present). Both expressions need to produce a positive match for the rule to be triggered. A signature can have just one of a quick pattern or regex property, in which case only that expression needs to be satisfied by the message content for the rule action to be triggered. Note Rewrite rules can only use quick pattern expressions to match content. That is, they can only reference signatures that use quick patterns. In practice, the quick pattern commonly checks for the minimum character sequence that indicates potential content of interest, while the regular expression provides a more thorough test of the content, as illustrated by the built-in SQL injection signature for the DROP command: Quick pattern: DROP Regex pattern: ;\s*\bdrop\b The quick pattern expression syntax comprises a subset of the PCRE syntax. Besides literal character matching, it includes support for: Simple character class wildcards, such as. (dot) to match any character Pre-defined character classes, which include: \d digit \D not-digit \s whitespace \S not-whitespace \w word (alpha, numeric, or underscore) \W not-word User-defined character classes, such as [a-z]. Hex-encoded character literals, such as \x61 for a. 6-51

66 Developing Signatures Chapter 6 Developing Rules and Signatures Built-In Signature Notes The following notes apply to the built-in signatures included in the base configuration and available for your rule development. Unused signatures While most built-in signatures are applied by one of the built-in rules, several are not. They are included in the base configuration and are available for use in your custom rules. Quotes.single Quotes.double Tab.Tab SQLComment.dashdash These signatures match characters that are often present in legitimate messages. For instance, the single quote character may appear in surnames entered as form data, such as O Neil. You should use them, therefore, only if you are certain that they are appropriate for your application traffic or if applying the signatures in monitor mode only. CreditCard Signature group The built-in signature groups include several credit card signature groups that all look for credit card numbers of various lengths. Notice that the signatures will match any appropriately delimited (with spaces or hyphens) set of numbers of the specified length. They do not apply any checksum formula (such as the Luhn algorithm) to verify that the numeric sequence of a suspected credit card number is actually a valid credit card number. Uploading Custom Signatures When finished developing signatures, you upload them to the Manager to make them available in the policy. To upload custom signatures: Step 1 Step 2 Step 3 Step 4 Step 5 In the Rules & Signatures page, click the Manage Signatures button. Click the New Signature Resource button. Type a descriptive name for the signature resource. The name should be unique for signature resources in the policy. The name will appear in the signature resource list, so it should be sensible for other users of the web console. Locate the file that contains the signatures to be uploaded by clicking the Browse button and navigating to the file on your file system. Alternatively, if the resource is served by a web server, enter the URL at which it is available. Resources uploaded from a web server location are subject to the resource refresh feature, which provides for automatic reloading of resources at policy deployment. Click Upload. The Manager validates the signatures in the file and presents any errors it discovers. When finished the new resource appears in the resource list. After the signatures are successfully loaded into the policy, they can be used to identify content of interest in messages handled by the ACE Web Application Firewall. You can update the resource at any time by clicking the edit link next to the resource in the signature list and uploading an updated file in the edit resource page. 6-52

67 Chapter 6 Developing Rules and Signatures Developing Signatures General Signature Development Guidelines Each uploaded signature file comprises a single named resource in the policy. As such, it is subject to version-control and policy archiving features of the Manager. The following lists general guidelines for signature file composition: The first line of the signature file must be: # Cisco Signature File v. <majorversion>.<minorversion> The version numbers should match the system parser version against which you have created the signatures, 1.0 in the current release. The file is in the form of new-line-delimited lines. You can add single-line comments in the file by starting the line with a hash symbol (#). Other than the required first line of the file, lines that begin with the hash symbol do not affect operation of the signatures. Each signature should conform to the syntax rules described in Signature Syntax section on page To use extended (non-7-bit-ascii) characters in the signature file, you must set the signature source file to use UTF-8 encoding from your text editor. Signature Syntax The format for a signature definition follows: X-<sig_group_id>.<sig_id>: <quick_pattern> <attribute-name>: <attribute-value> <attribute-name>: <attribute-value>... Where: <sig_group_id> is the name of the signature group to which the signature belongs. To ensure uniqueness from built-in resources, the signature group names you create must start with X-. The entire name, including the X- prefix, cannot be longer than 15 characters. Signature groups do not need to be separately declared. <sig_id> is the identifier of the signature. It should not be longer than 15 characters. In any signature group or signature ID, you can use letters (case-sensitive), numbers, underscore characters (_), and hyphens characters (-). The IDs should be unique among signatures in the same group and should be descriptive of the signature. <quick_pattern> is a pattern expression that identifies content to be matched using a subset of the regular expression syntax. A signature must have at least one of a quick pattern or regular expression (regex attribute), and may have both. If both are present, the quick pattern is evaluated first. If matched to the message, the regex pattern is compared to the matched portion as a final check. In all lines of the signature, whitespace between the colon and the first non-whitespace character following the token is skipped. All other whitespace up to the new-line is significant. The signature can have any of the following optional attributes. regex, a PCRE-style regular expression used to match message content. While the regex attribute is optional, the signature must have at least one of a regex or quick pattern. name, a descriptive name for the signature that appears in the web console. 6-53

68 Developing Signatures Chapter 6 Developing Rules and Signatures cve is the optional CVE (Common Vulnerabilities and Exposures) identifier that describes the vulnerability the signature is intended to address. This information is useful for documenting the signature. nocase determines case-sensitivity of the regular expression comparison. By default, the comparisons are performed in a case-insensitive manner. You can include this attribute and set it to false to have case-sensitive evaluation. Each attribute should be on its own line, and should be preceded by one or more whitespaces. While the attributes are optional, it is recommended that all signatures have a name attribute for usability in the web console. To interoperate correctly with the Manager, the fixed character portion of a signature may not be longer than 31 characters. While signature group identifiers must be unique across the policy, signatures identifiers must be unique only within the context of the group. A rule can reference an individual signature by its fully qualified signature ID, which is made up of both the group and signature ID: <SigGroupID>.<SigID>. In most cases, however, a rule will reference the entire signature group. Sample Signature File An example signature list file follows: Example 6-1 Signature list file # Cisco Signature File v. 1.8 # Copyright Cisco Systems, Inc. All Rights Reserved X-NextThreat_b.exec:exec regex: ;\s*\bexec\b nocase: true name: exec nextthreat command attack X-NextThreat_b.kick: kick nocase: true name: kick nextthreat command attack X-NextThreat_m.start:start nocase: true name: start nextthreat command attack X-NextThreat_m.cmd: cmdshell nocase: true name: cmdshell nextthreat command attack X-PastThreat_m.cmd: dial nocase: true name: dial command attack X-Privacy.USSocialSec:\d\d\d-\d\d-\d\d\d\d name: Social Security number screening The example creates four signature groups, X-NextThreat_b, X-NextThreat_m, X-PastThreat_m, and X-Privacy. Following the convention of the built-in signatures, the signature groups are named with the first letter of their severity level appended to the group name, b for basic and m for moderate. While the examples set the nocase attribute to true (which means that signatures are applied in a case-insensitive fashion), setting this attribute to true is not strictly necessary since this is the default comparison mode. You can try loading the sample by copying the text of Example 6-1 into a text file, and loading it into the Manager as described in Uploading Custom Signatures section on page After loading the signatures, you can apply them in custom rules. 6-54

69 Chapter 6 Developing Rules and Signatures Developing Rules Developing Rules A rule specifies the signatures to be applied to message content. Custom message inspection rules and message rewriting rules are supported. Message inspection rules are only applicable to requests, whereas message rewrite rules are only applicable to response messages. A rule includes an expression that defines a condition for the rule action. In most cases, the expression is made up of the identifier for the part of the message to be checked and a reference to the signature to use for the check. It can also include functions, operators, or other advanced features. As with signatures, custom rules are developed in a text file which, once uploaded to the Manager, comprises a named resource in the Manager. Since a rules file is treated as a single resource in the Manager, if you need to create a large number of rule groups for many applications, it may make sense to organize rule groups across multiple source files. The following example shows the format of the rule set file: Example 6-2 Rule set file format # Cisco Rule File v. <major_version>.<minor_version> GROUP X-<rulegroup_id>:<rulegroup_name> X-<rulegroup_id>.<rule_name>:<message_inspection_scope> sig <siggroup_name> name: <rule_descriptive_name> sev: <severity_level> Rule set files must begin with the Cisco Rule file declaration as its first line. The version numbers should reflect the version of the rule set parser against which the rules are written, 1.0 for the current version of the rule parser. The GROUP keyword declares a rule group, which can contain one or more rules. User-created signature groups and rule groups must begin with the X- characters to ensure uniqueness with built-in rule groups. The rule definition starts by declaring the group to which it belongs. It then specifies the part of the message to be inspected and the signature used for the inspection. Example 6-3 Rule set file example # Cisco Rule File v. 1.0 # Group declarations GROUP X-InspectRules: My Inspection Rule group GROUP X-RewriteRules: My Message Rewrite Rule group # rule declarations X-InspectRules.NextThreat1:REQUEST_PARAM_ALL sig X-NextThreat_b name: Parameter inspection for Next Threat sev: 0 X-InspectRules.NextThreat2:REQUEST_HEADER sig X-NextThreat_b name: Header inspection for Next Threat sev: 0 X-InspectRules.NextThreat3:REQUEST_ALL sig X-NextThreat_m X-PastThreat_m name: Closer Inspection for Next Threat sev: 1 # rewrite rules X-RewriteRules.SsnMask: rewrite X-Privacy name: Prevents SSN leak 6-55

70 Developing Rules Chapter 6 Developing Rules and Signatures rewritechar: X desc: Finds and rewrites SSN The example defines three message inspection rules and a message rewrite rule. Note that the message inspection rules include a sev, or severity, property. The rule s sev value allows profiles to apply rules in a rule group selectively based on their severity, with values: 0 (basic), 1 (moderate), or 2 (strict). The message rewrite rule includes a rewritechar value, which is used to replace each character of the matched content in the message. The first two message inspection rules are distinguished by the part of the message to be inspected for the signature. You can try loading the sample rules by copying the text of Example 6-3 into a text file, and loading it into the Manager as described in Uploading Custom Rules section on page Before attempting to load the rules, you will need to upload the signatures listed in Example 6-1. After loading the rules, you can apply them in profiles. Viewing Existing Rules As with signatures, when creating your own rules, it is often helpful to start from an example provided by a built-in rule definition. To view the rule definitions, in the Rules & Signature page, click the Details link next to the rule, and then the View Source button at the bottom of the details page. The raw source code of the rule set appears. Uploading Custom Rules After you have finished developing rules, as described in the following sections, you will need to upload them to the Manager to make them available in the policy. To upload custom rule files: Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 In the Rules & Signatures page, click the New Custom Rules button. Type a descriptive name for the rule resource. The name should be unique for rule resources in the policy. The name will appear in the rule resource list, so it should be sensible for other users of the web console. To load the rules from an external text file, identify the file by clicking the Browse button and navigating to the file on your file system Click the Load File Contents button. The rule source code appears in the Rule Definitions field. Note that while you can type or paste the rule source code directly into this field, in most cases, it will be loaded from an external text file. If needed, make changes directly to the rule source code in the Rule Definitions field, although note that changes you make in this field will not be propagated to the original rules source file. Click Save Changes. The Manager validates the rules. Any validation errors are indicated at the top of the page. If rules reference signatures that have not been loaded, for instance, a rule validation error results. The custom rules now appear in the web console page, as shown in Figure 6-2. They are also listed in profiles, where they can be enabled to be made applicable to network traffic. 6-56

71 Chapter 6 Developing Rules and Signatures Developing Rules Figure 6-2 Custom rules in the web console In the Rules & Signatures page, you can view the source code of the resource by clicking the Details link next to the name of the custom rule. After loaded to the policy, the rule source code is modifiable by clicking the Edit Rule File button at the bottom of the details page. You can edit the rule file to add new rules, modify, or remove rules from the rule set resource. Removing a rule group removes its availability from all profiles, including those in which the rule group is enabled. General Rule Development Guidelines Each uploaded rule file comprises a single named resource in the policy. As such, it is subject to version-control and policy archiving features of the Manager. The following lists general guidelines for rule file composition: The first line of the rule file must be: # Cisco Rule File v. <majorversion>.<minorversion> The version should match the parser version of the system for which the rule are created, 1.0 in the current release. Single-line comments can be included in your file by starting the line with a hash symbol (#). Other than the required first line of the file, lines that begin with the hash symbol do not affect the operation of the rule set. The rule set may contain one or more rules and rule group declarations, in the form of new-line-delimited declarations. For manageability, rewrite rules and message inspection rules cannot be in the same group. Most elements of the rules files can have a desc property, which is intended to serve to document the item in the Manager user interface. Severity levels are indicated by the sev attribute, with possible values of 0 (basic), 1 (moderate), or 2 (strict). 6-57

72 Developing Rules Chapter 6 Developing Rules and Signatures Rule Syntax Rule Group Declaration As previously mentioned, you can create two types of rules for web application security: message inspection rules message rewrite rules The syntax between the two types varies slightly. However, both start by identifying the rule group to which it belongs, followed by a period, and then the rule s own identifier, as follows: SQLINJECTION.SqlInjection1:REQUEST_ALL sig SQLInjection... In the example, a new rule named SqlInjection1 is declared in the rule group SQLINJECTION. After the name is a colon (:) followed by the rule statement, which includes the part of the message to be inspected along with signatures to be applied. The example is a message inspection rule. A message rewrite rule starts with a similar arrangement of identifiers. However, the keyword rewrite follows the colon. The following sections provide details on the message syntax. A group declaration defines properties for a rule group. The only property applicable to group declaration is desc, a description property. Note that if there is no GROUP declaration for a rule group ID reference in a rule declaration, the rule group is created automatically. Its name will be set to the same value as its ID, and it will have an empty description. Rule groups are declared in the following format: GROUP X-<rule_group_id>: <group name> <wsp>desc: <description><newline> The declaration is made up of the following components: GROUP A keyword that identifies the statement as a group definition. <rule_group_id> The rule group identifier. The identifier has these characteristics: To ensure uniqueness with built-in rule groups, the group identifier must start with X-, The identifier must not be longer than 15 characters, including the required X- prefix. The rule group identifier must be unique among all rule groups. Legal characters in the identifier are upper- or lower-case letters, numbers, underscore characters (_), and hyphen (-) characters. <group_name> A user-friendly name for the rule group, for use in the Manager interface (for example, SQL Injection ). <wsp> A white space or tab precedes the group declaration attribute (the only supported group attribute is desc). <description> A description of the rule group. This description appears in the user interface after the rule file is uploaded. 6-58

73 Chapter 6 Developing Rules and Signatures Developing Rules Message Inspection Rule Format Message Rewrite Rule Format Message inspection rules use the following format. <rule_group_id>.<rule_id>: <rule_statement> <attribute-name>: <attribute-value> <attribute-name>: <attribute-value>... The rule is made up of the following: <rule_group_id> The identifier of the rule group to which the rule belongs. If a separate rule group definition for the group does not exist, the rule group is created. To ensure uniqueness from built-in rule groups, the group names you create must start with X-. The entire name, including the X- prefix, cannot be longer than 15 characters. <rule_id> The rule identifier. The identifier has these characteristics: The ID must be no longer than 15 characters. The rule ID must be unique among all rules in the group. Legal characters in any ID are case-sensitive letters, numbers, underscores (_), and hyphens (-). <rule_statement> A string defining a valid Reactor expression statement. For more information on this statement, see Rule Statement Format, page rule attributes A rule can have rule attributes in the form of name-value pairs. Each attribute should occupy its own line, and be preceded by one or more whitespaces. The attribute is in the form of a attribute name followed by a colon, and then the attribute value followed by a line break. Message inspection rules can have the following attributes: name A user-friendly name for the rule. desc A description of the rule that should document the rule for web console users. severity The severity level of the rule. If using severity levels, you define multiple rules that attempt to address a given security task at multiple levels of strictness or thoroughness. The profile can then apply the rule at the severity level desired for a given backend application. Rather than acting upon the entire message, message rewrite rules modify the portion of the message content matched by the signature. The signature may be matched multiple times in a single message. These rules are most commonly used to identify and overwrite sensitive content in a message. Rewrite rules can only use quick pattern expressions to match content. For more information, see About the Quick Pattern section on page Message rewrite rules have the following format. <rule_group_id>.<rule_id>: rewrite <sig_group_id> <attribute-name>: <attribute-value> <attribute-name>: <attribute-value>... The rule is made up of the following: <rule_group_id> The identifier for the rule group to which the rule belongs. If a separate rule group definition for the group does not exist, the rule group is created. <rule_id> The rule identifier. The identifier has these characteristics: The ID must be no longer than 15 characters. 6-59

74 Developing Rules Chapter 6 Developing Rules and Signatures Rule Statement Format The rule ID must be unique among all rules in the group. Legal characters in any ID are case-sensitive letters, numbers, underscores (_), and hyphens (-). rewrite The rewrite keyword identifies the rule as a message rewrite rule. <sig_group_id> The identifier of the signature group for the signatures that you want to apply in this rule. The signatures determine the content to be rewritten in messages subject to this rule. Rewrite rules can only apply signatures that use DFA expressions; it cannot apply PCRE expressions. Therefore, the regular expression \d{4,6} could not be used, and would have to be replaced with three different signatures, each one for a different pattern length. rule attributes A rule can have rule attributes in the form of name-value pairs. Each attribute should occupy its own line, and be preceded by one or more whitespaces. The attribute is in the form of an attribute name followed by a colon, and then the attribute value followed by a line break. Rewrite rules can have the following attributes: name: A user-friendly name for the rule. desc: A description of the rule that should document the rule for web console users. rewritechar A value that is used to replace the matched pattern in the signatures. The rewritechar is written once for every character in the matched pattern, so if the replacement character were x, the following matched string would be rewritten as: xxxxxxxxxxxxxxxx. The rule statement is generally a conditional expression which, if resolving to true, triggers the rule action. The rule statement appears after the colon following the rule ID: <rule_group_id>.<rule_id>: <rule_statement> The rule statement format is: <variable-expr> <operator> <test-value> For example: REQUEST_PARAM_ALL sig X-NextThreat_b In this case, sig is the operator. It applies the test value specified by the signature or signature group name (X-NextThreat_b) to the tested value (all parameters). Rule statements can comprise tests based on other factors than a rule match. For instance, the following statement checks the number of request parameters: REQUEST_PARAMS.count() gt 128 The sample tests whether the number of parameters in the requests exceeds 128. If true, the rule action is triggered. It is made up of: A variable, REQUEST_PARAMS A function, count(), and An operator, gt These rule expression features provide significant flexibility in defining custom rule behavior, as listed in these sections: Rule Operators Rule Variables 6-60

75 Chapter 6 Developing Rules and Signatures Developing Rules Rule Functions Rule Operators The following operators apply a binary test to a given test and tested value. If the test resolves to false, the tested content is excluded from rule applicability. The rule operators are listed inthe following table. Table 6-1 Rule operators Operator eq gt gte lt lte re nre sig True if the tested value is... equal greater than greater than or equal less than less than or equal a regular expression not a regular expression a signature group, with a value that is the name of a SignatureGroup Rule Variables Rule variables provide access to runtime information. Variables exist, for example, for request parameters, headers, and client information, such as the client IP. Variables allow you to create rule conditions based on these runtime values. In addition to rule composition, variables can be used in other areas of the policy as well. For example, you can include them in custom error response messages by referencing the variable in this form in the HTML response: $(varname). Also, they are available in header processing fields, so that variable values can be added as HTTP headers to outgoing messages. Note When developing rules, it may be helpful to test rule variables in a custom error response to quickly discover the types of values returned by each variable for your traffic. Certain variables can provide access to the values of named parameters associated with a request in the following form: VARIABLE_NAME['param'] Where param is the name of the web form variable. For example: REQUEST_HEADER['Referer'] sig CrossScript_m In this case, the HTTP request header Referer is specifically checked for a content match against the signatures in CrossScript_m. Request parameter values can be retrieved in a similar fashion by passing the name of the parameter as identified in the POST form. The variables available for rule development are listed in the following table. Where example return values are indicated, the return is based on a request URL of:

76 Developing Rules Chapter 6 Developing Rules and Signatures Table 6-2 Rule variables Variable CLIENT_IP CLIENT_PORT SERVER_IP SERVER_PORT REQUEST_ALL REQUEST_LINE REQUEST_URL_RAW REQUEST_URL_FULL REQUEST_QUERY_RAW REQUEST_URL_PATH REQUEST_URL_HOST REQUEST_HOST REQUEST_PARAM REQUEST_PARAM_NAMES REQUEST_PARAM_ALL REQUEST_GETPARAM REQUEST_GETPARAM_NAMES Description The IP of the client that made the request in dotted quad format. The listening port to which the client made the request. The IP of the server we are routing to in dotted quad format. The listening port of the destination server to be addressed. A collection of the URL path, all parameters, all headers, in name-value format for each, when appropriate. The complete request line including method and HTTP version. The request URL prior to normalization, such as: /details.do?v1=value1&v2=value2&v3=value3 The full request URL after normalization, such as: /details.do The query string portion of the request. The query string is the part of the request URL after a question mark, such as: v1=value1&v2=value2&v3=value3 The path portion of the request URL, such as: /details.do The host portion of the request URL, if present. The host of the request, either from the URL or the Host header. A collection of all parameter values after normalization, keyed on parameter names (if message contains both GET and POST args, both are present), such as: value1, value2, value3 A collection of all parameter names. A collection of all parameter names and values, keyed on parameter names, such as: v1, v2, v3, value1, value2, value3 A collection of all GET parameter values after normalization, keyed on parameter names, such as: value1, value2, value3 A collection of all GET parameter names, keyed on parameter names. 6-62

77 Chapter 6 Developing Rules and Signatures Developing Rules Variable REQUEST_GETPARAM_ALL REQUEST_POSTPARAM REQUEST_POSTPARAM_NAMES REQUEST_POSTPARAM_ALL REQUEST_HEADER REQUEST_HEADER_NAMES REQUEST_HEADER_ALL COOKIE COOKIE_NAMES COOKIE_ALL REQUEST_METHOD REQUEST_VERSION REQUEST_LENGTH AUTH_RAW AUTH_METHOD AUTH_USER AUTH_PASSWORD AUTH_DATA SSL_CIPHER SSL_CERT SSL_CERT_VERIFIED SSL_CERT_REVOKED SSL_DIGEST_SHA1 SSL_SUBJECT_DN SSL_ISSUER_DN Description A collection of all GET parameter names and values, keyed on parameter names, such as: v1, v2, v3, value1, value2, value3 A collection of all GET parameter values, after normalization, keyed on parameter names. A collection of all GET parameter names, keyed on parameter names. A collection of all GET parameter names and values, keyed on parameter names. A collection of all request header values, keyed on header names. A collection of all request header names. A collection of all request header names and values, keyed on header names. The cookie values, keyed on cookie name. An ordered list of all cookie names. Collection of all cookie names and values, keyed on names. The request method. The request HTTP version. The length of the request. The raw data of the Authorization header, including the method and Base64 region. Authentication method (from Authorization header, for example, Basic). Username value from Authorization header. Password value from Authorization header. Data from Authorization header, that is, the value after Auth method. The cipher used for the client SSL connection. The PEM-encoded client certificate, if present. Boolean value indicating whether the client certificate was verified. Boolean value indicating whether the client certificate was revoked. The SHA1 digest of the client's SSL certificate, if present. The Subject Distinguished Name of the client's SSL certificate, if present. The Issuer Distinguished Name of the client's SSL certificate, if present. 6-63

78 Developing Rules Chapter 6 Developing Rules and Signatures Variable Description SSL_SUBJECT_ALTNAME The Subject Alternative Name of the client's SSL certificate, if present. SSL_SUBJECT_KEYID The Subject Key Identifier of the client's SSL certificate, if present. SSL_PEER_CERT_EXTENSION A collection of the extension values of the client's SSL certificate, keyed on names. SSL_PEER_CERT_EXTENSION_OID A collection of the extension values of the client's SSL certificate, keyed on OIDs. SSL_PEER_CERT_EXTENSION_NAMES A collection of the extension names of the client's SSL certificate, keyed on names. SSL_FINGERPRINT_CHAIN An ordered list of fingerprints in the client's SSL CA verification chain. SSL_VERSION The version of the SSL session, one of TLSv1, SSLv2, SSLv3, or an empty string. REQUEST_MULTIPART_HEADERS A collection, keyed on name, of all the headers of a multipart/form-data message's parts. All parts are aggregated into a single collection, so REQUEST_MULTIPART_HEADERS['Content-type' ] will return all content-types of all parts. REQUEST_MULTIPART_DISPOSITIONS The simple value of the Content-Disposition header of all the parts of a multipart/form-data message. This is typically form-data. REQUEST_MULTIPART_DISPOSITION_NAMES The name parameters of all the Content-Disposition headers of all the parts of a multipart/form-data message. REQUEST_MULTIPART_DISPOSITION_FILENAMES The file name parameters of all Content-Disposition headers of all parts of a multipart/form-data message. REQUEST_BODY_RAW The body portion of the request prior to normalization. REQUEST_BODY_XML The body portion of the request as XML content. RESPONSE_HEADER A collection of all response header values, keyed on header names. RESPONSE_HEADER_NAMES A collection of all response header names. RESPONSE_HEADER_ALL A collection of all response header names and values, keyed on header names. REQUEST_PATH_AND_QUERY_RAW The resource path and query portion of the request URL prior to normalization. Rule Functions Rule functions apply special processing operations to rule values before the rule is evaluated. The following functions are available for rule composition. Note that they are also available in other contexts of the policy, such as in custom error response text or header processing fields. To apply a function to a variable value in a error response, enter them in the form $(varname.function), such as $(REQUEST_PARAMS.count()). 6-64

79 Chapter 6 Developing Rules and Signatures Developing Rules Table 6-3 Rule functions Function count() size() maxsize() urlencode() normalize(expr) Description Returns the number of items identified by variable, such as REQUEST_PARAMS.count(). Returns the total size of items referenced by variable. Returns the size of the largest value of items referenced by variable. Converts all values referenced by variable to their URL-encoded equivalent. Normalizes items specified by the expr parameter. By normalizing a value, the function transforms it into canonical form, removing arbitrary variations or possible harmful content. For more information, see normalize() Function section on page

80 Developing Rules Chapter 6 Developing Rules and Signatures 6-66

81 CHAPTER 7 XML Threat Defense This chapter describes the XML validation and threat defense features of the Cisco ACE Web Application Firewall. It covers these topics: About XML Threat Defense Tuning Threat Defense Settings About XML Threat Defense While the ACE Web Application Firewall does not provide the advanced XML and Web Service security and integration capabilities of the Cisco ACE XML Gateway product, it does include features for defending against XML threats. The XML threat defense features can identify and defend against XML-based attacks, such as XML denial-of-service (XDoS) attacks. Threat defense settings allow you to apply limits based on various properties of XML messages, including their size, number of elements, size of attributes, and so on. When the ACE Web Application Firewall encounters a message that violates a rule, it logs the event and drops the message. In addition to XML-specific threat inspection, an XML message is subject to message inspection rules and other processing measures configured for the profile applied by the virtual web application. Tuning Threat Defense Settings The settings for XML threat defense are preconfigured with values that are appropriate for most purposes. You can view and modify the values as follows: Step 1 Step 2 Step 3 Step 4 In the web console, click the System Management link on the navigation menu. Under the ACE Web Application Firewall header, click the I/O process settings link. The settings appear under the Reactor heading. Configure the settings as desired. Examples of settings available include maximum document size, element levels, attributes per element, and so on. For details on the settings, see the online help page accessible from the I/O process settings page. Click Save Changes to have your changes saved to the working policy. Once the policy is deployed, incoming requests that do not meet the requirements you have configured are blocked by the ACE Web Application Firewall. 7-67

82 Tuning Threat Defense Settings Chapter 7 XML Threat Defense 7-68

83 CHAPTER 8 Working with Ports and Hostnames This section describes how to open ports on the ACE Web Application Firewall to listen for client HTTP or HTTPS requests. It covers these topics: About HTTP Ports, page 8-69 Opening a Port, page 8-70 Listening on a Virtual Hostname, page 8-71 Configuring a Static Content Response, page 8-72 About HTTP Ports Clients access applications proxied by the ACE Web Application Firewall by addressing requests at the port number specified in its consumer interface. You can open an HTTP listening port on the ACE Web Application Firewall, and manage its configuration settings, using a port object. Port objects are created for you when you define new virtual web applications. However, you can also create them manually or modify existing definitions. The ACE Web Application Firewall policy includes a built-in listening port for HTTP port 80. You can open additional listening ports using the HTTP Port policy object. You may need to open additional ports, for example, for SSL-secured connections (conventionally on port 443). After adding the listening port, you apply it to a virtual web application to have requests for the service handled on the port. Note The built-in default HTTP port (80) cannot be deleted, since it is used by certain internal system processes. However, you can edit the built-in port object by changing its name, port number, or other values from the Open HTTP(S) Ports page. The port object contains settings that allow you to set up a name-based or IP-based virtual host for the ACE Web Application Firewall. The port can be configured to listen for traffic addressed to a particular hostname or IP address. A port can be configured to respond to requests at a particular URL with a static response message. This capability is most often used to enable health monitoring of the ACE Web Application Firewall by upstream load balancers or other network hosts. 8-69

84 Opening a Port Chapter 8 Working with Ports and Hostnames Note In the ACE XML Gateway chunked requests can be handled by the Reactor only. That is, the Flex Path does not support chunked requests (requests that indicate chunked transfer encoding). If it receives a chunked request, the ACE XML Gateway responds with a 411 error response code. Chunked responses from the backend server are supported, but for messages handled by the Flex Path, the Gateway assembles the chunked response prior to delivery to the client. Chunked responses handled by the Reactor are passed through chunked. Opening a Port To open a listening port on the ACE Web Application Firewall: Step 1 Step 2 Step 3 Step 4 Step 5 While logged into the web console as an Administrator user or as a Privileged user with the Routing role, set the active subpolicy to the one in which you want to use the port. Click the HTTP Ports & Hostnames link in the navigation menu. In the Open HTTP(S) Ports page, click the Add a New Port button. In the Edit Port page, type a descriptive name for the new port definition in the Name field. This name identifies the port in the ACE Web Application Firewall Manager's console. It should be unique for port objects in the policy. Type the listening port number in the Port Number field. Note To ensure proper operation of the system, be sure to avoid using port numbers reserved for administrative purposes by the ACE Web Application Firewall and Manager. These include ports in the range of 8200 through 8299 and 514. For a complete list of ports that may be used by the system, see Cisco ACE Web Application Firewall Administration Guide. Step 6 Step 7 Step 8 To have the ACE Web Application Firewall apply transport layer security to traffic on the port, select the SSL checkbox. The Public/Private Keypairs menu and Upload button are enabled. If SSL is enabled, choose an item from the Public/Private Keypair menu to specify the public/private keypair to be used for encrypting this connection. If the correct keypair does not appear in the menu, it needs to be uploaded to the policy using the Upload button. For more information on SSL, see Securing Traffic with SSL/TLS section on page Optionally, specify the ciphers to be accepted in negotiating SSL connections with clients on this port in the SSL Cipher Suite menu. In the course of negotiating a secure connection, the ACE Web Application Firewall and client must be able to agree on the cipher suite to use for the connection. If the client does not support any cipher you specify here, the connection is not permitted. By default, the connection will use the global SSL Cipher Suite settings for the HTTP server process of the ACE Web Application Firewall, as set in the System Management > I/O Settings page. This option lets you apply more specific settings for this port. Specify a cipher suite by choosing custom from the SSL Cipher Suite menu and in the field that appears, enter the cipher suite to be accepted in OpenSSL Cipher string format, described here:

85 Chapter 8 Working with Ports and Hostnames Listening on a Virtual Hostname Note Use care when entering the cipher suite string. The ACE Web Application Firewall Manager web console interface does not verify the value you enter. If you mistype or enter a meaningless value, the ACE Web Application Firewall may not be able to open an SSL connection with the server. Step 9 Step 10 Step 11 The port can listen for all traffic on this port or only for traffic on this port addressed to a particular host or IP address. This setting allows you to set up virtual hosts (vhosts) at the ACE Web Application Firewall, by either hostname and IP address. Specify the requests this port is to monitor from the Listen For menu, from these options: All traffic on this port The port listens for any traffic addressed to the Firewall on this port. Requests to a hostname The port listens for any traffic addressed to the Firewall on this port and to this hostname. Specify one or more hostnames by typing the literal hostname or a POSIX regular expression in the Hostname field. To use a regular expression, click the Allow regular expression matching in the hostname checkbox. Requests to specific IP addresses The port listens for any traffic addressed to this IP address. Enter one or more IP addresses in the IP Addresses field. Use paragraph returns to separate multiple IP addresses, so that each address is on its own line. Any IP address you enter must also be configured at the network interface for each Firewall appliance. For more information, see the Cisco ACE Web Application Firewall Administration Guide. You can serve a static response message at a particular URL on this port by choosing the serve the following static page on this port option from the Static Content menu. For more information, see Configuring a Static Content Response section on page Click Save Changes. The port now appears in the HTTP Port menu in virtual service configuration pages. Listening on a Virtual Hostname The ACE Web Application Firewall supports IP-based and name-based virtual hosting. This support allows the Firewall to serve as a reverse proxy for multiple addressable hosts. The virtual hostname settings for the ACE Web Application Firewall appear in the port object configuration in the policy. A virtual hostname on a port directs the ACE Web Application Firewall to service requests addressed to the specified hostname. You can configure multiple ports in the policy to listen on a single port number, but each on a different hostname or IP address. To set a virtual hostname for the ACE Web Application Firewall, follow these steps: Step 1 Step 2 Create or modify the port object on which you would like the ACE Web Application Firewall to listen to requests for the host. For more information on creating port objects, see Opening a Port section on page In the Listen For menu, choose requests to a hostname, for name-based virtual hosting, or requests to specific IP addresses, for IP-based virtual hosting. 8-71

86 Configuring a Static Content Response Chapter 8 Working with Ports and Hostnames Step 3 Step 4 Step 5 If you configured the port to listen for requests to an IP address, specify the IP addresses in the text field. The IP addresses you enter must also be configured on the network interface of the ACE Web Application Firewall appliance. For more information, see the Cisco ACE Web Application Firewall Administration Guide. If you configured the port to listen for requests to a hostname, enter the hostname in the text field. You can use regular expression matching for the hostname by checking the Allow regular expression matching in the hostname box and entering the hostname as a regular expression, such as: ^example$ example:80 example.cisco.com In this case, the port accepts requests in which the host is addressed as example (as a whole word), example.cisco.com, or example:80. Note that with regular expression matching enabled, a value in host of simply example would match any request URL in which example appears as a substring, which may or may not be as intended. Click Save Changes when finished and deploy the policy to have the changes take effect at the ACE Web Application Firewall. Configuring a Static Content Response The ACE Web Application Firewall can be configured to serve a static response message at a particular URL on a port. Other network elements (such as load balancers) can use this mechanism to perform health checks against the ACE Web Application Firewall. You can set up a static response in the form of an HTML page, SOAP response, text only response, and more. There are a few points to note regarding static response pages: A virtual host configuration for a port (that is, a particular configuration in the Listen For option) does not affect the static page response. That is, if you configure port 8080, for instance, to listen only for requests to the hostname mygateway, the static content page will be served for a request to the configured URL path at port 8080, regardless of the hostname requested. Load balancers sometimes send HEAD method requests for health checks on balanced devices. The response page on the port automatically responds to HEAD method requests as well as GET requests. If you enable compression on the port, compression does not apply to the static response. To set up a static response: Step 1 Create or edit a port object, as described in Opening a Port section on page 8-70 Step 2 From the Static Content menu, choose the option serve the following static page on this port. Step 3 For the Path, specify the URL path for addressing the response. Step 4 Choose the type of response from the Content-Type menu: HTML XML SOAP Text or a custom response 8-72

87 Chapter 8 Working with Ports and Hostnames Configuring a Static Content Response Step 5 Notice that you need to enter the appropriate body content given the response content type. For HTML, for instance, this means that appropriate markup tags are included in the response. In the Body field, enter the body of the response message. The body needs to include markup tags appropriate for the content type you chose, if appropriate. For example, for a SOAP message, the body must include the XML element and envelope markup, as in the following figure. Figure 8-1 Static Content Message Configuration Step 6 Click Save Changes to commit changes to the working policy. When the policy is deployed, the page is available at the ACE Web Application Firewall address, such as:

88 Configuring a Static Content Response Chapter 8 Working with Ports and Hostnames 8-74

89 CHAPTER 9 Configuring Destination Server Settings This chapter explains how to manage settings for protected backend systems. It covers these topics: About Destination Servers, page 9-75 Working with Destination HTTP Servers, page 9-75 Integrating with ACE Application Switches, page 9-77 Using an HTTP Echo Server, page 9-80 Removing a Server Definition, page 9-81 About Destination Servers In the ACE Web Application Firewall policy, settings for a backend system for which you want to process and validate traffic are contained by an HTTP server object. Server objects are created for you when you define new virtual web applications. However, you can also create destination HTTP server definitions manually or modify existing definitions. The destination server settings are primarily made up of connection settings that the ACE Web Application Firewall uses to forward requests to the backend system. The actual endpoint identified by the destination HTTP server definition may be the server that hosts the application or a logical server that represents a server farm or virtual server. An echo server is a type of server definition in which the ACE Web Application Firewall itself generates and returns a response instead of an external backend system. The Firewall either echoes the request or returns a static response page configured for the server definition. An echo service is useful for testing a policy or performing message validation in callout fashion. This chapter describes how to configure servers in the ACE Web Application Firewall Manager. A server definition can be generated automatically, when defining a virtual web application, or created manually. Working with Destination HTTP Servers An HTTP server definition holds settings for a particular backend server, such as its network address, listening port, and whether SSL is required for the connection. To create, edit or remove server objects, you need to be an Administrator user in the console, or a privileged user with the routing role. 9-75

90 Working with Destination HTTP Servers Chapter 9 Configuring Destination Server Settings Adding a Destination HTTP Server Creating an HTTP server enables you to associate traffic processing rules to the server. Destination servers are created for you when you define new virtual web applications. However, you can also create destination HTTP server definitions manually, as follows: Step 1 Step 2 Step 3 Step 4 In the ACE Web Application Firewall Manager web console, set the active subpolicy to the one in which you want to add the destination HTTP server definition. Click the Destination HTTP Servers link from the navigation menu. On the HTTP Servers page, click Add a New HTTP Server. Type a descriptive name for the server definition in the Name field. This name is used within the console only, and should identify the server definition to other users of the web console. It should be unique for HTTP servers in the policy. Note For server objects generated through the application virtualization process, the ACE Web Application Firewall Manager uses the hostname and port number for the default server name, such as server.example.com:80. Since this value is used for identification only, however, it can be any value that helps you distinguish this server definition from others. Step 5 Step 6 Step 7 In the Host field, type the hostname of the backend server. The host value must be the DNS name of the backend system (such as swan.example.com) or its IP address (such as ). You do not need to type the protocol prefix ( in the field. In the Port field, specify the port number on which the backend server listens for service requests. If you do not specify this value correctly, the service descriptor cannot pass traffic to the service correctly. Most HTTP servers use port 80 for normal web traffic or port 443 for SSL connections. To configure SSL for the connection to the backend server: a. Click the SSL checkbox. Only choose this option if the server supports SSL connections. b. In bilateral SSL, the client must authenticate itself to the server, as well as vice versa. If the server requests client authentication (the ACE Web Application Firewall, in this case), the Firewall can present the certificate you specify in the field labelled If requested, use client public/private keypair. If the keypair you want to use is not listed in the menu, click Upload to add it as a resource to the policy. c. Specify how the ACE Web Application Firewall validates certificates that the backend HTTP server presents from these options: To accept any certificate the server presents, leave the Require remote server certificate signed by this CA certificate option at its default value, none. This setting is the default. To accept any certificate authenticated by a specified Certificate Authority (CA), select the Require remote server certificate signed by this CA certificate option and choose the CA certificate from the menu. If the certificate does not appear in the menu, choose Upload and add the certificate to the ACE Web Application Firewall Manager's list of Trusted Certificate Authorities. 9-76

91 Chapter 9 Configuring Destination Server Settings Integrating with ACE Application Switches Step 8 To specify that the server must present a certificate identical to a specified certificate, click the Require a certificate from the remote server that is identical to this certificate button and choose the certificate from the menu. If the certificate does not appear in the menu, choose Upload and add the certificate to the ACE Web Application Firewall Manager's list of remote server certificates. Optionally, specify the ciphers to be accepted in negotiating SSL connections to this backend server with the SSL Cipher Suite menu. In the course of negotiating a secure connection, the ACE Web Application Firewall and server must be able to agree on the cipher suite to use for the connection. If the server does not support any cipher you specify here, the connection is not permitted. By default, the connection will use the global SSL Cipher Suite settings for the HTTP client process of the ACE Web Application Firewall, as set in the System Management > I/O Settings page. This option lets you apply more specific settings for this server. Specify a cipher suite by choosing custom from the SSL Cipher Suite menu and, in the field that appears, enter the cipher suite to be accepted in OpenSSL Cipher string format, as described here: Note Use care when entering the cipher suite string. The ACE Web Application Firewall Manager web console interface does not verify the value you enter. If you mistype or enter a meaningless value, the ACE Web Application Firewall may not be able to open an SSL connection with the server. Step 9 Click Save Changes to finish the server configuration. When finished, the server can be used in virtual web applications in the policy. Integrating with ACE Application Switches In production networks, application servers are rarely accessed directly by the client applications. Instead, they are usually proxied by one or more load balancers. The ACE Web Application Firewall Manager includes capabilities for rapidly integrating backend services that are proxied by the Cisco Application Control Engine (ACE) Application Switch. The ACE Application Switch is a high performance application switch that maximizes the availability, performance, and security of applications on the network. By inspecting the ACE Application Switch configuration, the ACE Web Application Firewall Manager can quickly generate the policy configuration needed to route service traffic to application servers behind the ACE Application Switch. Figure 9-1 Downstream ACE Appliance configuration services service consumer ACE Web App Firewall ACE Application Switch services services

92 Integrating with ACE Application Switches Chapter 9 Configuring Destination Server Settings In ACE configuration terms, the ACE Application Switch exposes a backend server farm to the external network through a virtual IP (VIP). The ACE Web Application Firewall Manager issues a query an ACE Application Switch virtual device context to discover the VIPs it presents. After performing VIP discovery, the ACE Web Application Firewall Manager presents the VIPs it found for the Cisco ACE virtual device. You can choose the VIPs for which you want to generate HTTP Server objects, which can then be used as the backend service destination for a virtual service. The ACE Web Application Firewall Manager works with the following versions of the ACE Application Switch: Cisco ACE appliance, software versions A1(7) and higher Cisco ACE module, software versions A1(0), A2(0), and higher Integrating the ACE Application Switch and ACE Web Application Firewall configuration occurs in two phases: 1. Set up the connection to the ACE Application Switch virtual device from which you want to import VIPs. 2. At any time after configuring the ACE virtual device connection, direct the ACE Web Application Firewall Manager to inspect the Cisco ACE virtual device and generate server objects from selected VIPs. Every time you have the ACE Web Application Firewall Manager performs VIP discovery on a particular ACE virtual device, the ACE Web Application Firewall Manager treats the discovery as a new event; that is, it will find and report VIPs for which you have already configured HTTP server objects. However, the ACE Web Application Firewall Manager prevents you from generating duplicate server objects from VIPs that were previously imported. It does not attempt to perform any type of configuration update for VIPs that have already been imported. Note SSL connection requirements for backend servers as configured in the ACE Application Switch are not propagated to the HTTP server object generated by VIP import in the ACE Web Application Firewall policy. After importing a VIP for a backend SSL server, you will need to enable SSL connection encryption in the object settings manually. The server management features provided by the ACE Web Application Firewall differ between manually created HTTP server objects and those generated by VIP import. While request throttling is configurable for ACE-based server objects, server pooling is not (since ACE Application Switches are generally relied upon to perform the task of load balancing backend servers). Setting Up the Cisco ACE Virtual Device Connection To import VIPs from the ACE Application Switch, first specify the connection to the virtual device on the ACE Application Switch. Keep in mind that this connection is used only for policy development on the ACE Web Application Firewall Manager. Service traffic will be sent to the connections that are generated from the VIPs found on the Cisco ACE virtual device. Also note that the ACE Web Application Firewall Manager does not modify the configuration of the ACE device specified by this connection. That is, the ACE Web Application Firewall Manager performs read-only operations on the Cisco ACE device only. To configure a connection to a Cisco ACE virtual device: 9-78

93 Chapter 9 Configuring Destination Server Settings Integrating with ACE Application Switches Step 1 Step 2 Step 3 Step 4 Step 5 In the ACE Web Application Firewall Manager web console, click the Destination HTTP Servers link in the navigation menu. Click the Configure Integrated ACE Management button. Click the Add ACE Application Switch button. Enter values in the following fields: ACE VLAN Address The IP address for the ACE Application Switch virtual device that has the VIPs you want to import. This address should correspond to a particular VLAN address in the ACE configuration. HTTP(S) Port The port number on which this Cisco ACE virtual device listens for HTTP requests. Use HTTPS Whether the ACE Web Application Firewall should use SSL when connecting to the ACE Application Switch to inspect and import VIPs. Note that the ACE Web Application Firewall can use secure socket layer security to access the ACE device, but it cannot verify the certificate on the ACE Application Switch (since the certificate cannot be imported into the ACE Web Application Firewall policy). If accessing an ACE appliance using SSL, you usually need to connect to port (Port 443 is reserved for other uses on the ACE appliance.) Username The username for an administrative account for this ACE Application Switch virtual device. Password The password for the specified user account. Connection Timeout The amount of time after which the Manager should abandon its attempt to validate the connection and discover VIPs from the Cisco ACE application switch. Note that this value applies to each individual request within the inspection event, not to the overall time it takes for the inspection. Click Save Changes. The ACE Web Application Firewall Manager validates the connection to the Cisco ACE virtual device, and performs an initial inspection of its configuration. If successful, the newly defined connection appears in the ACE table. You can now import VIPs from the Cisco ACE virtual device by clicking the Import VIPs link for the connection and following the instructions in the following section. Generating Server Definitions from VIPs After configuring the ACE Application Switch virtual device connection, you can import VIP information at any time. In this process, the Manager inspects the ACE virtual device for the VIPs it exposes and presents them in the web console. You can choose the VIPs for which you want the Manager to generate HTTP server objects, as described in the following procedures: Step 1 If it is not already open, access the HTTP Servers page by clicking the Destination HTTP Servers link in the navigation menu. The Cisco ACE device connections that have been configured appear in the ACE portion of the HTTP Servers list. For information on configuring connections, see Setting Up the Cisco ACE Virtual Device Connection section on page

94 Using an HTTP Echo Server Chapter 9 Configuring Destination Server Settings Step 2 Click the import VIPs link next to the ACE virtual device from which you would like to import VIPs. The ACE Web Application Firewall Manager takes a moment to inspect the ACE Application Switch. When it finishes, a list of IP addresses and port numbers appear for the VIPs presented in the ACE virtual device. Note The ACE Web Application Firewall does not support import of any VIP that matches a range of IP addresses in the ACE Application Switch policy. Step 3 Choose the VIPs for which you want to create server objects by selecting their check boxes. If a port number on the VIP is a range (as it is for the any port selection in the ACE policy), enter the specific port number on which you want requests to the backend ACE application switch to be sent in the text field next to the VIP. Note If you want messages to be sent to one of several ports on the backend VIP, you will need to create a server object for each different port. You will need to repeat the VIP import process to create backend server objects for the additional ports. Step 4 After choosing the VIPs for which you would like to create HTTP server objects, click the Create HTTP Servers button. The VIPs appear in the HTTP Servers table. You can now use the VIPs in the backend service configuration for virtual services in the policy. Using an HTTP Echo Server If a virtual service uses an echo server as its backend service, the ACE Web Application Firewall produces the response instead of an external server. The response can be a fixed response (such as a HTML page or SOAP response configured in the policy) or the original request reflected back to the client. An echo server is useful in several ways: It can be used if the backend system is under development and not ready to receive requests. The echo service lets you test client-side applications before the backend service is ready. The ACE Web Application Firewall can validate messages outside the main traffic stream. Echo servers work only with virtual services that are HTTP-based. It does not work for messaging servers, such as MQ Series. To set up an echo server, follow these steps: Step 1 Step 2 Step 3 Click the Destination HTTP Servers link in the navigation menu and then the Add a New HTTP Echo Server button. In the New Server page, provide a distinguishing name for the echo server definition in the Name field. The name should be unique for echo server definitions in the policy. Choose how the response will be generated from these options: 9-80

95 Chapter 9 Configuring Destination Server Settings Removing a Server Definition Echo reflects the request back to the client. Any processing or validation settings specified in the policy are applied to the message as it traverses the Firewall. The echo server itself does not process the message except to adjust HTTP headers as needed; that is, it removes request-specific HTTP headers and adds response-specific HTTP headers before reflecting the message back to the Firewall for response processing. Fixed returns the response you configure with the Status Code, Content-Type, Other Headers, and Body fields. (In addition to the headers configured here, the echo server adds the Content-length HTTP header to the returned message, with the appropriate value given the message size.) Asynchronous always returns an HTTP response with a return code of 202. This option is functionally equivalent to choosing Fixed response and setting the Status Code to 202 Accepted. Note For more information on these options, see the discussion following these steps. Step 4 Step 5 Click Save Changes to save your changes to the working policy. In the Backend Service settings for a service definition for which you want messages to be echoed, choose the echo server definition as the host server. For new objects, the echo server is available in the list of servers available for the service interface. Removing a Server Definition You can remove server definitions by clicking the Destination HTTP Servers or Messaging Servers link in the console navigation menu. In the servers list, remove a server by clicking the remove link next to the entry for the server. Confirm the operation when prompted. You can remove a server only if there are no service definitions that use the server. In order to delete the server in these cases, either delete the object that depends on the server or change it to another server. 9-81

96 Removing a Server Definition Chapter 9 Configuring Destination Server Settings 9-82

97 CHAPTER 10 Securing Traffic with SSL/TLS This chapter describes how to use SSL/TLS to secure service traffic. It covers these topics: About SSL/TLS Traffic Encryption, page Securing the Service Consumer Connection, page Securing the Service Provider Connection, page About SSL/TLS Traffic Encryption The Secure Sockets Layer (SSL) and subsequent standardization of SSL, Transport Layer Security (TLS), are a widely used method of securing network traffic. You can use SSL with the ACE Web Application Firewall to secure communication between the ACE Web Application Firewall and service consumer or between the ACE Web Application Firewall and backend service provider. To use SSL with consumer connections, you need to upload and specify a public/private keypair to be used to establish the SSL session. For information on loading keypairs, see Uploading a Keypair Resource section on page Note that SSL is used in the system for purposes other than securing service traffic as well. The ACE Web Application Firewall Manager serves the web console over SSL, for instance. Also, log and administration information is passed between the ACE Web Application Firewall and Manager by SSL. Therefore, there are several areas in the web console for configuring SSL certificates. This chapter describes how to set up the ACE Web Application Firewall to use SSL specifically for service traffic. Securing the Service Consumer Connection To use SSL for the consumer connection, the ACE Web Application Firewall needs to have a public/private keypair. The keypair can be either a self-signed certificate or one signed by a Certificate Authority. A self-signed certificate is normally sufficient if the consumer is internal to your organization. For other purposes, you should use a CA-signed certificate. For compatibility with certain types of clients, a certificate used for a port at the ACE Web Application Firewall (as described here) may need to be configured as a server certificate. That is, the certificate needs to have an X509v3 Extended Key Usage attribute of TLS Web Server authentication. This is only a potential requirement for certain clients, however; the ACE Web Application Firewall system does not require you to use server certificates and non-server certificates may work in many instances. To configure an encrypted channel between the ACE Web Application Firewall and consumers: 10-83

98 Securing the Service Consumer Connection Chapter 10 Securing Traffic with SSL/TLS Step 1 Step 2 Step 3 Step 4 Step 5 Click the HTTP Ports & Hostnames link in the navigation menu. If the port on which you want to configure SSL connections already exists, click the edit link for that port. If the port does not exist, open the port as described in Chapter 8, Working with Ports and Hostnames. Conventionally, port number 443 is used for SSL. However, you can use any port number you like, including port 80, the default port number for non-secured HTTP communication. In the Edit Port page, click the SSL check box. When this option is selected, SSL encryption is used for communication on that port. In the Public/Private Keypairs menu, choose the keypair you want to use for the connection. If the keypair you want to use is not already uploaded in the ACE Web Application Firewall Manager, follow the directions in Uploading a Keypair Resource section on page to upload the keypair. During SSL connection setup, the ACE Web Application Firewall and client negotiate various parameters of the connection, including the SSL Cipher Suite to be used for message encryption or authentication. By default, the ACE Web Application Firewall is not selective about the cipher suite it will accept on a port. It will accept most encryption algorithms, including those using 64 or 56 bit keys. Specifically, the default Cipher Suite list it uses is: ALL:!ADH:!EXPORT:!SSLv2:!LOW:+HIGH:+MEDIUM You can limit the cipher suites that are accepted by the ACE Web Application Firewall on the port by choosing custom from the SSL Cipher Suite menu. In the text field that appears, enter the set of cipher suites to be permitted in standard OpenSSL Cipher string format, as described here: For example, to permit only algorithms that use keys that have a length of 128 bits or greater and not anonymous DH, use: HIGH:MEDIUM:!ADH This is equivalent to specifying: DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA :EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA: DES-CBC3-SHA:DES-CBC3-MD5:DHE-RSA-AES128-SHA: DHE-DSS-AES128-SHA:AES128-SHA:DHE-DSS-RC4-SHA: KRB5-RC4-MD5:KRB5-RC4-SHA:RC4-SHA:RC4-MD5: RC2-CBC-MD5:RC4-MD5:KRB5-DES-CBC3-MD5: KRB5-DES-CBC3-SHA If the client is not capable of using any of the SSL Cipher Suites specified, the connection is not permitted. The event log will show a warning level event similar to: Terminating HTTP session: 400 Bad request. Note Use care when entering the cipher suite string. The ACE Web Application Firewall Manager interface does not verify the value you enter. If you mistype or enter a meaningless value, the port will be unusable. Step 6 Click Save Changes to finish the port configuration. Now you can configure the virtual web application or virtual service object to use the port. For example, for a virtual web application, perform these steps: 10-84

99 Chapter 10 Securing Traffic with SSL/TLS Securing the Service Provider Connection Step 1 Step 2 Step 3 Step 4 Step 5 Click Virtual Web Applications on the navigation menu. Select the basic virtual service object or handler for the service for which you would like to secure traffic. Click Edit next to the Consumer Interface heading of the properties page for the virtual service. For the Port value, choose the port you just configured for SSL from the list. Click Save Changes to commit the changes to the active subpolicy. This completes the client side SSL configuration. Deploy the policy to have the changes take effect at the Firewall. Securing the Service Provider Connection You can configure SSL encryption for connections between the ACE Web Application Firewall and backend service providers. To secure the backend server connection, you ll need to have the appropriate security resource for verifying the server certificate, either a remote server certificate or the certificate of the trusted CA used by the remote server. To specify trust for a CA, you need to import its certificate in the policy. By default, the policy contains no preloaded CA certificates. Note that the ACE Web Application Firewall also supports bilateral SSL, in which the ACE Web Application Firewall authenticates itself to the backend system. To use bilateral SSL, you ll need to have the ACE Web Application Firewall s public/private keypair loaded to the ACE Web Application Firewall Manager. To configure bilateral SSL: Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Click the Destination HTTP Servers link in the navigation menu. If the server for which you want to configure SSL already exists, click the view link for that server. If the server does not appear in the server list, click the Add a New Server button and configure the backend server as described in Adding a Destination HTTP Server section on page In the Edit Server page, click the Edit link next to the general settings heading. To have communication with the server occur over an SSL channel, enable the SSL option. The controls for configuring the SSL channel are enabled. In bilateral SSL, the server asks clients (the ACE Web Application Firewall, in this case) to authenticate itself as part of the SSL negotiation. If it does, you can specify the client public/private keypair to use from the If requested, use client public/private keypair menu. Specify how the ACE Web Application Firewall should verify certificates that the server presents: To accept any certificate the web service presents, leave the Require remote server certificate signed by this CA certificate option at its default value, none. This setting is the default. The ACE Web Application Firewall will accept any certificate the server presents. To accept any certificate that a specified Certificate Authority (CA) has signed, with the Require remote server certificate signed by this CA certificate option selected, choose one or more CA s listed in the menu. If the certificate does not appear in the menu, choose Upload and add the certificate to the ACE Web Application Firewall Manager s list of Trusted Certificate Authorities

100 Securing the Service Provider Connection Chapter 10 Securing Traffic with SSL/TLS Step 7 To accept a certificate identical to a particular certificate, click Require a certificate from the remote server that is identical to this certificate and choose the certificate from the menu. If the certificate does not appear in the menu, choose Upload and add the certificate to the ACE Web Application Firewall Manager s list of remote server certificates. During SSL connection setup, the ACE Web Application Firewall and backend server negotiate various parameters of the connection, including which SSL Cipher Suite to use for message encryption or authentication. By default, the ACE Web Application Firewall is not selective about which cipher suite it will accept. It will accept most encryption algorithms, including those using 64- or 56-bit keys. You can limit the cipher suites that the ACE Web Application Firewall will accept in establishing the connection to the backend server by choosing custom in the SSL Cipher Suite menu. In the text field that appears, enter the cipher suites to use for the server connection in standard OpenSSL Cipher string format, as described here: For example, to permit only algorithms that only keys that have a length of 128 bits or greater and not anonymous DH, enter the following in the text field: HIGH:MEDIUM:!ADH This is equivalent to specifying the following: DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA:EDH-RSA-DES-CBC3-SHA:EDH- DSS-DES-CBC3-SHA: DES-CBC3-SHA:DES-CBC3-MD5:DHE-RSA-AES128-SHA: DHE-DSS-AES128-SHA:AES128-SHA:DHE-DSS-RC4-SHA: KRB5-RC4-MD5:KRB5-RC4-SHA:RC4-SHA:RC4-MD5: RC2-CBC-MD5:RC4-MD5:KRB5-DES-CBC3-MD5: KRB5-DES-CBC3-SHA If the server is not capable of using one of the SSL Cipher Suites you configure, connection negotiation fails and the incident is recorded in the event log. Note Use care in typing the cipher suite in the field. The ACE Web Application Firewall Manager web console does not verify the value you enter. If you mistype or otherwise enter a meaningless value, the Firewall will be unable to connect to the server. Step 8 Click Save Changes to finish the server configuration. The SSL configuration is now complete. After deploying the policy, virtual services that rely on the configured server will now use SSL to communicate with the backend server

101 CHAPTER 11 Managing Resource Files This chapter describes how to work with resource files in a policy used by the ACE Web Application Firewall Manager. It covers these topics: Types of Resource Files, page Generating a CSR, page Uploading a Keypair Resource, page Uploading a Certificate Authority Resource, page Types of Resource Files An ACE Web Application Firewall policy is made up of objects and configuration settings that control how the ACE Web Application Firewall processes traffic. One type of policy object is a resource file. Resource files are self-contained artifacts that can be used throughout the policy, and include: Public/Private Keys Public/private keypairs are used to certify the identity of the ACE Web Application Firewall Trusted Certificate Authorities X.509 certificate files that identity providers of certificates that the ACE Web Application Firewall instance is prepared to trust Remote Server Certificates X.509 certificate files used to identify destination servers This section describes how to upload and manage resource files. There is usually more than one way to upload a particular type of resource file in the ACE Web Application Firewall Manager web console from the Resource Manager page in the console or from the page where a resource is applied. These instructions describe in general terms how to upload resources using the resource manager. Once the resource has been uploaded, it appears as a menu choice in applicable locations of the console. It is often preferable to load resources from a URL location rather than from a filesystem location. This allows you to take advantage of URL-based resource refreshing. Resource refreshing is a process by which the ACE Web Application Firewall Manager checks for updates to resources loaded in the policy by checking whether there are updates to the source. If so, the resource can be updated. For more information, see Reloading URL-Based Resources at Deployment section on page

102 Generating a CSR Chapter 11 Managing Resource Files Generating a CSR A public/private keypair associated with the ACE Web Application Firewall enables you to secure the communication channel between the ACE Web Application Firewall and consumer or between the ACE Web Application Firewall and backend service. The first step in acquiring a certificate is to create a certificate signing request, or CSR, for submission to a certificate authority. To generate certificate requests in the ACE Web Application Firewall Manager web console: Step 1 Step 2 Step 3 Step 4 Click the Public/Private Keypairs link in the Resources section of the navigation menu. Click the Generate CSR button at the bottom of the page. In the Generate Certificate Signing Request page, type in the Resource Name field the name that is to identify this resource in the policy. Type appropriate values into the following fields in the Subject Identification Information section: Table 11-1 CSR settings Field Common Name Address Company (O) Department (OU) City State ISO Country Code Description This field should contain the external hostname of the ACE Web Application Firewall. Note that for a clustered Firewall configuration this would be the common host name that consumers use to address the cluster. The address that is to receive the signed certificate in response to the CSR. The name of the organization or company with which the CN is associated. The name of an organizational unit or sub-group within the organization. The locality or city of the entity being certified. The state or province of the entity being certified. The two-letter International Standards Organization (ISO) code for the country of the entity being certified. Step 5 Step 6 From the Key Type menu, choose the algorithm to use when generating the certificate's signature, from these options: RSA The RSA public-key cryptosystem Secure Hash Algorithm. For more information, see the RSA-SHA1 Signature Suite page at the W3C web site. DSA The Digital Signature Algorithm Secure Hash Algorithm. For more information, see the Digital Signature Standard (DSS) page at the US National Institute of Standards and Technology (NIST) web site. Optionally, choose an item from the Key Size menu to specify the size of the key to use when generating the certificate's signature: 512 bits Use a 512-bit key to generate the signature bits Use a 1024-bit key to generate the signature. This is the default value bits Use a 2048-bit key to generate the signature

103 Chapter 11 Managing Resource Files Uploading a Keypair Resource Step 7 Step 8 Optionally, define additional attributes the certificate is to provide: a. Click the Add Attribute button. An Attribute OID field and a Value field appear in the Additional Attributes section. b. Type into the Attribute OID field the name of the additional attribute in OID format. c. Type into the Value field the value of the additional attribute. d. Repeat the preceding steps as necessary to add all of the attributes required. To remove an attribute, click the Remove button that appears at the end of its row in the list of custom attributes. When finished entering the information, click the Generate Request button. Using the information you supplied, the ACE Web Application Firewall Manager generates a Certificate Signing Request (CSR) and displays it on the Certificate Signing Request page. The generated request page appears similar to the following. Figure 11-1 Generated Request Form Step 9 Step 10 Copy the CSR data (the part between the -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- strings) into a text file or an message. Send the CSR data to your preferred CA for transformation into a signed X.509 certificate. Note When you are submitting a request, the CA may ask you to specify the type of certificate required. The ACE Web Application Firewall works with what are usually identified as Apache-style certificates. When the signed certificate arrives, install it on the ACE Web Application Firewall as described in the following section. Uploading a Keypair Resource A keypair resource is a file that stores a PKI public/private keypair. The ACE Web Application Firewall Manager uses keypair resource files to implement SSL connectivity between it and a browser attempting to access the web console. Service traffic can also be secured by the system public/private keypair. The Public/Private Keypairs page lists all keypair resources in the currently active subpolicy. Entries on this page represent keypair resources that reside on the system in encrypted form

104 Uploading a Certificate Authority Resource Chapter 11 Managing Resource Files When the ACE Web Application Firewall Manager compiles and deploys a policy that uses keypair resources, it transmits keypair data to the target Firewalls in a proprietary binary format. The keypair is never in clear-text form. You can upload a keypair to the ACE Web Application Firewall Manager by itself or as part of a certificate. A certificate resource is a file that the ACE Web Application Firewall Manager uses to store digital certificate data; optionally, the certificate resource can store the certificate's associated keypair data. Like the keypair resource, a certificate resource exists in the policy in encrypted form only. To upload a keypair resource to the policy in the ACE Web Application Firewall Manager: Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 While logged in to the Manager web console as an Administrator user or a Privileged user with the Routing role, set the active subpolicy to the one that is to use the keypair. Click the Public/Private Keypairs link in the navigation menu. Click the Add a New Public/Private Keypair button at the top of the page. (Alternatively, use the Upload Separate Certificate and Key Files if the certificate and key files are not in the same file.) The Upload Public/Private Keypair Resource page appears. You can also reach this page from the HTTP(S) port settings page. In the Resource Name field, type a unique name for the keypair resource. This name identifies the keypair in the ACE Web Application Firewall Manager's user interface. Identify the keypair to use from a filesystem location or from a network location by URL. Type the password for the keypair in the Password field. Note that the password is obscured in the field as you type. Click the Upload button. The ACE Web Application Firewall Manager uploads the keypair resource and displays it as a resource in the Public/Private Keypairs page. If the resource does not pass a basic validity test for example, if it does not provides a pair of valid PEM keys an error message appears in red text on the Upload Public/Private Keypair Resource page. When complete, you can use the keypair when configuring SSL connections in the policy. Uploading a Certificate Authority Resource Uploading the certificate of a Certificate Authority (CA) establishes a trust relationship for the ACE Web Application Firewall with that CA. The ACE Web Application Firewall can accept certificates based on the trust status of the CA that signed the certificate. By default, the policy does not include any pre-installed CA certificates; you will need to import the certificates of any CA to be trusted. You can upload a CA resource to the ACE Web Application Firewall Manager as a file or from a location specified by URL. You can also import the necessary information from an LDAP server. The Trusted Certificate Authorities page lists all Certificate Authorities available to the currently active subpolicy. These resources appear as named items in menus on pages that create or edit services requiring digital certificates. To upload a CA resource file to the ACE Web Application Firewall Manager web console: Step 1 As an Administrator user or a Privileged user with the Routing role in the console, set the active subpolicy to the one in which you want to use the keypair

105 Chapter 11 Managing Resource Files Uploading a Certificate Authority Resource Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 To make the keypair available to all subpolicies, add it to the Shared subpolicy. Click the Trusted Certificate Authorities link in the Resources section of the navigation menu. In the Trusted Certificate Authorities page, click the Add a New Certificate Authority Resource button, near the top of the page. The Upload Certificate Authority Resource page appears. Type a name for the certificate authority resource in the Resource Name field. This is simply a descriptive name for the resource used within the policy. Specify the certificate from either a file system location in the Local File field or from a network location, by typing the network address of the resource in the URL field. You can populate the Local File field automatically by clicking the Browse button, and navigating to the certificate file. Optionally, type a URL for the certificate revocation list in the CRL URL field. The ACE Web Application Firewall rejects connections that use certificates that appear in the certificate revocation list. Leave this field blank to not have the ACE Web Application Firewall check any certificate revocation list. If you configured a certificate revocation list, also specify how often the ACE Web Application Firewall should retrieve the list. When finished, click Upload to have the resource uploaded to the ACE Web Application Firewall Manager. After uploading the CA certificate, you can configure requirements based on this trust relationship. For instance, in the SSL connection settings for an HTTP server, you can require that server certificates be signed by the trusted CA

106 Uploading a Certificate Authority Resource Chapter 11 Managing Resource Files 11-92

107 CHAPTER 12 Deploying the Policy This chapter describes how to deploy a policy to the ACE Web Application Firewall. It covers these topics: Deployment Overview, page Deploying a Policy, page Selectively Rolling Back Policy Changes, page Reloading URL-Based Resources at Deployment, page Deploying an Approved Policy, page Deployment Overview As you make configuration changes in the console and save those changes, you re committing the changes to a working copy of the policy on the ACE Web Application Firewall Manager. The changes do not take effect at the Firewall until the working policy is deployed from the ACE Web Application Firewall Manager. Deploying a policy transmits the policy from the ACE Web Application Firewall Manager to any ACE Web Application Firewalls in the ACE Web Application Firewall Manager s administrative domain. Once deployed, the policy s rules and behaviors are applied by the ACE Web Application Firewall. In a development or evaluation setting, it is likely that you will want to deploy the policy frequently, for example, to test the effect of changes. In a production setting, however, deployment should only occur after the policy has been tested and verified. If necessary, you can enable approval-based deployment features to control the deployment process. You can deploy a policy selectively, for example, to a Firewall that has been recently added to the ACE Web Application Firewall Manager s domain. In general, however, all Firewall s in a particular domain should have the same policy. The deployment process occurs in several steps. 1. The ACE Web Application Firewall Manager performs a basic review of the policy, looking for configuration errors and other potential problems. 2. The ACE Web Application Firewall Manager compiles the policy, transforming it into the native format of the ACE Web Application Firewall for execution. 3. The ACE Web Application Firewall Manager adds a timestamp and ID code to the policy, and saves it in its archive

108 Deploying a Policy Chapter 12 Deploying the Policy 4. The ACE Web Application Firewall Manager transmits the policy to the ACE Web Application Firewall. 5. The ACE Web Application Firewall accepts the policy, stops services briefly, re-configures them to enforce the new policy, and restarts the services. We recommend as a final step in verifying the success of a deployment that you check the status of the I/O processes on the System Management page. If there are problems in the policy, it could prevent the http-server or reactor processes from restarting. You can ensure that all processes are running in the I/O Processes table in the Firewall Status settings. After completing the steps successfully, the ACE Web Application Firewall enforces the new policy. Who Can Deploy Policies In order to deploy a policy (or to approve one for deployment, if approval-based deployment is enabled) a user must have adequate permissions. Specifically, the user must: Be an Administrator or Privileged user with the Operations role Have access to the Shared subpolicy and the subpolicy to deploy. Additionally, if approval-based deployment is enabled, the policy or subpolicy itself must be approved for deployment. An Administrator user can always deploy and approve policies. Operations role users may deploy policies if they have access to the subpolicy involved in the deployment as well as the Shared subpolicy. Any subpolicy access is required to approve a policy for deployment. With approval-based deployment, users who do not have access to Shared instead request approval for policy changes to the administrator, who performs the actual deployment. Deploying a Policy Deploying a policy makes the changes in the current working policy take effect at the ACE Web Application Firewall. Only Administrator users and Privileged users with the Operations role can deploy policy changes in the web console. Optionally, an Administrator approval-based deployment can be enabled in the web console. When enabled, only certain users can approve or deploy a policy. The procedure for deploying the policy with approval-based deployment enabled is similar to these standard deployment instructions, with a few extra steps. For more information, see Approval-Based Deployment, page When approval-based deployment is not active, deploy a policy as follows: Step 1 Step 2 While logged in to the web console as an Administrator user or as a Privileged user with the Operations role, if your policy contains subpolicies, set the active subpolicy to the one from which you want to deploy. If there are subpolicies in a policy, deploying only moves the artifacts in the subpolicy that is active when deployment occurs. If you want to deploy changes from more than one subpolicy, you need to activate each subpolicy and deploy from the subpolicy one-by-one. Click the Deploy Policy button at the top of the page. If resource-reloading is enabled, the Step 1 of 4: URL Resource Refresh page appears. This page lets you ensure that the policy has the latest versions of any resource files loaded from URL locations, such as certificates. For details, see Reloading URL-Based Resources at Deployment section on page

109 Chapter 12 Deploying the Policy Deploying a Policy Step 3 If resource-reloading is not enabled, the ACE Web Application Firewall Manager displays the Step 1 of 3: Review Changes page. This page summarizes differences between the current policy and the policy to be deployed. For details, see Selectively Rolling Back Policy Changes section on page If the URL Resource Refresh page appears, click the Reload Resources Now button to upload changed URL-based resources. The ACE Web Application Firewall Manager attempts to retrieve new copies of all URL-based resources that the policy to deploy uses. It then displays the Review Changes page. Note Reloading URL-based resources cannot be undone. If you think you may need to revert to a previously saved version of a resource, be sure save a copy of the current version of the resource before you click the Reload Resources Now button. Step 4 Step 5 Step 6 Step 7 Step 8 Alternatively, click Continue To Next Step to skip reloading resources. Click the Continue to Next Step button to continue the deployment process. The Step 2 of 3: Basic Policy Review page lists conditions that would prevent successful deployment. Links on the page provide access to affected policy objects so you can make any changes needed to fix the problems. To discontinue deploying the new policy, click the Exit To Policy Manager button. Review and, if necessary, address any compilation warnings or errors displayed. The ACE Web Application Firewall Manager performs extensive compile-time policy checking to help ensure the integrity of the deployed policy. As you resolve each potential problem, the ACE Web Application Firewall Manager removes its associated warning from the Basic Policy Review page. To return to the Basic Policy Review page after resolving a problem, use your browser's Back button. Alternatively, click the Deploy button to restart the deployment process. When you have addressed the warnings on the Basic Policy Review page, click the Continue To Next Step button to continue the deployment process. The Compile and Deploy page appears. A Please wait message may appear for several seconds as the policy is compiled. Compilation transforms the policy to the native executable format of the ACE Web Application Firewall. When finished, the page displays information about the compiled policy, including its timestamp and the ID number assigned by the ACE Web Application Firewall Manager. Type a description for this policy version in the Policy Description field. This description helps to document the policy in the console. It appears in the Description column of the policy history. By default, this is an optional field. However, the administrator of the ACE Web Application Firewall Manager can make descriptions required from the Manager Settings page. Specify the appliances to which you want to transfer the compiled policy by checking the box next to its address or hostname. An out-of-date status for a Firewall indicates that the compiled policy is different from the currently deployed policy. Note It's possible to deploy a policy to some but not all of the appliances in a cluster. Do not do this, however, unless you are certain of the reasons for it. This is not a normal deployment strategy for the ACE Web Application Firewall. Under normal circumstances you should deploy the policy either to all or to none of the Firewalls controlled by the ACE Web Application Firewall Manager in a given cluster. Step 9 Click the Deploy To Selected Firewalls button to finish deploying the policy

110 Selectively Rolling Back Policy Changes Chapter 12 Deploying the Policy The ACE Web Application Firewall Manager transmits the policy to the selected appliances, where it will be enforced on network traffic. The Compile and Deploy screen reappears, displaying the results of the deployment: for each previously selected Firewall, the Status column displays Up to Date, the Deployed Policy Description column displays the description of the new policy, and the Deployed Policy Timestamp&ID column reflects the policy ID and timestamp of the new deployment. The new policy is now in effect at the ACE Web Application Firewall. Selectively Rolling Back Policy Changes At any time, you can selectively roll back or accept changes encapsulated by a policy version, as follows: Step 1 Step 2 Step 3 Step 4 As an Administrator user or as a Privileged user with the Operations role in the console, click the Policy Manager link in the navigation menu. In the policy history section at the bottom of the Policy Manager, click the Roll Back button next to the policy version to review. The Roll Back To description page appears. In place of the italicized replaceable description text is the text that appears in the Date Saved and Description columns of the specified policy's entry in the policy history. Click Accept addition or Accept deletion checkboxes as necessary to accept or reject individual changes to the policy. A checkmark in an Accept addition checkbox indicates approval of the action specified. Removing a checkmark indicates your rejection of the action its label specifies. Click Save Changes to confirm your changes. The Policy Manager page appears and the working policy reflects the choices you just confirmed. You can now request administrative approval of the changed policy or, if you have sufficient privileges, you can deploy it yourself. Reloading URL-Based Resources at Deployment The Firewall policy may include resource files that were loaded into the policy from a location specified by URL. In general, the ACE Web Application Firewall does not attempt to retrieve remote resources at runtime. Instead, it stores the resource in the policy. However, every time you deploy the policy, you can refresh the copy of the resource with the version located at the URL specified when the resource was originally loaded into the policy, as follows: Step 1 Click the URL Resource Refresh button in the Review section of the Policy Manager page. The URL Resource Refresh page appears.this page lists each network-based resource the working policy uses, along with the URL that provides the resource, the time of the last attempt at reloading the resource, and the result of that attempt

111 Chapter 12 Deploying the Policy Approval-Based Deployment Step 2 Click the Reload Resources Now button. Note This operation cannot be undone. If you think you may need to revert to a previously saved version of a resource, be sure to save the current version of the resource before you click the Reload Resources Now button. Step 3 The ACE Web Application Firewall Manager attempts to download a new copy of each resource in the list. As it proceeds, it updates the Last Reloaded and Result columns to reflect the status of each attempt. Click the Continue To Next Step button, at the bottom of the URL Resource Refresh page. The ACE Web Application Firewall Manager retrieves URL-specified resources. Approval-Based Deployment In approval-based (or two-stage) deployment, a policy developer first requests approval for changes made to the policy. The administrator reviews and either approves or rejects the changes. Once approved, the changes can be deployed by the administrator. When this feature is enabled, privileged users can still edit policies just as always, but the Deploy section of the Policy Manager is replaced by a Submit section, where users request administrative approval of changes to the working policy. If requesting approval from within a subpolicy, only the changes from within that subpolicy are represented by the change request. A user working in multiple subpolicies will need to request approval within each subpolicy. The procedures applicable to approval-based deployment are: Enabling Approval-Based Deployment Viewing Approval Status and Requests Requesting Approval of Policy Changes Approving or Rejecting Policy Changes Deploying an Approved Policy Enabling Approval-Based Deployment Approval-based deployment is disabled by default. To enable it, follow these steps: Step 1 Step 2 Step 3 Step 4 As the Administrator user in the ACE Web Application Firewall Manager web console, click the System Management link in the navigation menu. Click the link labelled Manager Settings, which is to the right of the ACE Web Application Firewall Manager heading. In the General settings area, find the Workflow configuration options, and enable the Use approval-based deployment option. Click the Save Changes button

112 Approval-Based Deployment Chapter 12 Deploying the Policy Step 5 Step 6 Step 7 The System Management page appears. Log out of the ACE Web Application Firewall Manager's web console. Verify that approval-based deployment is enabled by logging into the ACE Web Application Firewall Manager web console as a non-administrative user in the Operations role. Click the Policy Manager link in the navigation menu. If the configuration change succeeded, a Submit section appears in place of the Deploy section. Viewing Approval Status and Requests When approval-based deployment is enabled, the Manager Dashboard provides additional information concerning the status of subpolicy deployment, as discussed in this section. Approved Policy Status At the top of the Dashboard, the Approved Policy Status section lists proposed policy changes awaiting the approval of an administrative user. The Approved Policy Status section appears only when approval-based deployment is enabled. Only privileged users (those with the ability to edit or deploy policies) can view this section of the Dashboard. This section displays only subpolicies available to the user account logged into the ACE Web Application Firewall Manager. If the user has any subpolicy access, this section displays the status of all subpolicies simultaneously. Otherwise, it displays the status of the active subpolicy only; to view the approval status of another subpolicy, you must make that subpolicy the active subpolicy. For each subpolicy visible to the account logged into the ACE Web Application Firewall Manager, this section lists the following information: Date and time the subpolicy was last approved Whether the most-recently approved version was deployed Date and time of the request for approval of the new or changed subpolicy The username of the web console user who originated the request If you have policy-review privileges, a Review button appears next to each pending request. Approval Request Status for Active Subpolicy The Approval Request Status For section on the Dashboard lists outstanding requests for approval of changes to the active subpolicy. Only privileged users (those with the ability to edit or deploy policies) can view this section of the Dashboard. This section displays the status of the active subpolicy only; to view the status of another subpolicy, make that subpolicy the active subpolicy. This section lists the status of each request for approval as one of the following values: Approved A policy reviewer has authorized deployment of the subpolicy. A user in the Operations role who has any subpolicy access can transmit this policy to the ACE Web Application Firewall for enforcement

113 Chapter 12 Deploying the Policy Approval-Based Deployment Approval Requested A user has requested that a policy reviewer authorize the deployment of a new or changed subpolicy. Before approving the subpolicy, the reviewer inspects the differences between this policy or subpolicy and the one the ACE Web Application Firewall enforces currently.the reviewer can approve or deny each change individually to ensure that the policy ultimately deployed to the ACE Web Application Firewall performs as intended. Rejected A policy reviewer has denied authorization to deploy a new or changed subpolicy. After changing the unacceptable portions of the policy, you can request approval again. Requesting Approval of Policy Changes If approval-based deployment is enabled, new or changed subpolicies cannot be deployed until the change is approved by an administrator or privileged user with the operations role. To request approval of a new or changed subpolicy: Step 1 Step 2 Make the subpolicy with changes to be approved active in the console, and click the Request Approval button at the top of the page. If resource-reloading is enabled, the Step 1 of 4: URL Resource Refresh page appears. Before deploying a policy, you can use the Resource Refresh page to ensure that the policy has the latest versions of any remotely hosted resources, such as schemas or certificates obtained from URLs. For details, see Reloading URL-Based Resources at Deployment section on page If resource-reloading is not enabled, the ACE Web Application Firewall Manager displays the Step 1 of 3: Review Changes page. This page summarizes differences between the current policy and the policy to be deployed. For details on the Review Changes page, see Selectively Rolling Back Policy Changes section on page If the URL Resource Refresh page appears, click the Reload Resources Now button to load URL-based resources. The ACE Web Application Firewall Manager attempts to retrieve new copies of all URL-based resources that the policy to deploy uses. When finished, it displays the Review Changes page. Note Reloading of URL-based resources cannot be undone. If you think you may need to revert to a previously saved version of a resource, make sure you have archived a backup copy of the current version of the resource before you click the Reload Resources Now button. Step 3 Step 4 Step 5 Step 6 Click the Continue to Next Step button. The Step 2 of 3: Basic Policy Review page appears. This page shows warnings about possible problems the changed policy might introduce. Review the warnings. You may choose to resolve the issue that generated the warning or to overlook the warning for now. If you need to alter your policy to resolve a warning, click Exit to Policy Manager to exit the approval process and edit your policy. When finished, click the Continue to Next Step button. In the Step 3 of 3: Submit Request page, type a short description or comment in the Description field. The description is typically used to characterize the changes in the submission to an administrator or other developer. It is visible to any user that has policy-viewing permissions. Optionally, send notification of the request as follows: a. Click the Send notification of this approval request button

114 Approval-Based Deployment Chapter 12 Deploying the Policy Step 7 b. Type the addresses of recipients in the To address field. c. Type the sender's address in the From address field. Normally, this would be the address of the requestor. Click the Submit Request button. The approval request appears in the Dashboard page. For an administrator user or privileged user with the operations role, the request appears in the Approved Policy Status pane at the top of the Dashboard. For users who have access to the Shared subpolicy. the request appears in the Approval Request Status for Shared section. Approving or Rejecting Policy Changes Administrators or privileged users with the operations role can review and approve or reject policy changes. A change request needs to be approved before the changed policy can be deployed to the ACE Web Application Firewall. In the Manager Dashboard, the Approved Policy Status section displays the most recently proposed and the most recently approved changes for each subpolicy. Each row shows the subpolicy's last date of approval, deployment status, and most recent change awaiting approval. For a complete list of all approval requests, see the policy history at the bottom of the Policy Manager page. If you have policy deployment privileges, a Review button appears next to the most recent request that awaits approval. When you click the Review button, the ACE Web Application Firewall Manager treats all pending changes affecting that subpolicy as one subpolicy that you can approve or reject in total. To approve or reject changes selectively, see Selectively Rolling Back Policy Changes section on page To accept or reject all changes to the active subpolicy: Step 1 Step 2 As an Administrator or Privileged user with the Operations role in the console, in the Approved Policy Status section of the Dashboard, click the Review button at the far right of the row describing the policy to be approved or rejected. In the Review Approval Request page, approve or reject the policy as follows: To approve all changes, click the Approve Changes button. To reject all changes, click the Reject Changes button. To exit without making any changes, leaving the approval request still pending, click the Cancel Review button. The Dashboard page appears. The Approved Policy Status and Approval Request Status areas reflect the results of your choice. The policy-approval process allows an administrator to accept or reject a policy in its entirety. Following an approval, you can effect selective approval by using the roll back process in the Policy Manager. For more information, see Selectively Rolling Back Policy Changes, page

115 Chapter 12 Deploying the Policy Approval-Based Deployment Deploying an Approved Policy Once a policy approval request has been submitted and approved, the changes encapsulated in the request can be deployed by an Administrator user or Privileged user with the Operations role. If subpolicies exist in the policy, deploying only moves the artifacts in the subpolicy that is active (including Shared) when the deployment occurs. If you want to deploy changes from more than one subpolicy, you need to activate each subpolicy and deploy from the subpolicy one-by-one. To deploy the policy with approval-based deployment enabled, follow these steps: Step 1 Step 2 Step 3 Step 4 In the web console, click the Deploy Approved Policy button to compile the policy and transmit it to the ACE Web Application Firewall for enforcement. The Step 2 of 3: Basic Policy Review page lists the approval status. Although a similar review appears for policy submission, the Basic Policy Review page may appear a second time since the policy may have changed after submission. Review and respond to any warnings in the ACE Web Application Firewall Manager. Because the policy has already been approved, you cannot change it. If you are not willing to deploy the policy as it is, you must click the Exit to Policy Manager button to cancel the deployment. Subsequently, you can edit the policy in the Policy Manager and resubmit it for approval. If satisfied with the approved policy, click the Continue To Next Step button to continue the deployment process. The Compile and Deploy screen displays the message Please wait as it compiles the policy, transforming it to the native executable format of the ACE Web Application Firewall. When finished, it displays the message This policy is compiled and can now be deployed, along with controls that enable you to specify the ACE Web Application Firewall appliances that are to load and enforce this policy. Click the check box next to each Firewall appliance that is to receive this policy. Note It's possible to deploy a policy to some but not all Firewalls in a cluster. Do not do this unless you are certain of the reasons for it. Under normal circumstances you should deploy the policy to either all or none of the Firewalls in a cluster. Step 5 Click the Deploy To Selected Firewalls button to finish deploying the policy. The ACE Web Application Firewall Manager transmits the policy to the selected Firewalls, which accept the policy and reconfigure themselves to enforce it. The Compile and Deploy screen displays the results of the deployment. The Timestamp&ID column reflects the policy ID and timestamp of the new deployment. Your new policy is now in effect

116 Approval-Based Deployment Chapter 12 Deploying the Policy

117 CHAPTER 13 Managing the Policy This chapter describes how to manage an ACE Web Application Firewall policy. It covers these topics: About Policies, page Working with Subpolicies, page Copying Objects Between Subpolicies, page Exporting and Importing Policies with PPF Files, page Miscellaneous Policy Administration Tasks, page About Policies The policy contains the complete set of rules and behaviors that control how the ACE Web Application Firewall handles traffic. As the primary development environment for a policy, the ACE Web Application Firewall Manager web console provides many features for policy administration and maintenance. In particular, these features are available in the Policy Manager. While logged in to the console as a user with administrative privileges, you can view the Policy Manager page by clicking the Policy Manager link near the bottom of the Policy section of the navigation menu. The Policy Manager page is organized into these areas: Last Deployed refers to the version of the policy as last deployed. This is the version of the policy currently enforced at the ACE Web Application Firewall. Manager Policy contains controls applicable to the working version of the policy, that is, the one currently under development in the console. Among other tasks, you can save the current working version to the policy history list, without deploying the policy, and view change information. The policy history list shows past versions of the policy. When you deploy the policy, the policy version as deployed is automatically saved to the policy archive. Also, you can manually save the current working version of the policy to the history list at any time. When the ACE Web Application Firewall Manager is configured for approval-based deployment, the Approved or Deploy settings appear, depending on the role of the logged in user: The Approved pane lists those policies that are approved, and available to be deployed. The Deploy row of the working policy's section enables an administrator to begin the process of deploying the working policy. If approval-based deployment is enabled and you are not the administrator, this area is named Submit and you can use it to request administrative approval of unapproved policies

118 Working with Subpolicies Chapter 13 Managing the Policy As the single point for controlling the Firewall s rules and behaviors, a policy can grow to contain a large number of objects and service definitions. Subpolicies enable you to organize policy objects within the policy. Since access to subpolicies can be controlled in the web console, they can divide a policy into areas of concern corresponding to different teams that develop or administer the policy. This chapter covers these features, as well as other considerations for developing and maintaining the ACE Web Application Firewall policy. Working with Subpolicies A subpolicy allows you to organize objects and settings within a policy. A policy can have any number of subpolicies. Subpolicies facilitate team-based development, since they partition objects of concern to different development teams. By default, the Manager policy contains a predefined subpolicy named Shared. If no other subpolicy is ever added to the policy, the fact that the Shared subpolicy is the context of your policy work will be transparent to you. To use subpolicy features, you will need to define additional subpolicies. You can place objects in a particular subpolicy by making it active in the console, and then creating the object in the subpolicy. Once a policy object has been created in the subpolicy, it can only be modified when that subpolicy is active in the console. Objects can be moved between subpolicies. Using the PPF import/export process, you can selectively copy objects from one subpolicy to another. This process is useful for reorganizing objects among subpolicies, as well as migrating objects between environments that otherwise use different subpolicies. About the Shared Subpolicy The predefined Shared subpolicy has several unique properties for a subpolicy. The objects and resources it contains are available for use in other subpolicies. (The contents of other subpolicies are unavailable to other subpolicies, including to Shared.) Figure 13-1 Shared in relation to user-defined subpolicies The Shared subpolicy must be active for other subpolicies to be created or removed. In this sense, Shared is the parent of other subpolicies. Accordingly, to transfer subpolicy definitions between environment, you must export a PPF file from the Shared subpolicy and import to the target environment. This replicates the subpolicy definitions (but not the contents of those subpolicies) from the target to the source policies. Keep in mind, however, that Shared does not contain the subpolicies in any other sense. That is, the contents of other subpolicies are not part of Shared. Each subpolicy must be deployed or removed independently to change the policy

119 Chapter 13 Managing the Policy Working with Subpolicies The export process allows you to write a policy to a file for archiving or sharing. Policies are written to a Portable Policy Format (PPF) file. When exporting from Shared, only the objects in Shared are written to the file. When exporting from a user-defined subpolicy, parts of Shared may be included in the generated PPF file as well as the contents of the active subpolicy. (For more on exporting PPFs, see Exporting and Importing Policies with PPF Files section on page ) Since resources in Shared can be used across subpolicies, it will usually hold objects with broad applicability, such as security certificates and port definitions. A few types objects must be in Shared. These include: Content screening rules, both custom and built-in screening rules The Public authorization group of the Shared subpolicy. This is an internal authorization group to which public handlers are assigned. The default HTTP port (port 80) The web console prevents you from attempting to move these object. Otherwise, policy objects can be distributed among subpolicies in various ways. However, service definitions are not intended to be split between subpolicies, that is, you should not have a handler in the Shared subpolicy that routes to a service descriptor in another subpolicy. While you can use resources that are defined in Shared from other subpolicies, you cannot modify the Shared resources except from the Shared subpolicy. To change resources in Shared, like any subpolicy, you need to make it the active subpolicy in the web console. As mentioned, objects in other subpolicies can use the objects in Shared. Therefore, Shared is a good place to keep objects that may need to be used across subpolicies, such as HTTP(S) ports 80 and 443, certificate authorities, common back end HTTP servers, and so on. To ensure the stability of object dependencies from subpolicies to the Shared subpolicy, only the deployed version of Shared is visible in other subpolicies. To make Shared resources available to other subpolicies, or changes in Shared visible in other subpolicies, you must first deploy from Shared. Until deployed, the objects in Shared are unavailable in other subpolicies. Creating a Subpolicy To create a subpolicy: Step 1 Step 2 Step 3 Step 4 Step 5 As a user with Administrator privileges in the console, set the active subpolicy to Shared. Creating a new subpolicy requires Shared to be the active policy. If the navigation bar names a subpolicy other than Shared as the active subpolicy, use the Switch button to make Shared the active subpolicy. If the Switch button does not make the Shared subpolicy available to you, you do not have sufficient access privileges to perform this task. In the navigation menu, click the Subpolicies link. If the Subpolicies link does not appear in the navigation menu, you are not logged in as a user with administrator privileges. You must be an administrator to create subpolicies. Click the Create a New Subpolicy button on the Subpolicies page. In the New Subpolicy page, enter a unique name of the new subpolicy in the Subpolicy Name field. Click Save Changes

120 Working with Subpolicies Chapter 13 Managing the Policy The name of the new subpolicy appears on the Subpolicies page. You can switch to the subpolicy to start developing objects in it immediately. You may also need to enable access to the new subpolicy for web console users. In the account settings for a user, the web console administrator can set the user to have access to specific subpolicies or to any subpolicy. Users who are configured to have any subpolicy access automatically have access to new subpolicies as they are created. Users with access to select subpolicies will need to have their account changed to include the new subpolicy, if appropriate, from the User Administration page. Changing the Active Subpolicy After you create a subpolicy, users who want to start working on the subpolicy can use the Switch button at the top of the console to activate the subpolicy. The Switch button only appears in the console if more than one subpolicy (other than Shared) exists in the policy and the currently logged in user has access privileges to more than one subpolicy. When a user makes a particular subpolicy active, it remains active across logins for that user. That is, after logging out and then logging back in, the activated subpolicy will still be active in the console. Deploying from a Subpolicy To deploy the objects in a subpolicy, make the subpolicy active and then use the standard deployment procedure to complete the deployment. Note To deploy a subpolicy, the user needs to have access privileges to Shared as well as the subpolicy that is being deployed. Deploying from within a subpolicy propagates only the contents of that subpolicy to the Firewall, not the objects in any other subpolicy, including Shared. In general, only a single subpolicy can be deployed at a time, except when approval-based deployment is enabled. In this case, the administrator can deploy all at once those subpolicies that are approved for deployment. Deleting a Subpolicy You can delete a subpolicy by clicking the remove link next to it on the Subpolicies page. To delete a subpolicy, the subpolicy must be empty. It cannot contain virtual services, authenticators, or other policy objects. The easiest way to remove objects from a subpolicy is to switch to the subpolicy and reset the policy from there. That is, after making the subpolicy you want to remove the active policy, click the Policy Manager link. From the Manager Policy area of the Policy Manager, click the Reset Policy button and complete the reset policy process. When finished, make the Shared subpolicy active again and try removing the subpolicy again from the Subpolicies page. When you confirm deletion, the subpolicy is immediately removed from the console

121 Chapter 13 Managing the Policy Copying Objects Between Subpolicies Copying Objects Between Subpolicies The ACE Web Application Firewall Manager enables console users to copy policy objects between different subpolicies. While not limited to these scenarios, this feature is primarily intended to support the ability to reorganize objects among subpolicies and migrate objects between policy environments that have different subpolicies You can copy objects between subpolicies using the Portable Policy Format (PPF) import/export mechanism. The PPF import process merges the objects from a source PPF into the target subpolicy in the Manager, that is, in general, objects that existed in the target subpolicy that were not in the source PPF are retained alongside the imported objects. The PFF import/export process can run in several modes. In one mode, the Manager imports a subpolicy from a PPF file only if the identities of the source and target subpolicies match. In another mode, the Manager imports the subpolicy even if the source and target subpolicies differ, so that objects can be moved or migrated between subpolicies. This scenario is shown in Figure Figure 13-2 Import from one subpolicy to another Policy PPF File Shared Shared mysubpol1 (active) import mysubpol2 mysubpol In the import example shown in Figure 13-2, the source PPF would have been generated from the Shared subpolicy. Its contents are imported into the subpolicy mysubpol3. Notice that the target subpolicy does not have to be active in the Manager web console for it to be the import target. An additional import option applies when the source PPF contains a subpolicy other than Shared. When exporting from a non-shared subpolicy, the PPF file may contain objects of Shared as well as objects from the user-defined subpolicy. When importing the PPF, you are given the option of also including the contents of Shared in the merge. If selected, both source subpolicies are merged into the target subpolicy, as shown in Figure

122 Copying Objects Between Subpolicies Chapter 13 Managing the Policy Figure 13-3 Import from Shared and subpolicy to another subpolicy Policy PPF File Shared Shared mysubpol1 mysubpol2 import mysubpol2 (active) mysubpol The following sections describe the steps for moving objects between subpolicies to reorganize a policy and to migrate policy objects. Reorganizing the Policy In many cases, a simple policy can sensibly occupy a single subpolicy. However, as the policy grows, the need usually arises for a better organizational model for the policy, one based upon subpolicies. The following steps provide general steps for reorganizing policy contents by subpolicies, in this case, by moving objects from Shared into a user-defined subpolicy on the same Manager. However, the steps apply as well to simply moving misplaced objects between subpolicies. For detailed steps, along with background information on exporting and importing PPF files, see Exporting and Importing Policies with PPF Files section on page The general steps for moving subpolicy contents: Step 1 Step 2 Step 3 Step 4 Switch the active subpolicy in the Manager web console to the one from which you want to move objects. To reorganize objects from Shared into subpolicies, first make Shared the active subpolicy. In the Policy Manager page, export the policy to a PPF file by clicking the Export button next to the policy version you want to export. To export a working policy that has not been deployed yet, you will first need to save the policy to the policy history. Choose the subpolicy that you want to move the objects to, creating a new subpolicy if needed. This destination can be either on the same Manager or a different Manager instance. Log in to the appropriate Manager and switch to the destination subpolicy. In the Policy Manager, click the Import Saved Policy button. Note For details importing and exporting policies, see Exporting and Importing Policies with PPF Files section on page Step 5 In the Upload Policy File page, browse to the PPF file you generated from the source subpolicy

123 Chapter 13 Managing the Policy Copying Objects Between Subpolicies Step 6 Choose the button labelled Import the contents of the subpolicy in the PPF into [target subpolicy], the option for importing objects even if the identities of the source and target subpolicies differ. If there is more than one subpolicy in the target environment, choose the target subpolicy from the drop-down menu. This would be the new subpolicy to which objects from Shared will be moved. Figure 13-4 Selecting the import target Note Only the subpolicies to which the current console user has access privileges appear in the menu. Step 7 Step 8 Step 9 Step 10 Step 11 Choose whether the contents of Shared, if present in the source file, should be included or excluded from the import. If reorganizing from Shared to user-defined subpolicies, be sure to enable the option labeled: Include the contents of the PPF's Shared subpolicy in the import into [target subpolicy]. If the PPF was generated from Shared and you choose the first option, excluding the contents of Shared, nothing will be imported. Click Upload Policy File. In the Import Options page, choose the handler groups to be imported into the target subpolicy. Choose from the service definitions to be moved to the target subpolicy from those originally in the Shared subpolicy. For a reorganization, it is likely that a subset of the available handler groups would be chosen for import, with the handler groups not imported at this time imported into other subpolicies later. When finished importing the PPF, manually remove the objects from the source subpolicy, Shared in this case. This complete the move of the objects from the source to the target subpolicy. Deploy from both Shared and then the target subpolicy to have the change reflected in the policy at the Firewall, and to ensure the policy compiles and deploys without error. Notice that if importing from a PPF that contains a user-defined subpolicy and Shared, you can choose to import Shared or only those objects in the user-defined subpolicy. Migrating Policy Objects Thorough testing is normally required for a policy before it is placed in a production environment with live traffic. For this reason, policies are usually developed and tested in a test environment before promotion to production. The procedure described in Reorganizing the Policy, page can be used for policy migration as well as policy reorganization. Policy migration is the process by which development artifacts graduate from one environment to another in their life cycle, for example, from development environment to QA or from QA environment to production. After a target environment (production, for instance) is seeded with a policy imported from the source environment (such as development), the export/import process can be repeated to propagate subsequent changes to the policy

124 Copying Objects Between Subpolicies Chapter 13 Managing the Policy The ability to update policy objects only applies to objects that have been created in the target policy through the export/import process. If an object is manually created in the target policy, the ACE Web Application Firewall Manager cannot associate it with a corresponding object in the source (testing or development) policy, even if the objects have the same names in their respective policies. When you import objects with the PPF mechanism, the association between objects in the source and target policies are retained. If the original objects are kept in the source subpolicy, changes to it can be applied later to the target policy. Thus, the object copy procedure can be used as a basis for policy migration. When needed, changes to the source objects can be applied to the target environment by the export/import PPF procedure. Since the source and target subpolicies can be different, subpolicies can be organized sensibly for each environment, without having to duplicate the complete production policy in a given development environment, for instance. Figure 13-5 illustrates an example scenario. Figure 13-5 Migrating policies with PPF export/import Development Environment Production Environment CustomerDevCluster source policy CustomerServices.ppf Shared Gateway Cluster PartnerDevCluster source policy PartnerServices.ppf Shared target policy Shared CustomerServicesSubpolicy PartnerServicesSubpolicy EmployeeDevCluster EmployeeServicesSubpolicy source policy EmployeeServices.ppf Shared

125 Chapter 13 Managing the Policy Exporting and Importing Policies with PPF Files While the subpolicies may be different, for object updates to work through this mechanism, the source and target objects must have the same identity. In other words, the target objects must have been created by exporting from the source and importing into the target environment. Two objects that are duplicates, including by name, but have been created separately are not subject to this update capability. The steps for performing PPF export and import for the purposes of policy migration are similar to those described in section Reorganizing the Policy section on page The primary difference is that the original objects in the source subpolicy must be retained. If they are, subsequent changes to them can be propagated to the production environment by repeating the procedure. Also note that this procedure can be used across environments, that is, by copying and updating objects from one ACE Web Application Firewall Manager to another or across Firewall clusters. Certain settings may need to be changed when migrating the policy between network environments. For example, in the development environment, the ACE XML appliances may not be able to access the actual backend services being virtualized. Certain types of testing, such as performance testing, may adversely impact production-level infrastructure. Before promotion, therefore, you may need to modify the policy to change backend service settings, along with other settings. The policy settings that may need to be modified when the policy is migrated include: Private keys, since public/private keypairs are generally host-specific. The published hostname clients use to address virtual services at the Firewall. (This hostname is visible in generated WSDL files, which may need to be regenerated and published from the new environment.) The development and production networks may differ in availability of certain types of services, such as LDAP servers, backend service providers, and so on. Connection settings for these types of resources may need to be modified at migration time. Exporting and Importing Policies with PPF Files From the Policy Manager page you can export the deployed or approved policy, or any policy from the Policy History. When you export a policy, the ACE Web Application Firewall Manager converts all the policy objects to an external format and writes the data to a file. The file uses a proprietary format called Portable Policy Format, identified by the extension.ppf. You can use the file to perform a transfer by loading it into another ACE Web Application Firewall Manager, and then deploying the policy to the ACE Web Application Firewalls in the target Manager s control. You can also use PPF files to make copies of policies for backup purposes. The export/import process lets you move policy components selectively; that is, you do not need to export the entire policy. When exporting, you are offered the option of selecting the handler groups to export. Along with the handlers in the handler groups you select, the objects they reference are exported, such as certificates, server objects, and so on. When exporting a specific subpolicy, if the source subpolicy is one other than the Shared subpolicy, elements of Shared may also be included in the export. At import time, you are given the option of importing the contents from the source and either including or excluding the contents of Shared

126 Exporting and Importing Policies with PPF Files Chapter 13 Managing the Policy Exporting the Policy to a PPF To export the policy to a file: Step 1 Step 2 Step 3 As an Administrator or Privileged user with the Operations role, make the subpolicy that you want to export active. Click the Policy Manager link in the navigation menu. In the Policy Manager, click the Export button next to the policy to archive. You can export the currently deployed version of the policy or one saved to the policy history. Note To archive the current working policy, you must first save it to the policy history by clicking the Save To History button. You can then archive the saved policy version. The Export Policy page appears. Figure 13-6 Export Policy Step 4 Step 5 Step 6 In the Filename field, type a name for the generated policy archive file. If you are exporting from a policy version with a description, the Manager generates a default name based on the description. You do not need to add the.ppf extension to the name. The extension is appended to the filename automatically. If the policy contains public/private keypair resources, a checkbox appears that enables you to include the resource in the exported file. Its default setting is to be disabled, since such resources are extremely sensitive. If you do not include it, however, exported objects that depend on the resource will not work properly upon import until you manually modify their resource references. If you want to include the resources in the file, select the option labelled Include Public/Private Keypair Resources. Optionally, uncheck handler groups that are not to be included in the archive. Rather than exporting all service definitions, you can export the selected handler groups. Handler groups that are not included in the export are not created when the policy is imported. The Check All and Uncheck All links provide an easy way to include or exclude all handler groups

127 Chapter 13 Managing the Policy Exporting and Importing Policies with PPF Files Step 7 Step 8 Click Export Policy. The ACE Web Application Firewall Manager creates the archive file using the name you specified. In the dialog box, choose a location to save the file and click OK to save the archive file. The policy is now saved as a.ppf file. It can now be imported into other Manager environments or into another subpolicy. Importing a Policy Importing a Portable Policy Format (.ppf) file into the ACE Web Application Firewall Manager restores it in the Manager web console, where it can be modified or deployed to the ACE Web Application Firewall. As with policy export, the parts of a policy can be imported selectively. When you import a portion of a policy, it can be merged with the existing policy, so that its changes are blended in with the existing policy (as opposed to completely replacing the existing settings). If there are objects in the PPF that are the same as objects in the working policy (including by object name), duplicate objects will be created in the working policy unless the object in the PPF was generated by an export from the working policy. For more information, see Migrating Policy Objects section on page In most cases, the policy import process will be used with an empty target policy or to introduce new objects to a policy. To import a.ppf file from your local filesystem, follow these steps: Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Click the Policy Manager link in the navigation menu. Click the Import Saved Policy button in the working policy section of the Policy Manager. The Step 1 of 3: Upload Policy File page appears. Specify the.ppf file to import by either typing the path to the file in the Policy File field or browsing to the file in the file chooser dialog. You can set Do not show detailed content of subpolicies. It reduces the level of detail normally shown on the following import policy pages. If this option is not selected, the next page displays the list of subpolicies for importing. If selected, the list of handler groups for the subpolicy will not appear, and all handler groups from chosen subpolicies will be imported. Also, with this option selected, the list of changes introduced by the import procedure will be collapsed. To view detailed information, click the expand control for the specific subpolicy. Click the Upload Policy File button. The Step 2 of 3: Import Options page appears. Depending on how it was generated, a PPF can include the contents of several subpolicies. In the Import Mode settings, choose how you want subpolicies to be handled in the import. Options are: Import the contents of the selected subpolicies in the PPF into the subpolicies with the same name This option allows you to import the contents of several selected subpolicies in the PPF into the target subpolicies using one operation. For each subpolicy from the PPF, the import strategy is the following: If a subpolicy with the same name exists in the current policy and you have access to it, the content of the subpolicy in the PPF will be imported into the subpolicy with the same name from the current policy

128 Miscellaneous Policy Administration Tasks Chapter 13 Managing the Policy If there is no subpolicy with the same name in the current policy, a new subpolicy with the same identity will be created and the content of the subpolicy in the PPF will be imported into the created subpolicy. Note To create a new subpolicy, you need to be logged in as an administrator. Step 7 If the source and target subpolicies have different names and you do not have administrator privileges to create a new subpolicy with the same identity, nothing is imported. Import the contents of the selected subpolicies in the PPF into [subpolicy name] Moves the objects from the selected subpolicies in the PPF into the target subpolicy regardless of the identities of the source and target subpolicies. With this option selected, objects can be moved between different subpolicies. If there is more than one subpolicy in the target environment to which you have access privileges, they appear in the drop-down menu. Choose the target subpolicy from the menu. Optionally, uncheck objects that are not to be imported. The checkboxes on the Import Options page enable you to select objects according to handler group or object type. Note If the target policy contains custom content screening rules and you include content screening rules in the import, the custom rules are overwritten by the imported policy. In effect, custom content screening rules will be deleted if a policy is imported that does not include those rules. To ensure custom rules are not overwritten, remove the check box selection for custom screening rules. Step 8 Step 9 Step 10 Unless you are sure that you do not need an object from the policy, leave its box checked. The default set of options imports all objects. Click the Import Policy button. The Merge with Working Policy page uses the Policy Comparison display to show changes that importing the policy would introduce. Optionally, reject individual changes to policy objects. Removing the checkmark from the box that appears next to a policy object indicates that the ACE Web Application Firewall Manager is not to make the change the checkbox represents. If you are not sure whether to accept or reject a change, use the default settings. Click the Save Changes button. The Recent Saved Policy Versions section of the Policy Manager shows the newly imported policy. The new objects and other changes that importing the policy has introduced now appear in the ACE Web Application Firewall Manager web console. Miscellaneous Policy Administration Tasks This section lists other administration tasks applicable to policy management, including saving a policy within the policy manager, performing policy comparisons, and so on

129 Chapter 13 Managing the Policy Miscellaneous Policy Administration Tasks Saving a Policy to the Archive History The Policy Manager allows you to restore, view, or compare past versions of the policy. When a policy is deployed, the policy archive is populated automatically with the policy version deployed to the Firewall. The current working policy can also be saved manually. This is useful, for example, for preserving a save point for a policy in development. To save the current working policy to the policy history manually, follow these steps: Step 1 Step 2 Step 3 Step 4 Step 5 Log in to the web console as the Administrator user or Privileged user with the Operations role. Set the active subpolicy to the Shared subpolicy. In the navigation bar at the top of the Dashboard page, Shared appears to the left of the Switch button. Click the Policy Manager link in the Policy Administration section of the navigation menu. The ACE Web Application Firewall Manager displays the Policy Manager page. Type an informative description of the working policy into the Version Description field. It is recommended that you make the description as informative as possible. It may be the only information available to distinguish this policy from potentially many others. Click the Save to History button. The Recent Saved Policy Versions and Policy History logs display the archived policy with a unique identifier, timestamp, and description you provided. Using the controls that appear next to the policy entry, you can now specify other operations on the policy, such as: viewing the archived policy in the console restoring the policy by rolling back the current working policy to the archived one exporting it, to save a copy of it to your local disk as a.ppf file Restoring a Policy Sometimes you may make changes to a working policy that have unexpected effects. You may find that you have accidentally disabled services, or removed settings that would be a lot of work to restore. One of the most common uses of archived policies is to protect you against such problems by saving that state of a policy that is known to work. You can recover the earlier working state of the ACE Web Application Firewall by loading and deploying an archived policy, a process known as restoring or rolling back a policy. Caution When you restore an archived policy, all of its settings replace all of the settings currently in effect. This means that, for example, if the current policy exposes services that are not defined in the restored policy, or if the restored policy lacks some authenticators that are defined in the one it replaces, some consumers may lose contact with some services. Make sure you know which service descriptors, routes, authenticators, and other policy objects are likely to change before you restore a policy, and be prepared to spend some time inspecting the resulting configuration and logs in order to ensure that all needed service connections are restored properly

130 Miscellaneous Policy Administration Tasks Chapter 13 Managing the Policy To restore a policy: Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 As an Administrator or a Privileged user with the Operations role in the console, set the active subpolicy to the Shared subpolicy. Click the Policy Manager link in the Policy Administration section of the navigation menu. In the Policy Manager page, find the policy to restore. The ACE Web Application Firewall Manager archives policies in the Recent Saved Policy Versions history, at the bottom of the Policy Manager page. To view older archives, click the View Full History link in the policy history banner. To restore a policy that has been removed from the ACE Web Application Firewall instance, you must first upload the policy archive file from your offline storage using the Import Saved Policy button in the Import pane of the working policy section. After uploading, the policy appears in the policy archive lists. If the policy was archived on a different Firewall instance then you may need to migrate it before restoring. Click the Import Policy button to load the policy into the ACE Web Application Firewall Manager web console for compilation and deployment. The settings and objects defined by the archived policy replace those currently defined in the ACE Web Application Firewall Manager. Click the Deploy button to begin the usual deployment process. The ACE Web Application Firewall Manager compiles and deploys the archived policy, making it the currently active policy in the ACE Web Application Firewall instance. Comparing Policy Versions The Policy Comparisons page (Figure 13-7) shows differences between two policy versions. It appears automatically at various points in policy development, such as when you deploy the policy. You can also compare two versions of a policy manually from the Policy Manager. In the Policy Manager, you can compare any two previous versions of a policy from the policy history list. A version of the policy is saved to the list at each deployment and when saved directly using the Save To History button. Figure 13-7 Compare Policies Page