HPE Security Fortify Runtime

Software Version: 17.3

.NET Edition Designer Guide

Document Release Date: April 2017

Software Release Date: April 2017

.NET Edition Designer Guide

Legal Notices

Warranty

The only warranties for Hewlett Packard Enterprise Development products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HPE shall not be liable for technical or editorial errors or omissions contained herein.

The information contained herein is subject to change without notice.

Restricted Rights Legend

Confidential computer software. Valid license from HPE required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The software is restricted to use solely for the purpose of scanning software for security vulnerabilities that is (i) owned by you; (ii) for which you have a valid license to use; or (iii) with the explicit consent of the owner of the software to be scanned, and may not be used for any other purpose.

You shall not install or use the software on any third party or shared (hosted) server without explicit consent from the third party.

Copyright Notice

© Copyright 2015 - 2017 Hewlett Packard Enterprise Development LP

Trademark Notices

Adobe™ is a trademark of Adobe Systems Incorporated.

Microsoft® and Windows® are U.S. registered trademarks of Microsoft Corporation.

Documentation Updates

The title page of this document contains the following identifying information:

Software Version number

Document Release Date, which changes each time the document is updated

Software Release Date, which indicates the release date of this version of the software

To check for recent updates or to verify that you are using the most recent edition of a document, go to:

https://www.protect724.hpe.com/community/fortify/fortify-product-documentation

You will receive updated or new editions if you subscribe to the appropriate product support service. Contact your HPE sales representative for details.

HPE Security Fortify Runtime (17.3)

Page 2 of 8

.NET Edition Designer Guide

Contents

Preface

7

Contacting HPE Security Fortify Support

7

For More Information

7

About the Documentation Set

7

Change Log

8

Chapter 1: Introduction to this Guide

1

Intended Audience

1

Executable Sample Code

1

Related Documents

2

All Products

2

HPE Security Fortify Runtime

3

Chapter 2: Overview of HPE Security Fortify Runtime: .NET Edition Designer Guide

6

Overview of Fortify Runtime for .NET Components

6

Behavior is Defined by Rules

6

Event Handlers Define Response to Events

7

Overview of Fortify Runtime Modes of Operation

7

Overview of Standalone Mode

7

Overview Federated Mode

7

Fortify Runtime User Roles

8

Fortify Runtime Analyst

8

Fortify Runtime Operator

8

Fortify Runtime Solution Designer

9

Fortify Runtime User Role Examples

9

Chapter 3: Writing Event Handlers

10

About Event Handlers

10

Event Handler Example

10

Picture Strings

11

Matching Events

11

HPE Security Fortify Runtime (17.3)

Page 3 of 8

.NET Edition Designer Guide

MatchAttribute

12

Cluster and MatchCluster

14

Handling Events

17

<Filter>

17

<Create Event>

19

<SetAttribute>

20

<Dispatch>

20

<Action>

21

display Action

22

Event Handler Scenarios

23

Write Events to a Local Event Log File in Federated Mode

24

Preventing Sensitive Information from Being Recorded in Events

24

Running Behind a Load Balancer

25

Chapter 4: Writing Rules

27

Introduction to Fortify Runtime Rules

27

Overview of a Complete Fortify Runtime Rule

27

Overview of Fortify Runtime Rules

29

Overview of the Fortify Runtime Rule Header

29

Program Points

30

Specifying Program Point Attributes

31

Specifying the Program Location in a Program Point

31

Specifying a Method Identifier

32

Specifying a Built-in Program Point

34

Capturing Values in a Program Point

34

Defining a Program Point Outside a Rule

36

Overlapping Program Points

37

Monitor Specifications

38

Timer Monitor Example

38

The MonitorSpec Element

38

Monitor Attributes

39

Predicate

40

Configuration

41

Bindings

42

Defining Abstract Monitor Specifications in Monitor Definitions

43

Attribute Sets

44

HPE Security Fortify Runtime (17.3)

Page 4 of 8

.NET Edition Designer Guide

The Default Fortify Runtime Monitor Set

45

The Fortify Runtime Guard Monitor Type

45

The Fortify Runtime ParameterMonitor Monitor Type

46

The Fortify Runtime Timer Monitor Type

48

The Predicate Language

49

Syntax

49

Types

50

Variables

51

A Special Variable: Request

51

Rules Scenarios

52

Viewing and Changing HPE Security Fortify Rules

52

Making a Whitelist Rule

53

Capturing a Boolean

54

Chapter 5: Writing Monitors

58

Introduction to Fortify Runtime Monitors

58

Rules, Monitors, and Fortify Runtime

58

Restrictions and Requirements

59

Rule Properties Become Static Member Variables

59

An Example Monitor

59

A Rule that References the Example Monitor

60

Rule Bindings Become Member Variables

62

Watching the Target Program with Control Points

64

Changing Control Flow in the Target Program

65

Classes Provided by the Fortify Runtime Platform

66

Adding a New Predicate Library

66

Compiling and Executing a Monitor

67

Referencing Monitors from a Configuration File

67

Bundling Monitors with Rules in an RPR File

67

Example Source Code for a Complete Monitor

68

Chapter 6: Writing Filter Classes

71

Introduction to Fortify Runtime Filter Class

71

Creating a Filter Class

71

Installing a Filter Class

71

HPE Security Fortify Runtime (17.3)

Page 5 of 8

.NET Edition Designer Guide

Referencing a Filter Class

71

An Example Filter Class

72

Chapter 7: Writing a Federation Configuration Template and Bootstrap Configuration File

76

Creating a Bootstrap Configuration

77

Creating a Federation Template Configuration

78

Specifying Rules

80

An Additional Host Dispatch Option

80

Including Event Handlers Defined in the User Interface

81

The Controller Event Handler Chain

82

Chapter 8: Business Scenarios

84

Tuning

84

Eliminating False Positives

84

Send Documentation Feedback

85

HPE Security Fortify Runtime (17.3)

Page 6 of 8

.NET Edition Designer Guide

Preface

Preface

Contacting HPE Security Fortify Support

If you have questions or comments about using this product, contact HPE Security Fortify Technical Support using one of the following options.

To Manage Your Support Cases, Acquire Licenses, and Manage Your Account

https://support.fortify.com

To Email Support

fortifytechsupport@hpe.com

To Call Support

1.844.260.7219

For More Information

For more information about HPE Security software products: http://www.hpe.com/software/fortify

About the Documentation Set

The HPE Security Fortify Software documentation set contains installation, user, and deployment guides for all HPE Security Fortify Software products and components. In addition, you will find technical notes and release notes that describe new features, known issues, and last-minute updates. You can access the latest versions of these documents from the following HPE Security user community website:

https://www.protect724.hpe.com/community/fortify/fortify-product-documentation

You will need to register for an account.

HPE Security Fortify Runtime (17.3)

Page 7 of 8

.NET Edition Designer Guide

Change Log

Change Log

The following table lists changes made to this document. Revisions to this document are published only if the changes made affect product functionality.

Software Release /

 

 

Document Version

Changes

 

 

17.3

Updated: No functional changes.

 

 

16.8

Updated: Minor edits.

 

Renamed Built-in filters - StripSensitiveData is now named

 

 

 

 

MaskPersonalData and CEFFilter is now ProcessCEF.

 

Increased syslog protocol restrict message size - Supports messages up

 

 

to 65,500 bytes.

 

 

16.3

Replaced: HP to HPE Branding, Release numbering changed to <yy.mm>

 

Updated: Minor edits.

 

 

 

HPE Security Fortify Runtime (17.3)

Page 8 of 8

Chapter 1: Introduction to this Guide

This document provides content to aid in the configuration and customization of HPE Security Fortify Runtime for a given application that operates on a .NET platform.

Intended Audience

The audience for this guide may be a Fortify Runtime Solution Designer who often creates event handlers and chooses values for settings, sometimes writes rules, and occasionally creates a monitor. The Fortify Runtime Solution Designer must understand both software and security.

Executable Sample Code

Throughout this guide, you will find numerous instances of sample code. The Fortify Runtime SDK is available in the HPE Security Fortify Software ISO.

The following file is available electronically. See the HPE Security Fortify Software System Requirements for details.

HPE_Security_Fortify_Runtime_SDK_Dotnet_xx.x.zip where x.xx represents the current

version of Fortify Runtime.

Copy or download the appropriate file and then unzip the file wherever you want.

The directory structure of the unzipped contents is as follows:

HPE_Security_Fortify_Runtime_SDK_Dotnet_xx.x.zip <unzip_dir>\dotnet_sdk\apidoc

<unzip_dir>\dotnet_sdk\apidoc

<unzip_dir>\dotnet_sdk\DesignerGuide <unzip_dir>\dotnet_sdk\samples

<unzip_dir>\dotnet_sdk\schema

A solution file and individual project files for Microsoft Visual Studio 10.0 are included to make it easier to explore, experiment, and learn.

HPE Security Fortify Runtime (17.3)

Page 1 of 85

Related Documents

This topic describes documents that provide information about HPE Security Fortify Runtime.

Note: The Protect724 site location is https://www.protect724.hpe.com/community/fortify/fortify- product-documentation.

All Products

The following documents provide general information for all products.

Document / File Name

Description

Location

 

 

 

HPE Security Fortify Software

This document provides the

Included with product

System Requirements

details about the environments

download and on the

HPE_Sys_Reqs_<version>.pdf

and products supported for this

Protect724 site

version of HPE Security Fortify

 

 

 

 

Software.

 

 

 

 

HPE Security Fortify Software

This document provides an

Included on the Protect724 site

Release Notes

overview of the changes made

 

HPE_FortifySW_RN_

to HPE Security Fortify

 

Software for this release and

 

<version>.txt

 

important information not

 

 

 

 

included elsewhere in the

 

 

product documentation.

 

 

 

 

What’s New in HPE Security

This document describes the

Included on the Protect724 site

Fortify Software <version>

new features in HPE Security

 

HPE_Whats_New_

Fortify Software products.

 

 

 

<version>.pdf

 

 

 

 

 

HPE Security Fortify Open

This document provides open

Included with product

Source and Third-Party

source and third-party software

download and on the

License Agreements

license agreements for software

Protect724 site

HPE_OpenSrc_<version>.pdf

components used in HPE

 

Security Fortify Software.

 

 

 

 

 

 

HPE Security Fortify Glossary

This document provides

Included with product

HPE_Glossary.pdf

definitions for HPE Security

download and on the

Fortify Software terms.

Protect724 site

 

 

 

 

HPE Security Fortify Runtime (17.3)

Page 2 of 85

.NET Edition Designer Guide Chapter 1: Introduction to this Guide

HPE Security Fortify Runtime

The following documents provide information about Fortify Runtime.

Document / File Name

Description

Location

 

 

 

HPE Security Fortify Runtime

This document provides

Included with product

.NET Edition Designer Guide

information to aid in the

download and on the

HPE_RT_DotNet_Design_

configuration and

Protect724 site

customization of Fortify

 

Guide_<version>.pdf

 

Runtime for a given application

 

 

 

PDF only; no help file

that operates on a .NET

 

 

platform. The audience for this

 

 

guide includes an HPE Security

 

 

Fortify Runtime Solution

 

 

Designer who often creates

 

 

event handlers and chooses

 

 

values for settings, sometimes

 

 

writes rules, and occasionally

 

 

creates a monitor. The HPE

 

 

Security Fortify Runtime

 

 

Solution Designer must

 

 

understand both software and

 

 

security.

 

 

 

 

HPE Security Fortify Runtime

This document provides

Included with product

Java Edition Designer Guide

information to aid users in the

download and on the

HPE_RT_Java_Design_Guide_

configuration and

Protect724 site

customization of Fortify

 

<version>.pdf

 

Runtime for a given application

 

 

 

PDF only; no help file

that operates on a Java

 

 

platform. The audience for this

 

 

guide includes HPE Security

 

 

Fortify Runtime Solution

 

 

Designers who often create

 

 

event handlers and choose

 

 

values for settings, sometimes

 

 

write rules, and occasionally

 

 

create a monitor. The Fortify

 

 

Runtime Solution Designer

 

 

must understand both software

 

 

 

 

HPE Security Fortify Runtime (17.3)

Page 3 of 85

.NET Edition Designer Guide Chapter 1: Introduction to this Guide

Document / File Name

Description

Location

 

 

 

 

and security.

 

 

 

 

HPE Security Fortify Runtime

This document describes how to

Included with product

Application Protection (RTAP)

install the Fortify Runtime

download and on the

.NET Installation Guide

Agent for applications running

Protect724 site

HPE_RTAP_DotNet_Install_

under a supported .NET

 

Framework on a supported

 

<version>.pdf

 

version of IIS.

 

 

 

HPE_RTAP_DotNet_Install_

 

 

Help_<version>

 

 

 

 

 

HPE Security ArcSight

This document describes how to

Included with product

Application View Runtime

install the Fortify Runtime

download and on the

Agent Installation Guide

Agent for applications running

Protect724 site

HPE_AppView_RT_Agent_

under a supported Java

 

Runtime Environment (JRE) on

 

Install_<version>.pdf

 

a supported application server

 

 

 

HPE_AppView_RT_Agent_

or service and applications

 

Install_Help_<version>

running under a supported

 

 

.NET Framework on a

 

 

supported version of IIS.

 

 

 

 

HPE Security Fortify Runtime

This document provides

Included with product

Application Protection

information and procedures

download and on the

Operator Guide

that enable you to run and

Protect724 site

HPE_RTAP_Oper_Guide_

monitor the operation of HPE

 

Security Fortify Runtime

 

<version>.pdf

 

Application Protection.

 

 

 

HPE_RTAP_Oper_Help_

 

 

<version>

 

 

 

 

 

HPE Security ArcSight

This document provides brief

Included with product

Application View Quick Start

instructions about how to get

download and on the

HPE_AppView_Quick_Start_

started with installing and

Protect724 site

configuring HPE Security

 

<version>.pdf

 

ArcSight Application View.

 

 

 

PDF only; no help file

 

 

 

 

 

HPE Security Fortify RTAP

This document describes the

Included with product

Rulepack Kit Guide

detection capabilities of HPE

download and on the

 

 

Protect724 site

 

 

 

HPE Security Fortify Runtime (17.3)

Page 4 of 85

.NET Edition Designer Guide Chapter 1: Introduction to this Guide

Document / File Name

Description

Location

 

 

 

HPE_RTAP_Rulepack_Kit_

Security Fortify Runtime

 

<version>.pdf

Application Protection (RTAP)

 

PDF only; no help file

and the HPE Security Fortify

 

RTAP Rulepacks. Each category

 

 

 

 

of attack, vulnerability, or audit

 

 

event detected by RTAP is

 

 

described in this document.

 

 

 

 

HPE Security Fortify RTAL

This document describes the

Included with product

Rulepack Kit Guide

capabilities of the HPE Security

download and on the

HPE_RTAL_Rulepack_Kit_

Fortify Runtime Application

Protect724 site

Logging (RTAL) Rulepack Kit.

 

<version>.pdf

 

The HPE Security Fortify RTAL

 

 

 

PDF only; no help file

Rulepack is a special Runtime Kit

 

 

for HPE Security Fortify

 

 

Runtime. It provides

 

 

information about web

 

 

application internal activities to

 

 

ArcSight analysis servers so that

 

 

these events can be correlated

 

 

with other existing ArcSight

 

 

event information.

 

 

 

 

HPE Security Fortify Runtime

This document recommends

Included with product

Performance Tuning Guide

ways to address performance

download and on the

HPE_RT_Perf_Tuning_

bottlenecks a user might

Protect724 site

encounter in HPE Security

 

<version>.pdf

 

Fortify Runtime. It is meant to

 

 

 

PDF only; no help file

supplement, not replace, the

 

 

HPE Fortify Runtime

 

 

Installation and Configuration

 

 

guides. It is intended for users

 

 

who are familiar with and can

 

 

correctly install and run HPE

 

 

Security Fortify Runtime.

 

 

 

 

HPE Security Fortify Runtime (17.3)

Page 5 of 85

.NET Edition Designer Guide

Chapter 2: Overview of HPE Security Fortify Runtime: .NET Edition Designer Guide

Chapter 2: Overview of HPE Security Fortify

Runtime: .NET Edition Designer Guide

This section contains the following topics:

 

Overview of Fortify Runtime for .NET Components

6

Fortify Runtime User Roles

8

Overview of Fortify Runtime for .NET Components

Fortify Runtime for .NET functions with programs running under a supported version of CLR. The .NET program can be a Web application container or any other .NET program. The figure below shows the relationship of the Fortify Runtime components.

Behavior is Defined by Rules

Fortify Runtime behavior is defined by rules. A Rulepack serves as a container for one or more rules. HPE Security supplies the Fortify Runtime Rulepacks for detecting common types of attacks and vulnerabilities. You can also create your own custom Rulepacks.

A single rule specifies one or more program points that declare where to monitor a target program and one or more monitors that define what to check for at a given program point. When a monitor detects the specified operations in the target program, it creates an event.

HPE Security Fortify Runtime (17.3)

Page 6 of 85

.NET Edition Designer Guide

Chapter 2: Overview of HPE Security Fortify Runtime: .NET Edition Designer Guide

Event Handlers Define Response to Events

An event is a collection of attributes. Attributes provide information such as category of problem that has been detected and the location in the code where the problem was detected.

Fortify Runtime evaluates the ongoing stream of events with a set of event handlers. An event handler matches against event attributes and specifies the way Fortify Runtime should respond. A response might include a passive activity such as logging the event or sending out a syslog notification, or it might include an action: a change to the state of the target program. An action could throw an exception or display a special error message to the user.

Event handlers are organized in an event handler chain. By default, Fortify Runtime stops evaluating the event handler chain after it finds the first matching event handler. The event handler chain enables the security designer to organize event handlers into a sequence that provides the optimal action to take to protect the target program.

Overview of Fortify Runtime Modes of Operation

Fortify Runtime has two modes of operation: Standalone Mode and Federated Mode.

Overview of Standalone Mode

In Standalone Mode, Fortify Runtime reads its configuration (including rules, event handlers, and other settings) from disk.

Overview Federated Mode

In Federated Mode multiple computers running HPE Security Fortify Runtime Platform work in concert. They use the network to share a common source of configuration information and common event repository.

In Federated Mode, an instance of Fortify Runtime:

Operates as a Host—a member of a Fortify Runtime Federation

Receives its configuration from a Federation Controller

Transmits security events to its Federation Controller

The following figure shows the relationship of three hosts to an instance of Fortify Software Security Center running as those hosts' Federation Controller.

HPE Security Fortify Runtime (17.3)

Page 7 of 85

.NET Edition Designer Guide

Chapter 2: Overview of HPE Security Fortify Runtime: .NET Edition Designer Guide

After a Fortify Runtime Host receives a configuration from its Federation Controller, the Host caches the configuration. The Host uses that cached configuration until the Federation Controller sends a new configuration. The Host preserves the most recent cached configuration across program restart. This enables a Fortify Runtime Host running in Federated Mode to resume operation without waiting for the Federation Controller to re-send the Host's configuration.

Fortify Runtime User Roles

Deploying, configuring, customizing, and monitoring Fortify Runtime often involves more than one person within an organization. In this section the three conceptual roles for Fortify Runtime users are described. A single individual may fulfill more than one role, or duties for a single role may be spread across a team.

The Fortify Runtime conceptual roles may be classified as:

Fortify Runtime Analyst

Fortify Runtime Operator

Fortify Runtime Solution Designer

Fortify Runtime Analyst

This person is responsible for monitoring Fortify Runtime on an ongoing basis and for making limited configuration changes. A Fortify Runtime Analyst looks at Fortify Runtime output and makes decisions. A Fortify Runtime Analyst might modify event handlers or adjust settings within the structure established by the Fortify Runtime Solution Designer. This is principally a security role.

Fortify Runtime Operator

This person is responsible for installation, basic configuration, and ongoing maintenance of the Fortify Runtime system. A Fortify Runtime Operator expects the Fortify Runtime Solution Designer to provide

HPE Security Fortify Runtime (17.3)

Page 8 of 85

.NET Edition Designer Guide

Chapter 2: Overview of HPE Security Fortify Runtime: .NET Edition Designer Guide

a configuration for a particular application. With the configuration in hand, the Fortify Runtime Operator can deploy Fortify Runtime. A Fortify Runtime Operator has skills that are similar to those of a system administrator.

Fortify Runtime Solution Designer

This person is responsible for configuring and customizing Fortify Runtime for a given application. A Fortify Runtime Solution Designer often creates event handlers and chooses values for settings, sometimes writes Rules, and occasionally creates a monitor. The Fortify Runtime Solution Designer must understand both software and security.

Fortify Runtime User Role Examples

These roles may be fulfilled in different ways to meet the needs of different organizations.

Example 1: Business unit in a large enterprise

Fortify Runtime Analyst: Central security team

Fortify Runtime Solution Designer: Central security team working with software developers

Fortify Runtime Operator: Operations team

Example 2: Small team

Fortify Runtime Analyst: Data center Network Operations Center (NOC)

Fortify Runtime Solution Designer: Software architect

Fortify Runtime Operator: Development team

Example 3: Outsourced data center

Fortify Runtime Analyst: Central security team

Fortify Runtime Solution Designer: HPE Security Fortify Global Services

Fortify Runtime Operator: Outsourced data center operations

HPE Security Fortify Runtime (17.3)

Page 9 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Chapter 3: Writing Event Handlers

This section contains the following topics:

 

About Event Handlers

10

Handling Events

17

display Action

22

Event Handler Scenarios

23

About Event Handlers

When something noteworthy happens in the target program, the Fortify Runtime Platform generates an event. The event handlers determine how events are processed. An event handler can write an event to a log file, report the event using syslog, and/or modify the target program by invoking an action.

Event Handler Example

The following event handler chain that will throw an exception and log any session fixation attack. Events that are not related to session fixation will only be logged.

<EventHandlers>

<EventHandler>

<Match>

<MatchAttribute name="category">Session Fixation</MatchAttribute>

</Match>

<Handle>

<Dispatch name="log"/> <Action name="throw"/>

</Handle>

</EventHandler>

<Default>

<Handle>

<Dispatch name="log">

<Setting name="picture">default (no action)%n%all</Setting>

</Dispatch>

</Handle>

HPE Security Fortify Runtime (17.3)

Page 10 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

</Default>

</EventHandlers>

The event handlers work in a chain. The handler at the top of the chain sees the event first. The event propagates down the chain until it matches an event handler.

When an event handler matches an event, it handles it and the lower portion of the chain does not see the event. (This behavior is configurable.) The following table lists the attributes for the

<EventHandler> element.

Event Handler Attributes

Attribute

 

Name

Description

 

 

description

A description of the event handler.

 

 

enabled

The event handler is disabled if this attribute is set to false. If the event handler is

 

not enabled, an event handler will never match an event. By default enabled is

 

true.

 

 

label

A short name for the event handler.

 

 

propagate

To have event handler match an event but also allow that event to continue down

 

the handler chain, set propagate to true. By default, propagate is false.

 

 

Picture Strings

A number of places in the definition of an event handler accept picture strings. These strings are similar to printf-style format strings. An event's attributes will be used to perform substitutions on the given picture string. Picture strings interpret attribute names in the form %name or %{name}. %% is treated as a single % character.

In addition to regular event attributes, the following special substitutions are recognized:

%all - All attributes

%hostname - The name of the host computer

%location - The first line of the target program stack where the event was created

%n - Newline

%timestamp - The timestamp formatted as an ISO8601 string

Matching Events

An event handler may specify any number of Match tags. Each Match tag can contain any combination of MatchAttribute, Cluster, and MatchCluster elements. All of the elements in at least one Match tag must match the event in order for the event handler to execute.

HPE Security Fortify Runtime (17.3)

Page 11 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

The MatchAttribute element allows an event handler to match against the attributes of an event. The Cluster and MatchCluster elements allow the event handler to match against a sequence of events over a specified period of time. We will look at MatchAttribute, and then discuss Cluster,

and MatchCluster.

MatchAttribute

A MatchAttribute has a name and a value. The name of the MatchAttribute must match the name of the event attribute. The match is case-insensitive. The value of the MatchAttribute is a regular expression that must match the value of the named event attribute. The example below matches any

event that has com.example.me as part of its stack trace (the location attribute of an event).

Example: MatchAttribute element

<MatchAttribute name="location">Example\.Me</MatchAttribute>

You may invert the sense of a MatchAttribute tag by surrounding it with a Not tag. For example, to match all events that are not attacks, you could write something similar to the following example.

Example: Inverting MatchAttribute

<Not><MatchAttribute name="attack"/></Not>

You may match against more than one event attribute name in a single tag by using a vertical bar (pipe) to separate the names to be matched. The example below shows a tag that matches any event with a non-empty attribute named after one of Snow White’s seven dwarfs.

Example: Matching more than one attribute name with MatchAttribute

<MatchAttribute

name="Bashful|Doc|Dopey|Grumpy|Happy|Sleepy|Sneezy">.*</MatchAttribute>

The following table lists common event attributes. Note that monitors may output any additional fields as appropriate.

Common Event Handler Attributes

Event Attribute Name

Description

 

 

category

Event Seven Pernicious Kingdoms name

 

 

eventID

Unique Event ID

 

 

eventType

Type of event; can be any combination of attack, audit,

 

and/or vulnerability

 

 

kingdom

Seven Pernicious Kingdom name

 

 

location

The stack trace for the program point where the event was

 

generated

 

 

HPE Security Fortify Runtime (17.3)

Page 12 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Common Event Handler Attributes, continued

Event Attribute Name

Description

 

 

metaInfo.accuracy

Accuracy of rule

 

 

metaInfo.altcategoryCWE

Common Weakness Enumeration (CWE) ID of this category

 

 

metaInfo.altcategoryOWASP2004

OWASP 2004 Top 10 mapping

 

 

metaInfo.altcategoryOWASP2007

OWASP 2007 Top 10 mapping

 

 

metaInfo.altcategoryOWASP2010

OWASP 2010 Top 10 mapping

 

 

metaInfo.audience

The audience for the metaInfo category

 

 

metaInfo.coveredSCA

Identifies issues that can be found by Fortify Static Code

 

Analyzer (SCA)

 

 

metaInfo.impact

Impact of category if exploited

 

 

metaInfo.impactBias

Security impact of category

 

 

metaInfo.primaryAudience

Specify if the category is a security issue or quality issue

 

 

metaInfo.priority

The Fortify Priority Order of this event

 

 

metaInfo.probability

The probability that the category being exploited

 

 

MonitorID

The identifier of the monitor that generated the event

 

 

Reason

The reason why we flag the event (for example, report the

 

event as SQLi)

 

 

request.cookies

HTTP request cookies

 

 

request.headers

The list of all HTTP headers

 

 

request.host

The HTTP request host

 

 

request.ip

Client IP

 

 

request.method

The HTTP method

 

 

request.parameters

HTTP request parameters

 

 

request.path

The HTTP request path without query string

 

 

HPE Security Fortify Runtime (17.3)

Page 13 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Common Event Handler Attributes, continued

Event Attribute Name

Description

 

 

request.port

The local HTTP port

 

 

request.remote_user

The username of this HTTP session (if authenticated)

 

 

request.requestIid

A unique ID per each HTTP request

 

 

request.scheme

The HTTP scheme of this HTTP connection

 

 

request.sessionId

HTTP Session ID

 

 

RuleID

The identifier for the rule that generated the event

 

 

suggestedAction

The action to be taken

 

 

thrown_from

The stack trace for the original exception caught by the rule

 

 

timestamp

Epoch time of the event in ms.

 

 

Trigger

The trigger of this event

 

 

Some event attributes, notably action and dispatch, are added to the event after the event handler chain has been evaluated. Because the attributes do not yet exist when the event handler chain is evaluated, you cannot match against them in the event handler chain.

Cluster and MatchCluster

A cluster is a sequence of similar events that occur within a specified period of time. You might use a cluster to detect a brute-force password guessing attack or to limit the number of suspicious requests allowed before a user's session is terminated.

The Cluster tag defines a cluster. The Cluster tag shown in the example below will match when three events with the same category name occur within a ten-second window. In addition to matching on the 3rd event, the tag will continue to match any event with the same category name for five seconds after the 3rd event.

Example: Cluster tag

<Cluster id="nextc" n="3" window="10" linger="5" picture="%category" maxClusters="100"/>

The following table explains each of the cluster attributes. A cluster requires all attributes to be defined.

HPE Security Fortify Runtime (17.3)

Page 14 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Cluster Attributes

Event

 

Attribute

 

Name

Description

 

 

id

The identifier for the cluster tag (used by ClusterMatch tags).

 

 

linger

The length of time (in seconds) the tag will continue to match after a cluster is

 

found.

 

 

maxClusters

The maximum number of clusters the tag will attempt to track. A high value allows

 

the tag to keep track of more events but requires more memory. A low value could

 

cause the tag to miss clusters when they occur.

 

 

n

The number of events that will cause the cluster to match.

 

 

picture

The event format string used to group events. Example: the picture

 

%request.sessionid%category will create clusters out of the session identifier

 

and the category from the event. You might use such a picture to filter out similar

 

events that occur within the same session in a short period of time.

 

 

window

The length of time (in seconds) in which the n events must occur.

 

 

The following series of illustrations show how a Cluster tag works. After three events with the category authentication failure occur within the period of time defined by window, the Cluster tag matches for the period of time defined by linger.

Example: Cluster tag single event

Example: Cluster tag second event

HPE Security Fortify Runtime (17.3)

Page 15 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Example: Cluster tag third event

The MatchCluster tag refers to the state of a cluster and will match if the cluster matches, but unlike a Cluster tag, matching against MatchCluster will not change the state of the cluster. The following

MatchCluster tag refers to nextc.

Example: MatchCluster tag referring to nextc

<MatchCluster ref="nextc"/>

The example in the example below uses a combination of MatchAttribute, Cluster, and MatchCluster tags together to block login attempts for ten minutes after three failed login attempts in five minutes. Note that the events in this example are not generated by the default rule set.

Example: Combination of MatchAttribute, Cluster, and MatchCluster tags

<EventHandler propagate="true">

<Match> <!-- create clusters of failed logins around the failed user id -->

<MatchAttribute name="category">Authentication Failure</MatchAttribute>

<Cluster id="cluster2" n="3" window="300" linger="600" picture="%userid" maxClusters="100"/>

</Match>

<Handle/>

</EventHandler>

<EventHandler>

<Match> <!-- Before performing login, check to see if this user has already failed too often -->

<MatchAttribute name="category">Authentication Attempt</MatchAttribute>

<MatchCluster ref="cluster2"/> </Match>

HPE Security Fortify Runtime (17.3)

Page 16 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

<Handle>

<Action name="throw"/> </Handle>

</EventHandler>

Handling Events

The Handle section of an event handler specifies the operations to carry out when an event is matched. You can add to an event's list of attributes, write the event to the event log file, or communicate the event using the syslog protocol. You can also modify the behavior of the target program.

<Filter>

Filter allows an event handler to invoke a code module which can modify the event being processed. A filter can add, subtract, or modify event attributes or terminate the event. The Filter element specifies the type of filter to use with either an attribute named name or an attribute named class. If a filter declares a name, then the preferred way to use the filter is to reference it by its name using the name attribute. A filter that does not declare a name can be referenced by its fully qualified class name using the class attribute.

The example below shows an event handler that uses two filters in sequence to modify all events by adding the HTTP request being processed when the event occurred and by filling out the trigger attribute that explains the reason for the event.

Example: Filter

<EventHandler propagate="true" description="Standard event filters" label="Event filters">

<Match/>

<Handle>

<Filter name="AffixHttpRequest"/> <Filter name="ProcessTrigger"/>

</Handle>

</EventHandler>

A filter may accept settings, as shown in the following example.

Example: A Filter with Settings

<EventHandler propagate="true" description="Run my filter" label="My Filter">

<Match/>

<Handle>

HPE Security Fortify Runtime (17.3)

Page 17 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

<Filter name="MyFilter">

<Setting name=”remove”>.*</Setting> </Filter>

</Handle>

</EventHandler>

Fortify Runtime supplies some built-in filters as described in the following table, and users can create their own filters and include them in a Rulepack or a monitor library. See Writing Filter Classes for information about creating a custom filter.

Built-in Filters

Filter Name

Description

Settings

 

 

 

AffixHttpRequest

If an HTTP request is being processed by the thread

None

 

that created the event, this filter adds attributes that

 

 

describe the request. Attributes will be created for

 

 

HTTP parameters and headers, the request path, and

 

 

other information from the request.

 

 

 

 

AffixSource

Adds input source information to events when it is

None

 

available. Must be used in conjunction with a ruleset

 

 

that supports gathering of input source information,

 

 

such as the Fortify WebInspect Agent ruleset.

 

 

 

 

CalculatePriority

This filter will calculate Fortify Priority Order (FPO)

None

 

and will create an attribute named priority base on the

 

 

attribute values of impact, probability and accuracy.

 

 

 

 

MaskPersonalData

This filter can be used to remove sensitive data that

Each setting is

 

should not be recorded from event attributes.

interpreted as a

 

 

regular

 

 

expression. The

 

 

value of the

 

 

setting is used as

 

 

the replacement

 

 

value for any

 

 

attribute

 

 

substring

 

 

matched by the

 

 

regular

 

 

expression.

 

 

 

HPE Security Fortify Runtime (17.3)

Page 18 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Built-in Filters, continued

Filter Name

Description

Settings

 

 

 

MaskSessionId

This filter will mask out session ID from event

Mask: max

 

attributes. By default, only the first 16 characters of

number of

 

the session ID will be displayed.

unmasked

 

 

characters to be

 

 

displayed, default

 

 

value is 16

 

 

 

ProcessCEF

This filter will create an attribute named CEF.syslog

None

 

by packing attributes that start with “CEF.*” according

 

 

to HPE Security ArcSight Common Event Format

 

 

(CEF).

 

 

 

 

ProcessTriggerEx

If the monitor that created the event is configured with

None

 

a TriggerPicture property, this filter will create an

 

 

attribute named Trigger based on

 

 

TriggerPicture, making substitutions as

 

 

appropriate. This filter should appear after other filters

 

 

so that the Trigger attribute will include the final

 

 

values of other event attributes. For example,

 

 

ProcessTrigger should appear after

 

 

AffixHttpRequest so that the Trigger attribute

 

 

can include values from the HTTP request.

 

 

 

 

<Create Event>

CreateEvent allows an event handler to create a new event based on a set of attributes defined in a Rulepack. The new event will work its way through the event handler chain the same way all other events are processed. Any actions carried out as a result of processing the new event will be carried out

in the context of the call to CreateEvent. The CreateEvent element requires an attribute named attributeSet that specifies the ID of an <AttributeSet> defined in a Rulepack. CreateElement accepts two optional attributes:

inherit - specifies whether the created event should inherit attributes from the original event (defaults to true)

exclude - specifies a list of attributes that should not be inherited. It defaults to "RuleID,

MonitorID"

In order to prevent a poorly defined event handler chain from causing an infinite cascade of

CreateEvent invocations, each call to CreateEvent increments an event attribute named generation. If generation is greater than or equal to three, no further invocations of CreateEvent are allowed.

HPE Security Fortify Runtime (17.3)

Page 19 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

The following example creates an event based on an attribute set named stored_xss.

<CreateEvent attributeSet="stored_xss"/>

<SetAttribute>

The SetAttribute element requires a name attribute that specifies the name of the attribute to be added to the event. The body of the element is the value of the new attribute. The value can reference

event attributes by preceding them with a percent sign (%). You can overwrite existing event attributes. You can specify any number of SetAttribute tags.

SetAttribute supports an optional attribute named call_method. The value of call_method must refer to a method in the application or in the CLR with one of the following signatures:

public static String name()

public static String name(String value)

public static String name(HttpServletRequest req)

public static String name(HttpServletRequest req, String value)

The specified method will be invoked (with the current request and the value of the SetAttribute tag if the method accepts one or both of these arguments), and the value of the event attribute will be set to the value returned by the method.

The following example sets the category attribute to my vuln and adds an attribute named

vulnerability.

Example: SetAttribute

<SetAttribute name="category">my vuln</SetAttribute> <SetAttribute name="vulnerability"/>

<Dispatch>

The Dispatch element accepts a name attribute that specifies where the event is to be sent. You may specify any number of Dispatch elements. Valid names for Dispatch elements are log and syslog.

Dispatching to log sends the event to the event log file. Dispatching to syslog is much like dispatching to log, but the resulting message is sent out via the protocol rather than being written to the event log. syslog allows a setting named severity specifying the severity of the report. If used, the severity setting must have one of the following values: debug, info, notice, warning, error, critical,

alert, or emergency.

The example in the example below shows how the syslog element sends out emergency notifications.

Example: Syslog

<Dispatch name="syslog"><Setting name="severity">emergency</Setting></Dispatch>

HPE Security Fortify Runtime (17.3)

Page 20 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Note: The syslog protocol restricts messages to 65,500 bytes. If a picture results in a message longer than 65,500 bytes, the message will be truncated.

A Dispatch element can include a picture setting to control the way the event is recorded. The picture can reference event attributes by preceding them with a percent sign (%) as shown in the example below.

Example: Dispatch

<Dispatch name="syslog"><Setting name="picture">Detected a %category attack</Setting></Dispatch>

The above example format picture could produce the syslog message shown in the example below.

Example: Syslog message

Detected a my vuln attack

Note: The picture attribute can also be used with log dispatch, but using a picture other than the default will make it impossible to later convert the log file into an FPR file.

<Action>

An Action changes the target program. An event handler can specify any number of actions. An action can be parameterized using settings. For example, the Action shown in the example below

throws an exception of type system.Exception with the message Fortify Runtime rule (rule ID).

<Action name="throw">

<Setting name="type">System.Exception</Setting>

<Setting name="message">Fortify Runtime rule %ruleid</Setting> </Action>

The following table describes the supported actions and their settings.

Supported Actions

Action Name

Description

 

 

delay

Delay the execution of the current thread. Accepts optional length setting which

 

specifies the length of time to sleep in milliseconds (default: 3000ms)

 

 

die

Terminate the JVM. Accepts optional settings return (to specify the exit code for

 

the process) and message (as a final message to write to the system log.) No

 

additional actions can be executed after this one.

 

 

display

Ends the current operation by throwing an exception and notifies the user. Accepts

 

 

HPE Security Fortify Runtime (17.3)

Page 21 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Supported Actions, continued

Action Name

Description

 

 

 

optional settings status_code, forward, html, and text. These settings are

 

explained further below. No additional actions can be executed after this one.

 

 

ignore

Do nothing. Equivalent to no action at all.

 

 

invalidate_

If the current thread is servicing an HTTP request, this action terminates the session

session

of the user who made the request.

 

 

rewrite

Changes the value of a variable in the program. The variable and the changes must

 

be specified in the rule that triggers the action. Not all rules support rewrite. The

 

documentation supplied with HPE Security Fortify Rulepacks indicates the

 

categories that are compatible with rewrite.

 

 

throw

Throws an exception. Accepts optional settings type to specify the name of the

 

exception type to be thrown and message to specify the message the exception

 

should carry. No additional actions can be executed after this one. This action will

 

always throw an exception, even if an exception of the type specified cannot be

 

created.

 

 

display Action

The displayaction has four related global settings, all of which can be overridden by any of four optional settings on a specific display tag. The global settings for the display action are:

DisplayDefaultForwardPath, DisplayDefaultHtml, DisplayDefaultHttpStatusCode, and DisplayDefaultText. The settings for a specific display tag are status_code, forward, html,

and text.

If the active thread in the target program is not servicing a Web request at the time the display action is taken, the display action will throw a RuntimeException with a message taken from the local text setting (or the DisplayDefaultText global setting if there is no local text setting.)

In the context of a Web request, the precedence (from highest to lowest) and meaning of the display options are described in following table.

Display Setting Options

Option

Description

 

 

DisplayDefaultForwardPath

If this setting has a value, Fortify Runtime will transfer

global setting

processing of this HTTP request to the given path. Note that

 

this is NOT an HTTP redirect. All processing stays on the

 

server.

 

 

HPE Security Fortify Runtime (17.3)

Page 22 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Display Setting Options, continued

Option

Description

 

 

DisplayDefaultHtml global

If this option is set, Fortify Runtime will create an HTTP 200

setting

response and include this value as the body of the response.

 

 

DisplayDefaultHttpStatusCode

If this setting has a value greater than zero, the HTTP status

global setting

code of the response will be set to this value. If

 

DisplayDefaultText is not empty, it will be used as the

 

text of the response.

 

 

DisplayDefaultText global

If this option is set, Fortify Runtime will create an HTTP 200

setting

response and include this value as the body of the response.

 

 

forward local setting

If this setting has a value, Fortify Runtime will transfer

 

processing of this HTTP request to the given path. Note that

 

this is not an HTTP redirect. All processing stays on the

 

server.

 

 

html local setting

If this option is set, Fortify Runtime will create an HTTP 200

 

response and include this value as the body of the response.

 

 

status_code local setting

If this setting has a value greater than zero, the HTTP status

 

code of the response will be set to this value. If the text

 

option is set, it will be used as the text of the response.

 

 

text local setting

If this option is set, Fortify Runtime will create an HTTP 200

 

response and include this value as the body of the response.

 

 

Event Handler Scenarios

This section provides scenarios that include event handler capability. The format of the scenarios states a common business problem followed by the recommended solution. The scenarios in this section are:

Add a Custom Message for a 403 Error

Write Events to a Local Event Log File in Federated Mode

Preventing Sensitive Information from Being Recorded in Events

Running behind a Load Balancer

HPE Security Fortify Runtime (17.3)

Page 23 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Write Events to a Local Event Log File in Federated Mode

Problem

For creating new rules or debugging in Federated Mode, it can be handy to look at the raw event information being sent to the controller. This scenario addresses how to write events to the local

event.log.

Solution

There is a system-defined setting for enabling local event logging under System Defined Settings on the Logging tab.

Alternatively, you can write events to the local event log file by adding the line <Dispatch name="log"> to the same event handler that sends events to the controller. When this is finished, it looks like the results in the following example.

Example: Write events to local log

<!-- 3) send to controller -->

<EventHandler propagate="true" description="Send events to the controller" label="Event logger">

<Match/>

<Handle>

<Dispatch name="controller"/> <Dispatch name="log">

</Handle>

</EventHandler>

Preventing Sensitive Information from Being Recorded in Events

This scenario illustrates one way to prevent sensitive data from ending up in the event log or the controller. See the "Writing Filter Classes" on page 71 chapter for another approach.

Problem

If you log on to the Riches Bank application and drill down on an account, you will receive numerous Privacy Violation events. If you examine the event details, on the Request tab you will see the account number from the URL, similar to the following.

acctno: 5424000011112221

There is a way to prevent the Fortify Runtime operator from seeing this information.

HPE Security Fortify Runtime (17.3)

Page 24 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

Solution

Add an event handler that removes the sensitive information from the event using a <SetAttribute> tag. Imagine that for the Riches Bank application there are numerous web pages that include acctno as a request parameter. In order to remove the sensitive information from all events for all pages, add the following event handler to the beginning of the event handler chain.

Example: Event handler to remove sensitive information

<!-- 0) remove sensitive info from events -->

<EventHandler description=”Hide the accountno parameter in all events." label="Hide acctno" propagate="true" >

<Match>

<MatchAttribute name="request.parameters.acctno"/> </Match>

<Handle>

<SetAttribute name="request.parameters.acctno">(hidden by Runtime configuration)

</SetAttribute>

</Handle>

</EventHandler>

If you examine the account again, notice the details for a new privacy violation event. On the Request tab, observe acctno: (hidden by Fortify Runtime configuration).

Running Behind a Load Balancer

Problem

This scenario addresses a configuration whereby you may have multiple application servers behind a load balancer. When examining the details for an event, the IP address for the request is the IP address of the load balancer and not the IP address for the real user. There is a way to make the IP address show up as the IP address of the real user.

Solution

Add an event handler that sets the correct IP address using a <SetAttribute> tag. Most load balancers set an HTTP header named x-forwarded-for that gives the IP address of the original request. You can set the IP address of the request to be the value of this header by adding the following event handler to the event handler chain just after the event handler which includes the

AffixHttpRequest filter.

Example: Event handler that sets IP address

<!-- 0) set the IP address of the request (compensate for the load

HPE Security Fortify Runtime (17.3)

Page 25 of 85

.NET Edition Designer Guide

Chapter 3: Writing Event Handlers

balancer) -->

<EventHandler description="Set the IP address of the request if it has come

through a load balancer." label="Fix IP Address" propagate="true" > <Match>

<MatchAttribute name="request.headers.x-forwarded-for"/> </Match>

<Handle>

<SetAttribute name="request.ip">%{request.headers.x-forwarded- for}</SetAttribute>

</Handle>

</EventHandler>

HPE Security Fortify Runtime (17.3)

Page 26 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Chapter 4: Writing Rules

This section contains the following topics:

 

Introduction to Fortify Runtime Rules

27

Program Points

30

Monitor Specifications

38

Defining Abstract Monitor Specifications in Monitor Definitions

43

Attribute Sets

44

The Default Fortify Runtime Monitor Set

45

The Predicate Language

49

Rules Scenarios

52

Introduction to Fortify Runtime Rules

A Fortify Runtime rule:

Specifies how Fortify Runtime interacts with a target program

Specifies one or more program points

Specifies one or more monitors that connect to the rule’s program points

Provides a configuration for each specified monitor

Multiple Fortify Runtime Platform rules are packaged in a Rulepack.

Asample Rulepack is included in the Fortify Runtime SDK under the directory \sdk\samples. The subdirectories contain the individual Rulepacks which are named similar to my_rules.xml.

Overview of a Complete Fortify Runtime Rule

The following example illustrates a Rulepack that contains a single rule.

In the example rule, the built-in Fortify Runtime monitor ParameterMonitor examines HTTP parameters for input that may indicate a command injection attack; for example, the presence of the

character sequence cmd.exe.

If the ParameterMonitor monitor detects a suspicious parameter, then the monitor creates an event of category Probing: Command Injection; the event also contains value and action information.

Example: Example of a Fortify Runtime rule

<?xml version="1.0" encoding="UTF-8"?>

HPE Security Fortify Runtime (17.3)

Page 27 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<RulePack xmlns="xmlns://www.fortifysoftware.com/schema/runtime/rules" engineVersion="1.0">

<RulePackID>f101</RulePackID>

<SKU></SKU>

<Name>sample rulepack for Dotnet</Name> <Version>2010.1.0.0004</Version> <Language>dotnet</Language>

<Description><![CDATA[A sample Dotnet rulepack with a single rule in it.]]></Description>

<Rules>

<RuleDefinitions>

<Rule> <RuleID>d129e816-948d-SAMPLE-bed1-1bb993cf908a</RuleID> <ProgramPoints>

<ProgramPoint>

<Name>Parameters</Name>

<Capture/>

</ProgramPoint>

</ProgramPoints>

<Monitors>

<MonitorSpec class="Fortify.Runtime.Monitors.ParameterMonitor" monitorID="E4531ED3">

<Attributes>

<Attribute name="category">Probing: Command Injection</Attribute>

<Attribute name="suggestedAction">ignore</Attribute> </Attributes>

<Predicate>

values contains value: { value matches /(?i)(\/bin\/ (ba)?sh)|cmd\.exe/ }

</Predicate>

<Configuration>

<Property name="TriggerPicture">

<Value>name = %{name}, values = %{values}</Value> </Property>

</Configuration>

<Bindings>

<Binding name="name" capture-ref="name"/> <Binding name="values" capture-ref="values"/>

</Bindings>

</MonitorSpec>

</Monitors>

HPE Security Fortify Runtime (17.3)

Page 28 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

</Rule>

</RuleDefinitions>

</Rules>

</RulePack>

Overview of Fortify Runtime Rules

A Fortify Runtime Rulepack is an XML document that conforms to the Fortify Runtime schema specified

in \sdk\schema\rules.xsd.

In its simplest form, a Rulepack contains a preamble with information about the Rulepack followed by a list of rules.

More typically, a Fortify Runtime Rulepack contains multiple rules, many that share similar characteristics. In order to minimize the amount of duplication between rules, a rule writer can specify program points, monitors, and sets of attributes outside of a particular rule, then reference those definitions from any rule that requires those definitions.

The example below uses pseudo-XML to illustrate the general form of a Fortify Runtime rule.

Example: General form of a Fortify Runtime Rulepack

<RulePack>

…Rulepack header goes here… <RuleDefinitions/> <MonitorDefinitions/> <ProgramPointDefinitions/> <AttributeDefinitions/>

</RulePack>

Overview of the Fortify Runtime Rule Header

The following table lists Fortify Runtime Rulepack header elements.

Rulepack Header Elements

Name

Required

Description

 

 

 

Description

Yes

A longer explanation of the Rulepack contents for display purposes.

 

 

This element does not control any Fortify Runtime behavior.

 

 

 

Language

No

Indicates the language supported by this Rulepack. Fortify Runtime will

 

 

not load a Rulepack for the wrong language.

 

 

In other words, it is fine to include Rulepacks for multiple languages in a

 

 

single configuration. Fortify Runtime will ignore Rulepacks for other

 

 

 

HPE Security Fortify Runtime (17.3)

Page 29 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Rulepack Header Elements, continued

Name

Required

Description

 

 

 

 

 

languages.

 

 

 

Name

Yes

The display name of the Rulepack.

 

 

This element does not control any Fortify Runtime behavior.

 

 

 

RulePackID

Yes

A unique string that identifies the Rulepack. This element does not

 

 

control any Fortify Runtime Platform behavior.

 

 

 

SKU

Yes

A product identifier. This element does not control any Fortify Runtime

 

 

behavior.

 

 

 

Version

No

Use to differentiate revisions of a Rulepack. This element does not

 

 

control any Fortify Runtime behavior.

 

 

 

The Rulepack element accepts one optional attribute: engineVersion, which gives the minimum Fortify Runtime engine version required to run this Rulepack. If Fortify Runtime does not meet the minimum version required by the Rulepack, it will raise an error.

This Rulepack header in the example below specifies an engineVersion of 1.0, so it will work with all engine versions. This is equivalent to not specifying the engineVersion attribute at all. It specifies all of the required elements and the optional Version and Language elements too.

Example: Rulepack header

<RulePack xmlns="xmlns://www.fortifysoftware.com/schema/runtime/rules" engineVersion="1.0">

<RulePackID>f101</RulePackID>

<SKU></SKU>

<Name>sample rulepack for Dotnet</Name> <Version>2010.1.0.0004</Version> <Language>dotnet</Language> <Description>

<![CDATA[A sample Dotnet rulepack with a single rule in it.]]> </Description>

Program Points

The ProgramPoints section of a rule is a sequence containing one or more ProgramPoint elements. Each program point defines:

A method identifier or the name of a built-in program point (required)

A set of target program values to capture (required)

HPE Security Fortify Runtime (17.3)

Page 30 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

A set of attributes (optional)

Specifying Program Point Attributes

A program point can specify a set of program point attributes to be passed on to the monitor. This facility is useful primarily when declaring a program point outside of a rule in the

ProgramPointDefinitions section of the Rulepack. When used in this way, all rules that use the program point inherit the program point attributes. The program point shown in the example below uses a program point attribute to define the logging level associated with the method

log4net.ILog.Info(). A rule that uses this program point will automatically pass on the LogLevel Program Point attribute to its monitors.

Example: Program Point using an attribute

<ProgramPoint>

<Attributes>

<Attribute name="LogLevel">INFO</Attribute> </Attributes>

<Method>

<Class subclasses="true">log4net\.ILog</Class> <Name>Info</Name>

</Method>

<Capture>

<This id="logger"/>

<Argument id="input_text" index="0"/> </Capture>

</ProgramPoint>

In addition to specifying individual program point attributes, a program point can also make program

point attributes out of all of the attributes defined in an attribute set by using a SetReference tag as shown in the example below.

Example: Attribute set using a SetReference tag

<Attributes>

<SetReference id="LogAttrs"/> </Attributes>

Specifying the Program Location in a Program Point

There are three ways to specify points in the target program in a Program Point element. Every program point must supply one and only one of the following:

An identifier for a method

An identifier for an object initializer

The name of a built-in program point

HPE Security Fortify Runtime (17.3)

Page 31 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Specifying a Method Identifier

A method identifier supplies the class name (including the package name), the name of the method, and (optionally) the return type and parameter types for the method. Element values are interpreted as regular expressions, so it is easy to refer to groups of methods with similar characteristics, but periods and other special characters must be escaped with a backslash to avoid giving them special meaning.

Method Identifier Values

Constraint

Number

Negatable

Description

 

 

 

 

Class

1 or more

Yes

Matches the name of the class in which the

 

 

 

method is defined. Setting the attribute

 

 

 

subclasses on the Class element to true causes

 

 

 

the method identifier to match against any

 

 

 

subclass of the named Class or implementation

 

 

 

of the named interface.

 

 

 

 

ClassMarker

0 or more

Yes

Matches annotations placed on the class in which

 

 

 

the method is defined.

 

 

 

 

Flag

0 or more

Yes

Matches against method flags, such as public,

 

 

 

static or final.

 

 

 

 

Marker

0 or more

Yes

Matches annotations placed on the method.

 

 

 

 

Name

1 or more

Yes

Matches the name of the method.

 

 

 

 

Parameters

0 or 1

No

Matches against the signature (declared

 

 

 

parameters) of the method.

 

 

 

 

ReturnType

0 or 1

No

Matches the method return type.

 

 

 

 

 

 

 

The preceding table lists the method identifier constraints. Constraints marked as “Negatable” in the

table can have their meaning inverted by setting the negate attribute to true, as demonstrated in the figure below.

The Method example in the example below matches any implementation of the warn method belonging to the org.apache.log4j.Category class or any of its subclasses.

Example: Method identifier matching implementation of the warn method

<Method>

<Class subclasses="true">log4net\.ILog</Class> <Name>Warn</Name>

HPE Security Fortify Runtime (17.3)

Page 32 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

</Method>

The method identifier shown in the below figure matches all methods named ChangePassword that belong to a class inheriting the System.Web.Security.MembershipProvider class. In order to match, a method must accept three parameters of type System.String and return a bool.

Example: Method identifier with two parameters

<Method>

<Class

subclasses="true">System\.Web\.Security\.MembershipProvider</Class>

<Name>ChangePassword</Name> <ReturnType type="bool"/> <Parameters>

<ParameterType type="System\.String"/> <ParameterType type="System\.String"/> <ParameterType type="System\.String"/>

</Parameters>

</Method>

As with other constraints, ParameterType is treated as a regular expression, so be sure to use the correct escaping, especially when matching on array types (System.String[] becomes

System\.String\[\]).

The next method identifier shown in the figure below matches methods named Assert of System.Diagnostics.Debug class. In order to match, the first argument of a method must be of the type bool. Because the method identifier includes the tag Ellipsis after the first parameter type, it will match against methods that accept only one argument or methods that take any number of additional arguments with arbitrary types.

Example: Method identifier with matching methods

<Method>

<Class

subclasses="true">System\.Diagnostics\.Debug</Class>

<Name>Assert</Name>

<Parameters> <ParameterType type="bool"/> <Ellipsis/>

</Parameters>

</Method>

The final Method example shown in the figure below matches any public, non-static method in any

subclass of System.Web.Services.WebService that has a System.Web.Services.WebMethodAttribute attribute.

Example: Method identifier matching any public, non-static method

HPE Security Fortify Runtime (17.3)

Page 33 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<Method>

<Class subclasses="true">System\.Web\.Services\.WebService</Class> <Name>.*</Name> <Marker><Name>System\.Web\.Services\.WebMethodAttribute</Name></Marker> <Flag>public</Flag>

<Flag negate="true">static</Flag> </Method>

Specifying a Built-in Program Point

Fortify Runtime supplies named built-in program points for placing monitors in popular locations or for special purposes. Named program points restrict the behavior of a monitor; the only monitor control point that will be invoked is complete, and the monitor is not allowed to modify program values. A monitor is allowed to throw an exception from a named program point. The names of captured values are an implicit part of a named program point. The following table indicates the named program point that is supported.

Example: Supported named program point

Name

Description

Captured Value

 

 

 

Parameters

Fires the first time a new parameter is read

name: the name of the parameter, and

 

for a given request.

values: the values of the parameter

 

 

 

The program point in the example below uses the Parameters named ProgramPoint.

Example: Named program point

<ProgramPoints>

<ProgramPoint>

<Name>Parameters</Name>

<Capture/>

</ProgramPoint>

</ProgramPoints>

Capturing Values in a Program Point

Fortify Runtime can capture (and in some cases modify) values from the target program. A program point can specify three kinds of values to be captured:

A method's return value

The object invoking the method (the value of this)

Method arguments individually or as a range of arguments

Regardless of the capture type, every capture must specify an attribute named id.

HPE Security Fortify Runtime (17.3)

Page 34 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

The id attribute names the captured value so that it can be wired up to a monitor later in the rule. If multiple capture elements share the same id, the values will be combined into an array before being passed to the monitor.

The program point shown in the figure below uses three capture types to examine calls to Double.toString(). It captures the return value of the method and names it value. It names the object object, and it captures the first argument to the method (index 0) and names it format.

Example: Program point capturing a value

<ProgramPoint>

<Method>

<Class subclasses="true">System\.Double</Class> <Name>ToString</Name>

</Method>

<Capture>

<Return id="value"/> <This id="object"/>

<Argument id="format" index="0"/> </Capture>

</ProgramPoint>

In some scenarios it is useful to capture a variable number of values from the target program. This may make it easier to use general purpose monitors in a variety of situations. The figure below shows a program point that captures values from a set of overloaded WriteLine methods of the System.Console class.

public static void WriteLine(string format, Object o1);

public static void WriteLine(string format, Object o1, Object o2);

public static void WriteLine(string format, Object o1, Object o2, Object o3);

In this example, the number of values captured to the capture id “parts” depends on the method in

question. The values will be provided to the monitor as an array (Object[]), allowing a single monitor implementation to examine all arguments to the methods of the different arity.

Example: Program point capturing several values to the same id

<ProgramPoint>

<Method>

<Class subclasses="true">System\.Console</Class> <Name>WriteLine</Name>

</Method>

<Capture>

<Argument id="format" index="0"/> <Range id="parts" first="1"/>

HPE Security Fortify Runtime (17.3)

Page 35 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

</Capture>

</ProgramPoint>

The Range element functions by capturing multiple arguments starting at the index specified by the attribute first. An optional attribute last may be specified to indicate where the argument range should end. By default, the range extends to the end of the argument list. The last attribute may be specified using a positive number (offset from the start of the argument list beginning at 0) or a negative number (offset from the end of the argument list where -1 represents the last argument). Both first and last are inclusive.

The values a program point captures affect when the Complete control point can be executed. If a program point captures a method's return value, then Complete cannot execute until the method is ready to return. If a program point does not capture a method's return value, then Complete can execute before the method runs.

All of the program points used by a rule must name the set of capture ids required by the bindings in the monitors for that rule. It is not an error for a monitor to bind to a capture id which is not provided by the program point, but if it does the value of that binding will always be null. In general, any set of program points that are intended to be used together should expose the same set of capture ids.

Defining a Program Point Outside a Rule

Program points can be defined as part of a rule, as the example below shows. Program points can also be defined in the ProgramPointDefinitions section of a Rulepack. The format for program points is the same in both cases, but when program points are defined in ProgramPointDefinitions, they must appear under a ProgramPointSet element that carries an id attribute so that rules can refer to the set.

The example in the following example illustrates a rule that references a Program Point set named

log4jPPSet0 followed by the definition of that program point set. The set contains two program points.

Example: Rule that references a Program Point

<RuleDefinitions>

<Rule> <RuleID>60485088-3895-46c1-a766-4a032492c5b2</RuleID> <ProgramPoints>

<SetReference id="log4netPPSet0"/> </ProgramPoints>

<Monitors>

…monitor definitions go here… </Monitors>

</Rule>

</RuleDefinitions>

HPE Security Fortify Runtime (17.3)

Page 36 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<ProgramPointDefinitions> <ProgramPointSet id="log4netPPSet0">

<ProgramPoint>

<Attributes>

<Attribute name="LogLevel">FATAL</Attribute> </Attributes>

<Method>

<Class subclasses="true">log4net\.ILog</Class> <Name>Fatal</Name>

</Method>

<Capture>

<This id="logger"/>

<Argument id="input_text" index="0"/> </Capture>

</ProgramPoint>

<ProgramPoint>

<Attributes>

<Attribute name="LogLevel">ERROR</Attribute> </Attributes>

<Method>

<Class subclasses="true">log4net\.ILog</Class> <Name>Error</Name>

</Method>

<Capture>

<This id="logger"/>

<Argument id="input_text" index="0"/> </Capture>

</ProgramPoint>

</ProgramPointSet>

</ProgramPointDefinitions>

Overlapping Program Points

A single rule may contain multiple program points which match the same method in the target program. In this case, the behavior at Fortify Runtime depends on the Capture declaration in each program point. If the overlapping program points declare the same Capture, each monitor from the rule will be executed only once. If not, each monitor will be executed once for each unique Capture declaration from the set of matching program points.

HPE Security Fortify Runtime (17.3)

Page 37 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Monitor Specifications

A rule is responsible for declaring one or more Monitor specifications. A Monitor specification names a Monitor class and connects it to the target program through the rule's program points.

Timer Monitor Example

The following Monitor specification shown in the figure below uses the Monitor class

Fortify.Runtime.Monitors.TimerMonitor to watch for database methods that take a long time to return.

Example: Monitor with Timer

<Monitors>

<MonitorSpec class="Fortify.Runtime.Monitors.TimerMonitor" reentrant="false" monitorID="8069F9C2-A583-4F4B-89CD-

BF9E7C6AF227">

<Attributes>

<Attribute

name="category">Slow Method Call: Slow Database Connection</Attribute>

<Attribute name="suggestedAction">ignore</Attribute> <SetReference id="slowMethodCallAttrs"/>

</Attributes>

<Configuration>

<Property name="Threshold"> <Value>10000</Value>

</Property>

</Configuration>

<Bindings/>

</MonitorSpec>

</Monitors>

The MonitorSpec Element

The MonitorSpec element accepts 4 attributes: class, monitorID, reentrant and reentrySetID, as described in the following table.

HPE Security Fortify Runtime (17.3)

Page 38 of 85

Example: MonitorSpec
<MonitorSpec class="com.fortify.runtime.monitor.Timer" reentrant="false" monitorID="8069F9C2-A583-4F4B-89CD-BF9E7C6AF227">
A583-4F4B-89CD-BF9E7C6AF227

.NET Edition Designer Guide

Chapter 4: Writing Rules

MonitorSpec Element Attributes

Name

Required

Description

 

 

 

class

Yes

The fully qualified name of the monitor class.

 

 

 

monitorID

Yes

A globally unique ID for identifying the monitor in events and log

 

 

messages.

 

 

 

reentrant

No

A Boolean that determines if a monitor will be invoked if a method in

 

 

its reentrySet is already on the call stack. (See reentrySetID for

 

 

more details.) Defaults to true.

 

 

 

reentrySetID

No

If the reentrant attribute is set to false, this value names the set of

 

 

monitors that will be mutually non-reentrant with this monitor. In

 

 

other words, only one monitor instance from this set can be on the call

 

 

stack at any given time. Further monitors from the same set will be

 

 

skipped until the first monitor is popped from the stack. If reentrant

 

 

is true, this attribute is ignored. Defaults to the value of the

 

 

monitorID attribute. More than one value may be specified,

 

 

separated by commas.

 

 

 

The following monitor specification in the example below uses the monitor class com.fortify.runtime.monitor.Timer. The rule this monitor comes from is written to handle database driver implementations where a method such as Statement.executeQuery() delegates to an internally managed object that implements the same interface. In other words, one Statement.executeQuery() might well call another Statement.executeQuery(). In order to avoid creating duplicate events in this situation, the monitor sets reentrant="false". The specification does not set the reentrySetID attribute, so reentrySetID defaults to 8069F9C2-

(the same value as the monitorID attribute).

Monitor Attributes

Monitor specifications can optionally declare a set of monitor attributes to be reported in any event the Monitor might generate. Monitor attribute declarations work just like program point attributes. Monitor attributes can be declared one at a time or imported as a group from an attribute set. These attributes will appear in any event generated by the Monitor.

Example: Attribute declaration

<Attributes>

HPE Security Fortify Runtime (17.3)

Page 39 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<Attribute name="category">Slow Method Call: Slow Database Connection</Attribute>

<Attribute name="suggestedAction">ignore</Attribute> <SetReference id="slowMethodCallAttrs"/>

</Attributes>

A special noLocation attribute may be specified to prevent events generated by the monitor from containing stack traces. Collecting stack traces incurs a performance penalty, so disabling that behavior could speed up monitor execution.

Example: noLocation attribute declaration

<Attributes>

<Attribute name="noLocation"/> </Attributes>

Predicate

A popular reason to write a rule is to flag method calls that have particular argument values or that occur in specific contexts. In order to make these rules easy to write without having to create a specialized monitor for each rule, a rule can optionally specify a predicate that must be satisfied before the monitor is invoked. A predicate is evaluated once before the invocation of the method specified by the program point. (The time of predicate evaluation is independent of the control points the monitor watches). If the predicate evaluates to false, none of the monitor's control point methods are invoked. The monitor is effectively canceled.

Predicate syntax is described in the "The Predicate Language" on page 49 section. The following examples demonstrate typical uses for predicates.

Invoke the monitor if the captured value named Input is one of seven numbers as shown in the following example.

Example: Captured value named input

<Predicate>

Input matches /400|403|404|413|414|415|416/ </Predicate>

Invoke the Monitor if captured value named name is jsessionid (case insensitive) as shown in the following example.

Example: Captured value named “name”

<Predicate>

name matches /(?i)jsessionid/ </Predicate>

Do not invoke this Monitor in the context of a web request as shown in the following example.

HPE Security Fortify Runtime (17.3)

Page 40 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Example: Web request

<Predicate> not Request

</Predicate>

Invoke the Monitor if the Monitor library method IsWebOutput returns true for the captured value out as shown in the following example.

Example: Captured value “out”

<Predicate>

IsWebOutput(out)

</Predicate>

Invoke the monitor if the captured array values contain an element that matches the regular expression as shown in the following example.

Example: Captured array values

<Predicate>

values contains value: { value matches /(?i)(\/bin\/(ba)?sh)|cmd\.exe/ } </Predicate>

Configuration

Some Monitors have configurable properties that allow the same Monitor to be used for different purposes by different rules. For example, a rule writer might want to use the timer monitor (com.fortify.runtime.monitor.Timer) for two rules to flag long-running database queries.

Rule 1: flag queries that take longer than 2 second when the database is used in the context of a Web request.

Rule 2: flag queries that take longer than 10 seconds in the context of a batch processing job.

The timer's Threshold property allows different rules to use the same Monitor in different ways, as the following rule excerpts demonstrate.

Example: General construction of a rule that uses the Timer Monitor

<Rule>

<RuleID>Rule1</RuleID>

...

<Configuration>

<Property name="Threshold"> <Value>2000</Value>

</Property>

</Configuration>

HPE Security Fortify Runtime (17.3)

Page 41 of 85

Category, Assertvar, and ObjInput.

.NET Edition Designer Guide

Chapter 4: Writing Rules

...

</Rule>

<Rule>

<RuleID>Rule2</RuleID>

...

<Configuration>

<Property name="Threshold"> <Value>10000</Value>

</Property>

</Configuration>

...

</Rule>

The properties supported by built-in Monitors are described in the "The Default Fortify Runtime Monitor Set" on page 45 section. It is an error to provide an unsupported property to a Monitor as part of a rule.

Bindings

The bindings section connects the values captured in a Program Point to a Monitor's inputs. The

bindings section comprises of zero or more Binding elements. Each Binding element must supply two attributes:

name: the name of the Monitor input.

capture-ref: the id of the capture element declared in the program point.

The Bindings section of a Monitor declaration works closely with the Capture section in the program point. The following excerpts from a rule take three values from the target program in the Capture section: the object (given id=”logger”), the first method argument (given id=”assert_var”), and the second method argument (given id=”input_text”). In the Bindings section of the rule these three values are bound to the Monitor inputs

Example:Bindings

<Capture>

<This id="logger"/>

<Argument id="assert_var" index="0"/> <Argument id="input_text" index="1"/>

</Capture>

...

<Bindings>

<Binding name="Category" capture-ref="logger"/> <Binding name="Assertvar" capture-ref="assert_var"/> <Binding name="ObjInput" capture-ref="input_text"/>

HPE Security Fortify Runtime (17.3)

Page 42 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

</Bindings>

It is possible to bind more than one capture element to a single Monitor input field by having multiple Binding entries with the same value for name. In this case, all captured values will be assembled into an array (Object[]) before being passed to the Monitor.

Defining Abstract Monitor Specifications in Monitor Definitions

You can create abstract Monitor specifications in the MonitorDefinitions section of the Rulepack, and then use the abstract specifications inside rules. An abstract Monitor specification is similar in

appearance to a regular Monitor specification in a rule except that it requires an id attribute and does not accept the monitorID attribute or the reentrySetID attribute.

The following abstract Monitor specification is set up to look for social security numbers and replace the first 5 digits with XXX-XX.

Example: Abstract monitor

<MonitorDefinitions>

<AbstractMonitorSpec reentrant="false" id="PV_SSN"> <Predicate>

outputEnabled and

Input matches /(?<!\d|-)\d\d\d-\d\d-\d\d\d\d(?!\d|-)/ </Predicate>

<Configuration>

<Property name="ReplaceRegexMap"> <Map>

<Entry> <Key>(\d\d\d-\d\d-)(\d\d\d\d)</Key> <Value>XXX-XX-$2</Value>

</Entry>

</Map>

</Property>

</Configuration>

<Bindings/>

</AbstractMonitorSpec>

</MonitorDefinitions>

You can use an abstract Monitor specification with the Extension element in place of the Monitor element inside a rule. The Extension element has two required attributes:

base: the id of the abstract Monitor specification to use

monitorID: the Monitor ID for this Monitor specification

HPE Security Fortify Runtime (17.3)

Page 43 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

An ExtensionSpec element accepts all of the same sub-elements and attributes accepted by a MonitorSpec element. Any declarations in an ExtensionSpec element are added to the declarations in the abstract Monitor specification.

The following rule in the following example uses the abstract Monitor specification declared above.

Example: Rule using abstract Monitor specification

<Rule>

…rule header goes here… <Monitors>

<Extension

class="com.fortify.runtime.monitor.OrgApacheLog4jGuard" base="PV_SSN" monitorID="65AEFB5B-5BC9-438E-BE11-A00C450A56B2">

<Attributes>

<Attribute name="category">Privacy: Social Security Number</Attribute>

<Attribute name="suggestedAction">rewrite</Attribute> <SetReference id="privacyViolationSSNAttrs"/>

</Attributes>

<Bindings>

<Binding name="ObjInput" capture-ref="input_text"/> <Binding name="Priority" capture-ref="priority"/> <Binding name="Category" capture-ref="logger"/>

</Bindings>

</Extension>

</Monitors>

</Rule>

Attribute Sets

Similar rules often use similar sets of attributes. To avoid a great deal of repetition between groups of attributes declared in similar rules, you can create attribute sets in the AttributeDefinitions section of the Rulepack, then use a SetReference tag to import the attributes as Program Point attributes or monitor attributes.

Example: Attribute Set declaration

<AttributeDefinitions>

<AttributeSet id="privacyViolationCCNAttrs"> <Attribute name="kingdom">Security Features</Attribute> <Attribute

name="description">/privacy_ violation.htm?version=2009.4.0.0016</Attribute>

HPE Security Fortify Runtime (17.3)

Page 44 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<Attribute name="eventType">vulnerability,audit</Attribute> <Attribute name="probability">5</Attribute>

<Attribute name="accuracy">4</Attribute> <Attribute name="impact">3</Attribute>

<Attribute name="impactBias">confidentiality</Attribute> <Attribute name="audience">broad,dev</Attribute> <Attribute name="primaryAudience">security</Attribute> <Attribute name="coveredSCA">no</Attribute>

</AttributeSet>

</AttributeDefinitions>

The Default Fortify Runtime Monitor Set

Fortify Runtime includes three built-in monitors:

The Fortify Runtime Guard monitor type

The Fortify Runtime ParameterMonitor monitor type

The Fortify Runtime Timer monitor type

The Fortify Runtime Guard Monitor Type

The Fortify Runtime monitor class com.fortify.runtime.monitor.Guard creates an event when it is triggered. Most rules that use Guard create a predicate to determine the conditions under which an event should be created. Guard is able to rewrite its input. "Guard Monitor Inputs" below table lists guard monitor inputs, while "Guard Monitor Properties" below table lists guard monitor properties.

Guard Monitor Inputs

Name

Type

Description

 

 

 

Input

Object

The single input value captured from the

 

 

target program.

 

 

 

Guard Monitor Properties

Name

Type

Description

 

 

 

ReplaceRegexMap

Map<Regex,String>

If this property is specified, the regular expressions in

 

 

this map will be applied to input in the order they are

 

 

declared. All substrings that match each regular

 

 

expression will be replaced with the string paired with

 

 

the regular expression.

 

 

 

HPE Security Fortify Runtime (17.3)

Page 45 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Guard Monitor Properties, continued

Name

Type

Description

 

 

 

TriggerPicture

String

A template string which will be used to create an event

 

 

attribute called Trigger, if set. Variables can be

 

 

specified as %var or %{var}. Variables may refer to

 

 

Monitor bindings, event attributes, or Monitor

 

 

properties.

 

 

 

The following Monitor declaration uses Guard to mix up strings that include the substring dog. If the input matches dog, then Guard will create an event. Included in the event will be an attribute named trigger with the value of the input. If the rewrite action is triggered on the event, each of the letters d, o, and g will be replaced with a number. Note the syntax for specifying a map as a Monitor property.

A Monitor that uses Guard follows in the following example.

Example: Guard monitor

</ProgramPoints>

<Monitors>

<MonitorSpec class="com.fortify.runtime.monitor.Guard" monitorID="m1"> <Attributes>

<Attribute name="category">Don't Say SQL</Attribute> </Attributes>

<Predicate><![CDATA[ Input matches /.*dog.*/ ]]></Predicate> <Configuration>

<Property name="ReplaceRegexMap"> <Map>

<Entry><Key>d</Key><Value>1</Value></Entry>

<Entry><Key>o</Key><Value>2</Value></Entry>

<Entry><Key>g</Key><Value>3</Value></Entry>

</Map>

</Property>

</Configuration>

<Bindings>

<Binding name="Input" capture-ref="x"/> </Bindings>

</MonitorSpec>

The Fortify Runtime ParameterMonitor Monitor Type

The Monitor class com.fortify.runtime.containersupport.ParameterMonitor provides an easy way to use the named program point parameter to examine HTTP request parameters. The

HPE Security Fortify Runtime (17.3)

Page 46 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

"ParameterMonitor Inputs" below table lists ParameterMonitor inputs, while the "ParameterMonitor Monitor Properties" below lists ParameterMonitor monitor properties.

ParameterMonitor Inputs

Name

 

Type

Description

 

 

 

 

 

name

 

String

The name of the HTTP request parameter.

 

 

 

 

 

values

 

String[]

The values of the HTTP request parameter.

 

 

 

 

 

ParameterMonitor Monitor Properties

 

 

 

 

 

 

Name

Type

 

Description

 

 

 

 

TriggerPicture

String

 

A template string which will be used to create an event

 

 

 

 

attribute called Trigger, if set. Variables can be

 

 

 

 

specified as %var or %{var}. Variables may refer to

 

 

 

 

Monitor bindings, event attributes, or Monitor

 

 

 

 

properties

 

 

 

 

 

This Monitor is from the rule given at the beginning of this document. It uses the Parameter named program point to look for command injection attacks.

The following example shows a monitor that uses ParameterMonitor.

Example: ParameterMonitor monitor

<MonitorSpec class="com.fortify.runtime.containersupport.ParameterMonitor" monitorID="E4531ED3">

<Attributes>

<Attribute name="category">Probing: Command Injection</Attribute> <Attribute name="triggerHint">name, values</Attribute> <Attribute name="suggestedAction">ignore</Attribute>

</Attributes>

<Predicate>

values contains value: { value matches /(?i)(\/bin\/ (ba)?sh)|cmd\.exe/ }

</Predicate>

<Bindings>

<Binding name="name" capture-ref="name"/> <Binding name="values" capture-ref="values"/>

</Bindings>

</MonitorSpec>

HPE Security Fortify Runtime (17.3)

Page 47 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

The Fortify Runtime Timer Monitor Type

The Monitor class com.fortify.runtime.monitor.Timer reports method calls that take a long time to execute.

Timer takes no inputs.

The following table lists timer properties.

Timer Properties

Name

Type

Description

 

 

 

Threshold

int

The minimum amount of time (given in milliseconds) a method must

 

 

execute before Timer will generate an event upon method

 

 

completion. This property is passed through the configuration

 

 

variable interpreter before it is used, so the rule writer can provide

 

 

values such as %MyConfigVar and the threshold for a rule set in the

 

 

configuration file.

 

 

 

TriggerPicture

String

A template string which will be used to create an event attribute

 

 

called Trigger, if set. Variables can be specified as %var or %{var}.

 

 

Variables may refer to Monitor bindings, event attributes, Monitor

 

 

properties, or the special value threshold, which contains the current

 

 

threshold setting. The default value is "Method call took longer than

 

 

%{time} milliseconds, which exceeds current threshold of %

 

 

{threshold} milliseconds."

 

 

 

The following example illustrates a Runtime Monitor of class Timer.

Example: A MonitorSpec that uses Timer

<MonitorSpec class="com.fortify.runtime.monitor.Timer" reentrant="false" monitorID="8069F9C2-A583-4F4B-89CD-BF9E7C6AF227"> <Attributes>

<Attribute name="category">Slow Method Call: Slow Database Connection</Attribute>

<Attribute name="suggestedAction">ignore</Attribute> <SetReference id="slowMethodCallAttrs"/>

</Attributes>

<Configuration>

<Property name="Threshold"> <Value>${DatabaseConnectionTimeThreshold}</Value>

</Property>

HPE Security Fortify Runtime (17.3)

Page 48 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

<Property name="TriggerAttributeName"> <Value>Trigger</Value>

</Property>

</Configuration>

<Bindings/>

</MonitorSpec>

The Predicate Language

The predicate language gives rule writers easy access to values captured by a rule and functions defined in monitor libraries. It is a simple language. There are no explicit constructs for modifying control flow, no variable declarations (except for iterating over collections), and no user-defined functions or types.

Syntax

The syntax for the predicate language is given in the following example.

Example: BNF Syntax for the Predicate Language

pred ::= pred and pred | pred or pred | not pred |

expr contains Name ‘:’ ‘{’ pred ‘}’ | expr matches Regex |

‘(’ pred ‘)’ | exp

exp ::= var | call | String | Integer

var ::= Name |

Name ‘.’ Name | Name‘[’ String ‘]’

call ::= Name ‘(’ { arglist } ‘)’

arglist ::= { exp ‘,’ } exp

A String is a sequence of characters surrounded by quotation marks ("this is a string").

HPE Security Fortify Runtime (17.3)

Page 49 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

A Name (used for naming variables, fields and functions) is a sequence of one or more letters, numbers, and ampersands. Names are case-insensitive, so the expressions Request.Path and request.path are equivalent.

A Regex is a .NET regular expression surrounded by slashes, such as/[a-zA-Z][a-zA-Z0-9]*/.

An Integer is a positive or negative integer.

Predicates are evaluated from left to right. All predicate operators are short-circuit operators. In other words, a predicate will be evaluated until its value can be determined at which point evaluation will cease. Given the predicate A or B, if A evaluates to true, then B will not be evaluated.

Predicate operator precedence from highest to lowest is not, and, or.

The contains operator iterates over a collection and evaluates to true if the inner predicate evaluates to true for one of the members of the collection. If contains is used with a map, it will iterate over the map values and ignore the map keys.

The matches operator interprets its expression as a string and returns true if its regular expression matches the string. Note that the regular expression need not match the entire string; to match an

entire string, include anchors in the regular expression (for example, /^test$/).

The expressions o.x and o["x"] are equivalent.

Types

Expressions can be one of three types: Boolean, integer or reference. An expression used as a predicate evaluates to true if it has the Boolean value true, if it is an integer (of any value), or if it is a non-null reference. For example, the variable Request will be null if no HTTP request is available, so the predicate not Request creates a rule that will only fire outside the context of a web request.

Example: Using an expression as a Predicate

<Predicate> not Request </Predicate>

A reference expression can be null or can refer to an object. The built-in reference types are String and the collection types List, Map and MultiMap.

It is illegal to use the matches operator with any expression type other than a reference to a string. The contains operator must be used with an expression with a collection type. It is only legal to access fields or indices of a reference expression.

Taking a field or index of a null reference results in a null reference. Accessing a field or index that does not exist results in a null reference.

For a reference to a Map or MultiMap, a special field named @Keys returns a collection containing the keys used in the map.

A predicate that performs an illegal operation evaluates to false.

HPE Security Fortify Runtime (17.3)

Page 50 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Variables

Predicates may use monitor bindings as variables. In the following example, the predicate uses the binding out to check to see if an output stream is writing to an HTTP response.

Example: Using a Monitor Binding as a Predicate Variable

<MonitorSpec class="com.fortify.runtime.monitor.Guard" reentrant="false"

monitorID="MB0D">

<Attributes/>

<Predicate>

IsWebOutput(out)

</Predicate>

<Configuration/>

<Bindings>

<Binding name="out" capture-ref="captured_out"/> </Bindings>

</MonitorSpec>

A Special Variable: Request

The special variable Request refers to the current HTTP request or is null if no request is currently being processed by the thread that triggered the rule. Request fields are described in the following table.

Variable Fields for Request Variable

Name

Type

Description

 

 

 

Cookies

ICollection

A map of all of the cookies sent with the request.

 

 

 

Headers

ICollection

A map of all of the headers sent with the request.

 

 

 

Host

string

The host name of the interface on which the request was

 

 

received.

 

 

 

Method

string

The HTTP method of the request (GET, POST, etc.).

 

 

 

Parameters

ICollection

All of the parameters read by the program thus-far. If the

 

 

program has not yet requested a parameter, it does not

 

 

appear in this map.

 

 

 

Path

string

The path component of the request URL.

 

 

 

HPE Security Fortify Runtime (17.3)

Page 51 of 85

.NET Edition Designer Guide

Chapter 4: Writing Rules

Variable Fields for Request Variable, continued

Name

Type

Description

 

 

 

Port

string

The network port on which the request was received.

 

 

 

QueryString

string

The complete query string for the request.

 

 

 

RemoteAddress

string

The IP address of the remote user.

 

 

 

RemoteUser

string

The name of the remote user as represented in the

 

 

request.

 

 

 

Scheme

string

The scheme components of the request URL (http,

 

 

https, etc.)

 

 

 

Session

ICollection

A map representing the contents of the HTTP Session

 

 

object.

 

 

 

SessionId

string

The session identifier.

 

 

 

Rules Scenarios

This section provides scenarios that include Rules capability. The format of the scenarios states a common business problem followed by the recommended solution. The scenarios in this section are:

Viewing and Changing HPE Security Fortify Rules

Making a Whitelist Rule

Capturing a Boolean

Viewing and Changing HPE Security Fortify Rules

Problem

The default behavior you get with Fortify Runtime Rulepack is almost what you want, but not quite. You would like to understand how the rule works and maybe edit it a little bit, but the RPR file isn't humanly readable.

Solution

A lot of problems that are specific to a particular program or environment can be remedied with event handlers or other configuration settings, but sometimes writing rules is the only way to go. HPE Security Fortify does not include the XML of its rules with Fortify Runtime distribution because most customers don't require it, but we will provide the XML on an as-needed basis. Customers can then understand our rules in more detail and create their own custom rules based on ours.

HPE Security Fortify Runtime (17.3)

Page 52 of 85