Table Of Contents

AppScreen Configuration

Overview

Testing the Default AppScreen Configuration

Preprocessing Content Transformation

AppScreen Class

AppScreen Policies

Policy Rule Reference

Policy Disposition

Forward Disposition

Redirect Disposition

Ignore Disposition

Policy Actions

AppScreen Rules

Rule Components

Rule Operators

Rule Attributes

Rule Values

Using Multiple Attributes and Values

Regular Expression Matching

Content

Regular Expression Patterns

Exec Environment

Predefined Rules

Scanning POST Data and File Uploads

Buffer Limit

Content Types

AppScreen Logging

SNMP Notification

Receiving and Processing SNMP Traps

MIB

AppScreen Reports

AppScreen Configuration

---

This chapter describes how to configure the AppScreen feature. The following topics are covered:

•Overview

•AppScreen Class

•AppScreen Policies

•AppScreen Rules

•AppScreen Logging

•SNMP Notification

Overview

The AppScreen feature enables the application appliance to provide web application security and intrusion protection. AppScreen is highly configurable, and the following types of request filtering are pre-configured:

•binary blocking

•cross-site script blocking

•directory traversal blocking

•SQL injection blocking

•File upload blocking

AppScreen can scan all HTTP requests, and prevent unwanted requests from going to the origin server. AppScreen supports both:

•Positive (whitelist) screening, where the administrator describes content to allow.

•Negative (blacklist) screening, where the administrator describes content to deny.

AppScreen supports only request content screening. That is, it can scan all of the content sent from the end user's browser (or other front-end system) to the origin server, through the AppScreen proxy in between. AppScreen does not currently support response content screening; that is, scanning content that is returned from the origin server and/or AppScreen itself.

AppScreen is configured through two constructs:

•AppScreen Rules describe the matching of web transaction content with values provided in the rule (for example, looking for the text "<script" in a query parameter).

An AppScreen Rule determines whether the current request matches the criteria specified in the rule. If it does, then an AppScreen Policy that uses the rule is applied, otherwise the policy is skipped. AppScreen Rules are specified in two XML configuration files: appscreen-rules-standard.xml and appscreen-rules-custom.xml.

•AppScreen Policies determine which rules (if any) will be tested for the current request, and which actions (if any) will be taken if the request matches a rule.

AppScreen policies are specified in the fgn.conf file, at both the global level and within a type of class called an AppScreen Class. Like Application Classes, such classes allow requests to be segmented based on their attributes such as URL, header values, cookie values, etc.

AppScreen Policies allow the evaluation (or invocation) of AppScreen Rules to be decoupled from the definition of the rules.

The AppScreen feature is disabled by default. It is controlled by the AppScreen global keyword in the fgn.conf file. To turn it on, specify:

AppScreen On

If AppScreen is Off, all screening is disabled and all requests are passed through.

Testing the Default AppScreen Configuration

The factory default AppScreen configuration specifies Pass as the disposition for all of the pre-defined policies (see Table 6-2). This allows you to view the results of AppScreen content inspection without disrupting your web site or application traffic. Follow these steps to enable AppScreen and test the default configuration:

1. Install AppScreen and enable it using the configuration keyword AppScreen On, as described above.

2. Pass traffic through AppScreen for several hours or a day to get a representative sample of requests. Because all of the dispositions are set to Pass, AppScreen will not block or otherwise change the flow of the traffic.

3. Examine the AppScreen reports. If necessary, tune the AppScreen configuration for your environment. For example, you may have a particular web page such as a content management editor that should allow HTML <script> tags. In such a case, you can remove that restriction by setting the disposition to Ignore for that particular page or section of the application.

4. Now you can set the desired disposition for each policy, either keeping it as Pass or setting it to Deny, Redirect, Forward, Ignore, and so on. For more information on policy dispositions, see the "Policy Disposition" section.

Preprocessing Content Transformation

Before AppScreen examines the request content, the application appliance performs the following transformations:

•It transforms URL encoded characters (in hexadecimal) to their corresponding characters. For example, "%41" would be transformed to the character "A". The one exception is that the sequence %00 is left as-is and is not transformed to a null byte (character code zero).

•It transforms the + (plus) character to the space character.

These transformations are applied to the following request elements:

•URL

•Parameter names and values

•Cookie names and values

•Header names and values

•Query string and URL with query string (but be cautious about using these; see the "Regular Expression Matching" section)

•File names of uploaded files

•Content types of uploaded files

Additionally, for the POST content that AppScreen examines, the application appliance transforms any null bytes to the sequence "%00" so these can be searched for.

These transformations are transient; they are done only internally for AppScreen to examine the normalized content. If the request is allowed through, AppScreen sends through the original request, without any transformation.

AppScreen Class

AppScreen classes are similar to Application Classes, in that they allow requests to be segmented based on their attributes such as URL, header values, cookie values, etc. AppScreen Classes define a group of URLs for which specific AppScreen processing is desired.

AppScreen Classes are defined in the fgn.conf file, just like Application Classes. Here is an example of some classes defined:

# AppScreen classes

<AppScreenClass AllowHtmlTagsInForumPosts>

	Url "/myapp/forum/addComment\.jsp"

	AppScreenPolicy htmlTagStart | Ignore

	AppScreenPolicy invalidHtmlTagForForumPost | Deny 403

</AppScreenClass>

<AppScreenClass AllowTechSuppFileUploads>

	Url "/techsupport/uploadFile\.cgi"

	AppScreenPolicy prohibitedFileUpload | Ignore

</AppScreenClass>

AppScreen Class definitions can include a number of keywords (that also can be used at the global level in the fgn.conf file). The AppScreen-specific keywords are listed in Table 6-1.

Table 6-1 AppScreen Configuration Keywords 

Keyword	Description
AppScreen	Enables or disables the AppScreen feature at the global or AppScreen Class level. Valid values include On and Off (default).
AppScreenAlertSeverity	Configures the alert severity threshold. When an AppScreen Policy is matched, if the severity level of the policy is less than or equal to AppScreenAlertSeverity, then an SNMP alert is triggered as described in the "SNMP Notification" section. The default is 0. Valid values include the integers from 0 through 5.
AppScreenDefaultSeverity	Configures the default AppScreen Policy severity level. The default is 3. Valid values include the integers from 1 through 5. For more information about severity level, see the Severity keyword in Table 6-3.
AppScreenSnmpTrap	Enables or disables the AppScreen SNMP trap feature at the global or AppScreen Class level. If set to On, then an SNMP trap is sent if a policy is matched and the severity level of the policy is less than or equal to AppScreenAlertSeverity. Valid values include On and Off (default). If you set this to On, you must also define a location to send traps to with AppScreenSnmpTrapSink. For more information about SNMP and AppScreen, see the "SNMP Notification" section.
AppScreenSnmpCommunity	Defines the SNMP community string to be used when sending SNMP traps. The default is "public". For more information about SNMP and AppScreen, see the "SNMP Notification" section.
AppScreenSnmpTrapSink	Defines the location of an SNMP trap sink (that is, an SNMP management station). Specify a host name or IP address, optionally followed by a colon and the port number. If you don't specify the port number, the standard SNMP trap port of 162 is used. This keyword can be specified multiple times, to have the traps sent to multiple destinations. There is no default for this keyword, and it must be defined if AppScreenSnmpTrap is On, otherwise SNMP traps won't be sent. For more information about SNMP and AppScreen, see the "SNMP Notification" section.
PostContentBufferLimit	Sets the maximum amount of POST data that can be buffered by AppScreen, in kilobytes (KB). Valid values range from 0 to 1000, with a default of 40 KB. For more information about how this value is used, see the "Scanning POST Data and File Uploads" section.

AppScreen Policies

An AppScreen Policy definition in the fgn.conf file uses this syntax:

AppScreenPolicy rulename | disposition | [action [ | action ...]]

For example:

AppScreenPolicy checkBinary | Deny 403 | Severity 3

This definition could appear at the global level, or within an AppScreen Class.

AppScreen Policies have the following elements:

•Policy Rule Reference. The policy begins with the name of the rule that is evaluated. If the rule evaluates to true for this request, then this policy is applied. If the rule evaluates to false, this policy is skipped.

•Policy Disposition. Determines the disposition of the request (for example, will it be blocked or allowed). There must be exactly one disposition for each policy.

•Policy Actions. Determines what action(s) to take when the rule is matched. Zero or more actions can be specified.

The policy elements are described in detail in the following subsections.

The sequence of the policies is important. AppScreen processes policies in order, so earlier policies take precedence over later policies. However, a global policy can be overridden by an AppScreenClass policy that matches the same rule, and in that case, the AppScreenClass policy takes precedence even if it is later in the configuration file.

AppScreen checks each policy for a match against the current request:

•If there is no match, AppScreen continues to the next policy.

•If there is a match, the behavior depends upon the disposition defined for the policy. In most cases, AppScreen makes an allow/deny decision based on the first matching policy. This is described in the "Policy Disposition" section.

Policy Rule Reference

The Rule reference is simply the name of the rule that will be evaluated for this policy. If the rule evaluates to true for this request, then this policy is applied. If the rule evaluates to false, this policy is skipped.

Only one rule can be named. If multiple rules need to be evaluated then it is possible to define a rule that evaluates other rules. This is described in the "AppScreen Rules" section.

Policy Disposition

Disposition is the end result of this policy's rule being matched. Each policy must have exactly one disposition. Disposition keywords are listed in Table 6-2.

Table 6-2 Policy Disposition Keywords

Disposition Keyword	Description
Deny errcode	Blocks the request and returns the specified HTTP error code.
Allow	Allows the request. This disposition immediately allows the request to go through; the remaining AppScreen policies (if any) are not evaluated.
Pass	This is a "no-op" disposition. AppScreen simply continues on to the next policy in the list of policies. This is useful to simply tag a request as having matched a given rule. This information is used by the ruleMatch operator (described in Table 6-4).
Forward url	Forward to the specified URL. The URL must be absolute (e.g., http://...). For details, see "Forward Disposition" below.
Redirect url	Redirect to the specified URL. The URL must be absolute (e.g., http://...). For details, see "Redirect Disposition" below.
Ignore	This is a special disposition that means "don't bother to evaluate this rule." For details, see "Ignore Disposition" below.

Forward Disposition

The Forward disposition forwards the current request to the specified URL. This gives the origin server a chance to handle this client request and perform operations such as logging out the client or resource cleanup.

In order to use this feature, simply specify the URL to forward to. All the request headers from the client are sent to the origin server with the exception of the Content-length and Location headers. The Host header is appropriately fixed up.

The forwarding URL can be constructed using the parameter expander functions (see Table 5-4), for example:

http://myserver/cgi-bin/test-cgi?lang=$http_query_param(hl)

Where h1 is a query parameter that was received from the request.

Redirect Disposition

The Redirect disposition sends an HTTP redirect instruction (HTTP 302 response status code) to the client (web browser or other application). This is useful to display a customized error page instead of a generic error page, as may be displayed by the browser when receiving a Deny 500 error code, for example.

Using the Redirect disposition is as simple as specifying the URL to be displayed. However, there is one issue to contend with: special care must be taken to avoid introducing "looping" redirects. For example, consider the following sequence of events:

1. You have a policy called myPolicy that says:

Redirect http://www.mycompany.com/error.asp

2. A request comes in that matches myPolicy.

3. AppScreen sends a redirect to error.asp.

4. The request for error.asp comes to AppScreen.

5. For the sake of illustration, let's say that there is something about the request for error.asp itself (the URL, a header field, or something), that causes this request to also match myPolicy.

6. Now AppScreen will send another redirect to error.asp, and now the browser and AppScreen are caught in a loop. Each request for error.asp results in a redirect to error.asp, and so on.

This looping is not a security risk, however it is an unneeded use of AppScreen server resources, and it may be annoying to the user until they click the browser Stop button or close their browser window.

To avoid this looping problem, AppScreen tries to detect and prevent this condition. And the person creating the AppScreen policies should also be aware of this issue and take some precautions.

Redirect Loop Detection

When an AppScreen policy is matched, and the disposition is Redirect, AppScreen compares the URL of the current request (the Request URL) to all of the Redirect URLs defined for all AppScreen policies. If the Request URL exactly matches any Redirect URL, then AppScreen realizes that there is a danger of a redirect loop, and it does not do the requested redirect. Instead, it performs a Deny 500 disposition. A message is logged in the error log (at the info level), similar to the following example:

The request for URL http://www.mycompany.com:13188/index.html matches AppScreen policy 
myPolicy, which calls for a redirect to http://www.mycompany.com:13188/index.html. 
However, the requested URL is itself an AppScreen redirect URL, so the current request 
will not be redirected.

Policy Creation Guidelines

When creating a policy with a Redirect disposition, you should do a simple test to help ensure that the URL will not create a looping situation:

1. Open a web browser window, paste the Redirect URL into the Address field, and press Return to go to the URL.

2. After the page has displayed, look in the Address field and see if the URL has changed.

3. If the URL in the Address field is different from what you pasted in, then you should copy the URL from the Address field and use that URL as your Redirect URL.

It might seem obvious that the Address field should not change. However, there are some cases when the Address field could change:

•If the destination page itself does a redirect. For example, if error.asp does a redirect to error2.asp, then you should use error2.asp as your Redirect URL.

•If the destination URL is not in a standard form. For example, if you enter the URL http://www.company.com, it is often standardized to http://www.company.com/ or http://www.company.com/index.html.

Ignore Disposition

Having a disposition of Ignore is similar to having a disposition of Pass. The difference is that Pass actually evaluates the rule to see if the policy applies. In contrast, Ignore ignores the rule without evaluating it, even if a higher-level policy (such as a global policy or a policy in a higher-level IF statement) references the rule.

Having a policy with a disposition of Ignore might seem identical to not having the policy at all. At a given AppScreen Class level, this is true. However, the reason the Ignore disposition is used is to allow a given AppScreen class policy to override a policy that was set in a higher-level AppScreen class. One of the features of AppScreen classes is that they allow you to specify behavior that overrides previously-defined behavior. Not only can a class add additional policies, but by using the Ignore keyword it can effectively remove existing policies.

For example, if a global policy specifies a rule to be evaluated, and you want that rule to be ignored for a given AppScreen class, in that AppScreen class you would create a policy with a disposition of Ignore that references the rule.

Here is an example of using the Ignore disposition to override a globally-defined behavior. The following configuration enables the checkFileUpload rule at the global level, but disables it for a particular URL, if the expected cookie is set:

AppScreenPolicy checkFileUpload | Deny 403 | Audit

<AppScreenClass AllowTechSuppFileUploads>

	Url "/techsupport/uploadFile\.cgi"

	IF ($http_cookie_present(SUPPORT_USER)) THEN

		AppScreenPolicy checkFileUpload | Ignore

	ENDIF

</AppScreenClass>

Policy Actions

Actions are things that AppScreen does when this policy's rule is matched. A policy can have zero or more actions. Action keywords are listed in Table 6-3.

Table 6-3 Policy Action Keywords

Action Keyword	Description
Severity level	Sets the severity of this policy. The level is an integer between 1 and 5, where 1 is the most critical. The numbers can be thought of like this: 1. Critical 2. Major 3. Normal 4. Minor 5. Informational If level is not specified, it defaults to 3. If the policy is matched, and if the severity level of the policy is less than or equal to AppScreenAlertSeverity, then an SNMP alert is triggered as described in the "SNMP Notification" section
Exec command	This executes a specified system command (such as a binary or a shell script). The path to the command must be an absolute path (beginning with /).
Pause millisec	This pauses for the specified number of milliseconds. The valid values for millisec are from 0 to 3600000 (one hour).

AppScreen Rules

AppScreen Rules determine whether the current request matches the criteria specified in the rule. Matching is done by applying operators (regular expression match and rule match) to attributes (URL, query string, cookie value, etc.) and values (regular expressions and rule names) that are specified in the rule definition.

In simple terms, a rule is a Boolean expression that evaluates to true if the match conditions are satisfied, or false if they are not.

A rule can be a simple expression (for example, comparing a single attribute against a specified value). Or a rule can be a compound expression, tying together simple expressions with ANDs and ORs.

AppScreen rules are defined in two XML configuration files that reside in the conf directory where the fgn.conf file is stored:

•appscreen-rules-standard.xml: This is the standard rules file provided by Cisco that includes a set of predefined AppScreen Rules. It may be updated when the application appliance system is upgraded. We strongly advise against manually editing this file, because this file will be overwritten (and the edits will be lost) when the system is updated.

•appscreen-rules-custom.xml: This is the file where you can define additional AppScreen Rules, or override standard rules with your own customized definitions. When the application appliance starts, the standard file is loaded first and then the custom file is loaded; if the same rule exists in both files, the one in the custom file overrides the one in the standard file.

For the document type definition (DTD) of the AppScreen rules XML files, see "AppScreen Rules DTD."

The following subsections cover these topics:

•Rule Components

•Using Multiple Attributes and Values

•Regular Expression Matching

•Exec Environment

•Predefined Rules

•Scanning POST Data and File Uploads

Rule Components

The components of a rule definition are described in the following subsections:

•Rule Operators

•Rule Attributes

•Rule Values

Rule Operators

Operators compare attributes to values. They are specified by the <op> XML element. Operators are listed in Table 6-4.

Table 6-4 Rule Operators

Operator	Description
regexMatch	The attribute is compared to a specified regular expression. These are case-insensitive POSIX extended regular expressions. For details, see the "Regular Expression Matching" section.
exists	The rule evaluates to true if the attribute exists, or false if not.
ruleMatch	Determines if the specified rule was matched for this request. If so, this rule evaluates to true, otherwise false. This provides a way to develop a set of rules that can be combined into more complex rules. This allows the reuse of rules, rather than having to cut and paste the rule definitions.
not	Logical NOT operation on exactly one nested expression. If the expression is true then the rule evaluates to false, and if the expression is false, the rule evaluates to true.
and	Logical AND operation on two or more nested expressions. All nested expressions must evaluate to true for the rule to evaluate to true.
or	Logical OR operation on two or more nested expressions. Any of the nested expressions must evaluate to true for the rule to evaluate to true.

Rule Attributes

Rule attributes are attributes of the request. They are specified by the <attribSet> XML element. Each <attribSet> element can contain one or more <attrib> elements specifying the attributes to match.

Attribute keywords are listed in Table 6-5.

Table 6-5 Rule Attributes

Attribute Keyword	Description
Single Request Attributes
URL	URL, not including any query string. For example, for this full URL: http://jdoe:pass@www.xyz.com/a/b.jsp?s=1&t=2 the following value is used: http://jdoe:pass@www.xyz.com/a/b.jsp
URL_WITH_QUERY_STRING	URL, including any query string. For example, for this full URL: http://jdoe:pass@www.xyz.com/a/b.jsp?s=1&t=2 its complete value is used: http://jdoe:pass@www.xyz.com/a/b.jsp?s=1&t=2
QUERY_STRING	Query string, or the empty string if there is no query string. For example, for this full URL: http://jdoe:pass@www.xyz.com/a/b.jsp?s=1&t=2 the following value is used: s=1&t=2
METHOD	GET, POST, HEAD, etc.
REMOTE_ADDR	Client IP address from which the request was received.
cookie[name]	Value of the cookie identified by name.
header[name]	Value of the header identified by name.
Multiple Request Attributes
For each of these attributes, the attribute represents the union of all values of the multi-valued attribute. The matching logic cycles through all of the values of the specified attribute in an attempt to find a match.
param[name]	All values of the parameter identified by name.
ALL_CONTENT	URL (without query string), parameter names and values, cookie names and values, and header names and values.
ALL_CONTENT_VALUES	URL (without query string), parameter values, cookie values, and header values.
ALL_PARAM_CONTENT	Parameter names and values.
ALL_PARAM_NAMES	Parameter names.
ALL_PARAM_VALUES	Parameter values.
ALL_COOKIE_CONTENT	Cookie names and values.
ALL_COOKIE_NAMES	Cookie names.
ALL_COOKIE_VALUES	Cookie values.
ALL_HEADER_CONTENT	Header names and values.
ALL_HEADER_NAMES	Header names.
ALL_HEADER_VALUES	Header values.
ALL_UPLOADED_FILE_NAMES	Names of files being uploaded with this request.
ALL_UPLOADED_FILE_MIME_TYPES	MIME types of files being uploaded with this request.

Rule Values

Values are literal values that are specified in the rule definition. Depending on the type of operator, the value can be a regular expression or the name of another rule.

Values are specified by the <valset> XML element. A <valset> element can contain:

•one or more <val> elements with a type attribute set to regex

•one or more <rulename> elements that specify the name of another rule

Using Multiple Attributes and Values

In many cases, it is useful for a rule to check the value of multiple attributes and/or multiple values. This can be accomplished in two ways:

•Use a compound expression. Create a simple expression for each attribute/value pair you want to check, and then join these simple expressions with the appropriate ANDs and ORs. However, this can become quite verbose if there are many possible combinations of attributes and values.

•Use a simple expression with sets of attributes and values, described in the remainder of this section.

A simple expression can contain an attribute set (<attribSet>), which is a list of multiple attributes to be checked, and/or a value set (<valSet>), which is a list of multiple values to be checked.

A simple expression can have any of the following:

•one attribute checked against one value

•one attribute checked against multiple values

•multiple attributes checked against one value

•multiple attributes checked against multiple values

The multiple attributes and values are all implicitly ORed together. If any attribute listed in the simple expression matches any value, the expression evaluates to true.

If you need the behavior of AND instead of OR, then use a compound expression joined with ANDs.

Regular Expression Matching

The regexMatch operator matches content using a regular expression pattern.

Content

The content for each request attribute is used as it came from the client, except for the URL encoded character transformation described earlier in the "Overview" section.

You need to take special caution with the URL_WITH_QUERY_STRING and QUERY_STRING attributes. Because the entire string is transformed, it is not advisable to use these attributes for matching the name or value of a particular parameter. Instead, you should use the provided pre-parsed attributes like param[name], ALL_PARAM_NAMES, ALL_PARAM_VALUES, ALL_PARAM_CONTENT, and so on.

For example, consider the query string "?a=b%3dc". This is transformed to "a=b=c". If you had a regular expression looking for "b=c", it would match this query string, even though that might not be what you intended.

In short, the transformed query string is provided but needs to be used with caution.

Regular Expression Patterns

The regular expression patterns are case-insensitive, extended POSIX patterns and the syntax is discussed in "Regular Expressions."

There are some additional regular expression features and things to be aware of when using AppScreen.

XML Escaping

Because the AppScreen rules file is an XML file, there are some characters that have special meaning in an XML file that need to be escaped. These are listed in Table 6-6.

Table 6-6 XML Escape Characters

Character	XML Escape
<	&lt;
>	&gt;
&	&amp;

Or, if you prefer, you can use an XML CDATA section for any regular expressions that contain special XML characters. For example, if you want to search for the string "a&b=c", either of the following two regular expressions can be used:

<val type="regex">a&amp;b=c</val>

<val type="regex"><![CDATA[a&b=c]]></val>

Refer to an XML reference manual for more details on XML escape sequences and CDATA sections.

Backslashes and Hex Character Codes

You may want to match a character (or range of characters) that is non-printable. You can specify such characters using their hexadecimal character code using the following syntax:

\xhh

where hh is the character code, for example, \x1a for the Control-Z character.

The following rules apply:

•The \x must be followed by exactly two hex digits. Both the x and the digits may be in either lower or upper case. If valid hex digits are not found, the literal text is used. For example, "\xT3" would be treated as "\xT3" since T is not a valid hex digit.

•To escape the backslash character, double it. For example, "\x09" is treated as a TAB character, whereas "\\x09" is treated as "\x09".

•The character code 0 (\x00) cannot be used. To search for a null byte in the request content, use the term %00 as described in the "Preprocessing Content Transformation" section.

Reversing Regular Expression Match Result

Sometimes it is useful to reverse the results of a match operation. This can be done by using the reverse option on the regexMatch operator. For example:

<op type="regexMatch" reverse="true">

	<valSet>

		<val type="regex">\.((txt)|(pdf)|(doc)|(xls))$</val>

	</valSet>

	<attribSet type="include">

		<attrib src="req" type="enum" name="ALL_UPLOADED_FILE_NAMES" />

	</attribSet>

</op>

This match will return true if any of the uploaded filenames do not match the given pattern.

This syntax is generally needed only when you have multi-valued attributes, like ALL_UPLOADED_FILE_NAMES in the above example. If you have just single values, you can simply surround the match with a not operator, for example:

<op type="not">

	<op type="regexMatch">

		<valSet>

			<val type="regex">^1234$</val>

		</valSet>

		<attribSet type="include">

			<attrib src="req" type="param" name="userid" />

		</attribSet>

	</op>

</op>

Exec Environment

The programs or scripts that you launch using the AppScreen Exec command are run in a forked process that inherits the environment of the AppScreen process. The AppScreen process does not wait for the child process to complete—it is launched asynchronously.

In addition to the parent process environment, the following environment variables are available to the child process:

•APPSCREEN_URL. This is equal to the attribute URL_WITH_QUERY_STRING.

•APPSCREEN_CLASS. The name of the AppScreen class to which this request belongs.

•APPSCREEN_POLICY. The name of the AppScreen policy that was matched.

•APPSCREEN_TRNID. The unique transaction ID for this request. This is the concatenation of the instance ID (instanceID), a dash character ("-"), and the transaction sequence number (trnNum) in the FgnStatLog file. It is a string like the following: r0liy3whwsjbeviy2a31yxppzg-2.

•APPSCREEN_PORT. The port number of this instance of the application appliance performance node. This is useful in cases where multiple nodes are installed and running on the same server.

•APPSCREEN_SEVERITY. The numeric severity of the policy (a number from 1 to 5, where smaller numbers are more severe), as set by the Severity keyword (see Table 6-3). If not set, the default severity is used.

You can use these variables in a program or script. Here is a simple example:

#!/bin/bash

LOG_DIR="/path/to/some/dir"

LOG_FILE="$LOG_DIR/appscreen-match.log"

# blank line

echo "" >>"$LOG_FILE"

# timestamp

TSTAMP=$(date)

echo "[$TSTAMP] $0 $@" >>"$LOG_FILE"

# details of match

# (the following echo command is all on one line)

echo "AppScreen Policy matched: $APPSCREEN_POLICY, URL: $APPSCREEN_URL, TRNID: 
$APPSCREEN_TRNID" >>"$LOG_FILE"

This example will produce output like this:

[Mon Jul 26 14:30:02 PDT 2004] /some/dir/report-appscreen-match-1.sh 

AppScreen Policy matched: checkTest, URL: 
http://testserver/test.jsp?p=lion&q=tiger&r=bear, TRNID: 5rytbq1attdu4uix0uu5ixnfpe-2

Predefined Rules

Table 6-7 describes the factory default rules that are predefined in the appscreen-rules-standard.xml configuration file. These rules are provided to scan content for known risks. For the precise definitions, you can view the rule text in the appscreen-rules-standard.xml file. As described in the "AppScreen Rules" section, these rules can be overridden (and new rules can be added) by editing the appscreen-rules-custom.xml file.

Table 6-7 Predefined Rules

Rule	Description
nullByte	Scans content for null (binary zero value) bytes. Null bytes can be used to exploit buffer overflow vulnerabilities or create other faults in back-end applications.
htmlTagStart	Scans content for the symbol "<", which indicates the beginning of an HTML tag. Note that although this rule is predefined, there is no default policy to evaluate this rule, because the presence of the "<" character is not clear evidence of an intrusion attempt.
script	Scans content for the string "<script>". Script injection can be used to attempt to steal the credentials of authorized site users.
sql	Scans content for SQL keywords and constructs. SQL injection can be used to attempt to view or modify restricted data in the database.
directoryTraversal	Scans content for the parent directory path "../". Directory traversal can be used to attempt to go outside the defined bounds of the web site or application to view unauthorized data or perform unauthorized actions.
binary	Scans content for non-printable characters. Binary characters can be used to attempt to force a fault in the back-end application.
prohibitedFileUpload	Scans file uploads for non-permitted file types. Uploaded files may contain viruses, spyware, or other intrusions. A default list of allowed file types is provided as an example. The default allowed file types are those with the following extensions: .txt, .pdf, .doc, and .xls. This list can be modified for your needs. You can also examine the MIME type of the uploaded files, either in addition to or instead of the filename extension.

Scanning POST Data and File Uploads

This section discusses data and file scanning issues.

Buffer Limit

An HTTP POST can send a very large (effectively unlimited) amount of data; in an extreme case, the client can just keep sending a stream of data for the server to handle. In order to parse and inspect the POST data, AppScreen needs to load the data into a buffer in memory. The following global keyword is used to control the maximum amount of POST data that can be buffered by AppScreen:

PostContentBufferLimit maxKB

The limit is specified in kilobytes (KB). Valid values range from 0 to 1000, with a default of 40 KB.

If the POST content length exceeds the configured buffer size, AppScreen does not take any special action. It simply loads as much POST data as possible into the buffer and makes it available for inspection as described below.

Content Types

There are two types of standard HTTP form POST operations. They are distinguished by the value in the Content-Type header:

•application/x-www-form-urlencoded

This type of POST represents the majority of all HTTP POSTs. This is just a standard POST of a web page form.

For this type of POST, AppScreen works just like it does for GET requests. You have the same access to all of the form parameter names and values, just as you would if the parameters were specified in a GET query string. The only limitation is that you only have access to the amount of data that fits in the AppScreen POST buffer, as per the PostContentBufferLimit keyword.

•multipart/form-data

This type of POST is much less common. Its main purpose is to allow browser users to upload files to a web site or application. For example, if you use a web-based email program, and you want to attach a file to an email that you are sending, the upload of the file is done using this type of POST. Another usage (even less common) of this type of POST is to send binary data (for example, from a custom browser plug-in, or from a non-browser HTTP client).

For this type of POST, AppScreen does not give you access to the parameter names and values. However, AppScreen does give you access to the other parts of the request (URL, headers, cookies) as usual.

Also, if the post includes one or more file uploads, AppScreen makes the filenames and MIME types of the uploaded files available for inspection with the following request attributes: ALL_UPLOADED_FILE_NAMES and ALL_UPLOADED_FILE_MIME_TYPES. With AppScreen, you could, for example, block all POSTs of this type. Or, you could allow such posts only when they contain file uploads with file names ending in ".doc", or files of type "text/plain", and so on.

It is conceivable that a POST could be sent with a Content-Type other than the two standard types mentioned above. This would not be done by a standard web browser, but it could be done by an unusual (or malicious) user agent. AppScreen rules can detect and block such POSTs by examining the HTTP method and the Content-Type header.

AppScreen Logging

Requests that match AppScreen Classes are logged in the FgnStatLog file.

---

Note An AppScreen policy with a disposition of Ignore is not logged, because no matching is done for such policies.

---

Here is an FgnStatLog excerpt showing a request that did not match any policy:

<APS> <AST> 1 </AST> </APS>

Here is an FgnStatLog excerpt showing a request that matched the "script" policy in the Root AppScreen Class:

<APS> <AST> 0 </AST> <ASC> Root </ASC> <ASP> script </ASP> <ASL> 1 </ASL> </APS>

For details on these log entries, see the "FgnStatLog" section.

Reports of requests that match AppScreen Classes are also available through the AppScreen Reports command in the Management Console. For details, see the "AppScreen Reports" section.

SNMP Notification

If the severity of a matched policy is less than or equal to the value defined by the AppScreenAlertSeverity keyword (see Table 6-1), then an SNMP trap is issued.

You can control whether AppScreen sends these traps, and you can configure AppScreen to send the trap to one or more SNMP trap sinks (SNMP management stations).

To enable SNMP traps, set the following configuration parameters (the values given here are examples; replace these with your own values):

AppScreenAlertSeverity 2 
AppScreenSnmpTrap On 
AppScreenSnmpTrapSink 10.0.10.131 
AppScreenSnmpCommunity AppScreenAlert

With this example configuration, any matched AppScreen policies with a severity less than or equal to 2 will result in SNMP traps being sent.

The default value for AppScreenSnmpCommunity is public, so you don't need to specify that keyword if you want to use the default.

You can use either a host name or IP address for the trap sink. By default, AppScreen sends SNMP traps to the standard SNMP trap port of 162. You can specify a different port by appending it to the trap sink host value with a colon, like this: 10.0.10.131:22345

Also, you can specify the AppScreenSnmpTrapSink keyword multiple times if you want the notification to be sent to multiple destinations.

Here is another example configuration:

AppScreenAlertSeverity 2 
AppScreenSnmpTrap On 
AppScreenSnmpTrapSink myhost:12345 
AppScreenSnmpTrapSink 10.0.10.131

Receiving and Processing SNMP Traps

AppScreen SNMP traps can be received and processed by any software or system that is capable of handling standard SNMP v1 traps. For example, HP OpenView or other commercial network management software, or the open source snmptrapd program.

Figure 6-1 shows example of how an AppScreen trap appears in the HP OpenView user interface.

Figure 6-1 AppScreen Trap in HP OpenView

Here is an example of how an AppScreen trap is reported by snmptrapd (line breaks have been added for clarity):

2004-10-01 19:55:53 devsrv3 [10.0.0.26] (via localhost [127.0.0.1]) TRAP, SNMP v1, community public

.iso.3.6.1.4.1.9007.3 Enterprise Specific Trap (101) Uptime: 265 days, 13:18:49.61

.iso.3.6.1.4.1.9007.3.101.1 = "sql"

.iso.3.6.1.4.1.9007.3.101.2 = "ROOTAPPSCREENCLASS/"

.iso.3.6.1.4.1.9007.3.101.3 = "a0f1fvd43zsggknnm3tpyrux2d-1"

.iso.3.6.1.4.1.9007.3.101.4 = 13180

.iso.3.6.1.4.1.9007.3.101.5 = 2

MIB

The SNMP Management Information Base (MIB) for AppScreen is available for your reference, or for importing into SNMP management software. The file is located at: $AVS_HOME/perfnode/conf/fgn_appscreen_mib.mib

AppScreen Reports

Reports of requests that match AppScreen Classes are also available through the AppScreen Reports command in the Management Console. For details, see the "AppScreen Reports" section.

The AppScreen reports can include all requests that match AppScreen Classes, whether or not they triggered an SNMP alert. You can configure what severity levels of matching requests you want to see in the reports.