Contents: Overview Planning The Adapter Building The Adapter Installing and Configuring The Adapter Testing and Troubleshooting Updating The Adapter Resources About the authors Rate this article Related content: Related article title Related article title Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Gary Lord, Information Developer, IBM Tivoli Integration Factory
Adam Richards, Developer, IBM Tivoli Integration Factory

06 Jul 2004
Updated 6 Jul 2004

This article provides walk-through instructions to help you build, install and configure a new IBM® Tivoli™ Risk Manager 4.2 adapter. This will allow you to integrate Tivoli Risk Manager with an existing sensor product, thereby centralizing visibility and control of security-related incidents. The key to this process is the creation of a format file, with code that maps security-related events from your third-party sensor into recognizable Tivoli Risk Manager event classes and categories. The article also covers Tivoli Risk Manager concepts and resources, important design considerations and alternatives, plus modification of existing adapters.

Overview
This section introduces the scenario and describes important considerations, resources and prerequisites.

Who Should Read This Article
This article is designed to help any IBM Tivoli customers who wish to integrate an existing sensor product with Tivoli Risk Manager version 4.2. Because it explains in detail the mappings within the adapter files, it should also be of considerable interest to any existing Tivoli Risk Manager customers who wish to better understand their adapter's functionality, or customers wanting to update the functionality of an existing adapter (e.g. for a new sensor upgrade).

Before You Start
To properly build, install and test an adapter as described in this article, both Tivoli Risk Manager 4.2 and the third-party sensor software must be installed, configured and running without errors on your network. This article uses the convention RMINSTDIR to refer to the directory where Tivoli Risk Manager is installed.

The Tivoli Risk Manager client should be installed on the same host system as the event source to be monitored. The exception to this is when monitoring a JDBC Database table, in which case the JDBC data source may be remote from the client. You must install the JDBC driver for the database to be monitored, which typically requires the addition of one or more files to the CLASSPATH (note that Tivoli Risk Manager client loads classes from the list of archives in the RMINSTDIR/etc/rmclasspath.conf file, not from the system CLASSPATH). For Tivoli Risk Manager software pre-requisites and detailed installation instructions, see the Tivoli Risk Manager 4.2 Installation Guide.

This article describes building a new Tivoli Risk Manager adapter from scratch. Before you start, check the existing range of Tivoli Risk Manager adapters to see if an adapter already exists for the sensor that you wish to integrate. See the Tivoli Risk Manager Adapters Guide, or check the Integration Factory Website for the latest information.

If you are not familiar with the process of installing and configuring a Tivoli Risk Manager 4.2 adapter, I strongly recommend that you take my previous DeveloperWorks tutorial before you start. Additional information is also available in the Tivoli Risk Manager Adapters Guide.

This article assumes some knowledge and experience with the administration of Tivoli Risk Manager. For further assistance, see the Tivoli Risk Manager 4.2 Administrators Guide.

See the Resources section below for links to these publications and Websites.

Planning The Adapter
This section examines how your adapter will gather events, design options and other planning considerations.

Adapter Event Source Options
Tivoli Risk Manager adapters allow you to integrate Tivoli Risk Manager with a wide variety of third-party security "sensors", including intrusion detection sensors (IDS), firewalls, applications and operating systems. Adapters allow Tivoli Risk Manager to capture any security-related event data gathered by these sensors and integrate it with event data from Tivoli Risk Manager's own agent software. The event data can then be forwarded to a Tivoli Risk Manager server for correlation, display on a real-time console, and storage in a relational database.

Tivoli Risk Manager 4.2 includes a Java-based Event Monitor utility for simple installation, configuration and operation of Tivoli Risk Manager adapters. The Event Monitor enables simultaneous monitoring of events from one or more of the following event sources:

• Log Files (ASCII log files or output of UNIX syslog daemon),
• Windows Event Logs (Application, Security, System, DNS Server, File Replication, Directory),
• Relational Database Tables.

This coverage enables integration with the vast majority of security sensors. If your sensor captures event data by some other method, see if it can be modified to integrate with the Event Monitor. For example, your sensor may have a debugging option that enables writing of event data to a text file, which can then be monitored by the new adapter.

If your sensor is not able to log event data in a way that is compatible with the Event Monitor, there are two further alternatives for integrating with Tivoli Risk Manager:

• Tivoli Enterprise Console Adapters - Existing Tivoli Enterprise Console adapters can sometimes be modified to support Tivoli Risk Manager. These adapters are only suited for Tivoli Risk Manager version 4.1, plus a handful of SNMP-based sensors.
• Custom Adapters - Some adapters must be custom built, utilizing the functions of the Tivoli Risk Manager agent to interact directly with the third-party sensor (for example, sensors that utilize a proprietary API to log events).

Although the format file build process that this article describes can also be used for Tivoli Risk Manager 4.1 installations, Tivoli Enterprise Console and custom-built adapters are generally beyond the scope of this article. Please see the Tivoli Risk Manager Adapters Guide for more information, or contact the Tivoli Integration Factory (see Resources below).

Design Considerations
Before you begin building your new Tivoli Risk Manager adapter, consider the following important design questions:

• What type(s) of third party sensor are you integrating with?
• How does the sensor software detect and log security-related events?
• Which of these events do you want to capture?
• For each event, what information is captured and logged (e.g. IP address, server FQDN, username, timestamp)?

Analyzing these questions will require an in-depth understanding of your sensor software. If your sensor catalogues events into groups, you may be able to save time and effort by filtering groups as a whole, rather than individually filtering events.

Your sensor software must be able to log timestamps in a format recognizable to Tivoli Risk Manager, as shown in the table below. Your sensor must also log a valid hostname or IP address. If it does not, see if it can be modified to do so. All other Tivoli Risk Manager class attributes can be any text or numeric value.

Table 1. Event Source formatting requirements

Attribute(s)	Format
rm_Timestamp	Must be a recognizable timestamp in the standard Tivoli Risk Manager (EPOCH) format. For example: JUN 16 15:13:26
rm_SensorHostname rm_DestinationHostname rm_SourceHostname	Must be a valid hostname.
rm_SensorIPAddress rm_DestinationIPAddress rm_SourceIPAddress	Must be a valid and recognizable IP Address. For example: 10.40.6.50.

You also need to consider the potential congestion and space issues that may be created by logging an excessive number of events. Thorough testing before deployment is strongly recommended.

Building The Adapter
This section describes how to create a format file that maps sensor event data into recognizable Tivoli Risk Manager data, then convert this format file into an XML file for use with the Tivoli Risk Manager 4.2 Event Monitor.

Assigning Classes
Having carefully analyzed your sensor software, the first step in building your adapter is to define the Tivoli Risk Manager class mappings for all sensor events you wish to capture.

The best practice at this stage is to create a table or spreadsheet to record this mapping data. Depending on how your sensor logs events and the number of events you wish to monitor, this mapping process may be quite time-consuming.

Tivoli Risk Manager events are recorded in BAROC files (Basic Recorder Of Objects in C). These can be found on the RMINSTDIR/RISKMGR/etc/baroc folder on the Tivoli Risk Manager server. For a list of valid Tivoli Risk Manager classes, refer to the generic.baroc file. The classes in generic.baroc are inherited from the sensor_abstract.baroc file, which also defines valid attributes for those classes. Do not modify these files.

For each distinguishable event that your sensor produces, identify the best Tivoli Risk Manager class. For example, a failed login attempt would be mapped to RMG_SecAuth_Deny, while a successful login attempt would be mapped to RMG_SecAuth_Allow.

It is important to understand the hierarchical structure of Tivoli Risk Manager events. Do not allow your application or adapter to create an event that uses a class that is also a base class for other classes. If this occurs, the Tivoli Risk Manager server will not see any events that are instances of the base class. By default, the Tivoli Risk Manager server only processes incoming events that are instances of leaf classes, such as a class at the bottom of the hierarchy.

See the Tivoli Risk Manager Adapters Guide for further information on Tivoli Risk Manager classes, attributes and values.

Building the Event Monitor FMT file
Now it's time to create a format file that maps all the sensor events you wish to detect into recognizable Tivoli Risk Manager events. This format file will:

• Define the format of events captured from the monitored event source,
• Map these events to Tivoli Risk Manager Event Classes and Categories.

Use a text editor to create a format file with a .fmt extension (adaptername.fmt). The format file can use any of the following string-matching tokenizers:

• %t = time
• %s = match any one word with no spaces
• %s* = match any string including words separated by spaces

Begin by defining a generic base class for the adapter. The following example, Solaris9_Base class, is taken from the Tivoli Risk Manager Adapter for Solaris Host IDS:

// generic base class inherited by all subsequent classes
   FORMAT Solaris9_Base
   %t %s xxxx %s*
   date $1
   -sensor_host $2
   hostname DEFAULT
   adapter_host PRINTF("%s",hostname)
   rm_SensorOS "Solaris"
   rm_Timestamp PRINTF("%s",date)
   rm_TimestampFmt "TIME2"
   rm_SensorType "OS_Solaris"
   rm_SensorHostname PRINTF("%s",sensor_host)
   rm_DestinationHostname PRINTF("%s",sensor_host)
   rm_SourceHostname PRINTF("%s",sensor_host)
   rm_Version "1.0"
   END

The base class shown above will capture all sensor events that begin with a timestamp (%t = date) and a string (%s = sensor_host). The "xxxx" is included as a blocker. All the information from date to rm_Version will be inherited by lower-level classes.

Note that the sensor_host line is commented out with a hyphen (-), which means this information is local to that class for formatting purposes only. It will not be picked up by the adapter and will not be displayed on the Tivoli Enterprise Console.

To ensure that events can be correlated on the server, ensure that the following attributes are set (as a minimum) in either the generic base class or lower-level adapter classes:

• adapter_host (set to the host name of the adapter)
• msg
• rm_DestinationHostname, rm_DestinationIPAddr, or both
• rm_SensorHostname, rm_SensorIPAddr, or both
• rm_SensorType
• rm_Signature
• rm_SourceHostname, rm_SourceIPAddr, or both
• rm_Timestamp
• rm_TimestampFmt (set in the .baroc file as a default)

The sub_source, origin, sub_origin, or hostname attributes do not need to be set because the Tivoli Risk Manager server assigns their values. However, you may want to obtain the adapter's host name and IP address by setting the hostname=DEFAULT and the origin=DEFAULT. The obtained values can then be used to assign values to the rm_SensorHostname and rm_SensorIPAddress attributes.

Having created the base class, continue defining further classes, based on the format of event data captured by your sensor. For example, consider the following Solaris log file entry:

Jun 16 15:13:26 oceanwind login: [ID 658745 auth.crit] REPEATED LOGIN FAILURES ON /dev/pts/1 FROM 132.45.65.23, root

To capture this event data in the adapter format file, the following class is defined:

// class mapping the login event to an RMG_SecAuth_Deny Risk Manager Event
FORMAT RMG_SecAuth_Deny FOLLOWS Solaris9_Base
%t %s login: %s* REPEATED LOGIN FAILURES ON %s*, %s*
-text $3
-tty $4
rm_Object $5
rm_Signature "UNIX Login"
msg PRINTF("login: %s REPEATED LOGIN FAILURES ON %s, %s", text, tty, rm_Object)
END

In this case:

• the timestamp (%t) data is "Jun 15 15:13:26" and the hostname string (%s) is "oceanwind" (captured by the base class above).
• The "login" text and the "REPEATED LOGIN FAILURES ON" text help identify the event as belonging to this class.
• Two text strings, "[ID 658745 auth.crit]" and "/dev/pts/1 FROM 132.45.65.23" are captured but commented out.
• The final string that follows the comma - "root" - is captured as rm_Object data.
• Any events captured by this class are defined with the rm_Signature of "UNIX Login".
• The msg PRINTF line shows how the captured event information will be displayed on the Tivoli Enterprise Console screen.

As a further example, consider another Solaris log file entry:

Jun 16 15:13:46 oceanwind telnetd[358]: [ID 498083 daemon.notice] init Kosseal not avail, rc 40002

In this case, the event data is mapped within the format file as follows:

// class mapping the telnetd event to an RMG_Service Risk Manager Event
FORMAT RMG_Service FOLLOWS Solaris9_Base
%t %s telnetd: [%s %s %s.%s] %s*
-id $3
-msgid $4
-facility $5
-priority $6
-text $7
rm_Signature "Unix Telnetd"
msg PRINTF("telnetd: [%s %s %s.%s] %s", id, msgid, facility, priority, text)
END

Continue mapping all sensor events to Tivoli Risk Manager event classes in this way until your format file is complete.

The RM_NoMapping class should be used as a catch-all, particularly for testing purposes. This will ensure that any non-mapped events are still captured.

Converting the Adapter Format File to XML
The next step is to convert the FMT format file into an XML file, using the wrmfmt2xml.cmd command utility (distributed as part of the agent). To do this:

1. Save your new .fmt format file to the bin directory where the Tivoli Risk Manager agent is installed.
2. Open a command window and change to this bin directory.
3. Run the following command to create a new XML event definition file from your existing FMT format file:

   wrmfmt2xml.cmd adaptername.fmt adaptername.xml

Installing and Configuring The Adapter
Install your new adapter in a test environment first, so that you can monitor the adapter's performance and troubleshoot any problems.

To install the adapter, you must create an adapter configuration file for the Event Monitor, then add an agent source definition and connector definition to the rmagent.xml file.

If your adapter is of the JDBC Table event source type, you must also create an XML configuration file containing JDBC attributes in accordance with the JDBC DTD file (located in the RMINSTDIR/RISKMGR/etc directory). For an example of this, see the Tivoli Risk Manager Adapter for ISS SiteProtector.

Creating the Adapter Configuration File
Once the format file is complete and the conversion into the XML has taken place, a configuration file must be created to configure the Event Monitor to utilize the new adapter.

The configuration file should be named adaptername.conf and placed in the RMINSTDIR/RISKMGR/etc directory. The following configuration file example is suitable for an adapter with a UNIX logfile event source:

   RMMonitorList=A1
   A1Type=LOGFILE
   A1PollingInterval=10
   A1Source=<LOGFILE>
   A1CrcByteCount=50
   A1EventDefinitions=RMINSTDIR/RISKMGR/etc/<adaptername>.xml
   A1ID=<adaptername>

The A1Source value defines the location of the event source being monitored. A valid value for a Solaris syslog (for example) would be /var/adm/messages.

The A1EventDefinitions attribute should point to your newly created adapter XML file (converted from the FMT file).

See the Tivoli Risk Manager Adapters Guide for examples of configurations files that are suitable for other event sources.

Updating rmagent.xml
Once the configuration file has been created, the RMINSTDIR/RISKMGR/etc/rmagent.xml file must be configured so that the Event Monitor will run the adapter.

Add the following lines to the rmagent.xml file:

    <connector>
   		<from name="adaptername"/>
   		<to name="eif_sender"/>
    </connector>

    <source name="adaptername" class="com.tivoli.RiskManager.Agent.Transports.Receivers.rmaMonitorReceiver">
        	<set key="RMA_conf" value="RMINSTDIR/RISKMGR/etc/adaptername.conf"/>
    </source>

Once this has been completed, re-start the Tivoli Risk Manager Agent on the client machine using the wrmadmin -r command. This will command the Tivoli Risk Manager Agent to load the Event Monitor, which will run the Adapter specified in the RMINSTDIR/RISKMGR/etc/adaptername.conf file and send all events processed by the Event Monitor to the eif_sender, which is configured by default to send events to the Tivoli Risk Manager Server.

Testing and Troubleshooting
To verify that your Tivoli Risk Manager adapter has been properly installed and configured:

1. Check that both the third-party sensor and the Tivoli Risk Manager agent are running.
2. Generate a number of security-related events (failed login attempts, password changes, and so forth). These events should correspond with the event types you previously configured within your adapter format file.
3. Check that the events have registered on the Tivoli Risk Manager server.

If the events have not registered:

• Check that events have registered in the sensor's own event source (e.g. log file).
• Check that all adapter details in the adaptername.conf configuration file are correct.
• Check that the RMINSTDIR/RISKMGR/etc/eif_sender.conf file displays the correct IP/hostname of the Tivoli Risk Manager server

For further assistance, see the Tivoli Risk Manager Adapters Guide or the Tivoli Risk Manager Administrator's Guide.

Updating The Adapter
From time to time, you may want to change the contents of the adapter XML file, in response to changing business needs or sensor upgrades. To do this:

1. Make a backup copy of your adapter FMT and XML files, as well as the rmagent.xml file.
2. Edit the FMT file to make the necessary changes.
3. Use the wrmfmt2xml.cmd command to re-create the XML file.
4. Re-install the adapter as described above.

The updated adapter should be run in a test environment before it is installed on your network.

Resources

• For an introduction to Tivoli Risk Manager adapters, including hands-on installation of a Host IDS adapter, see the DeveloperWorks tutorial Centralize security management - Tivoli Risk Manager 4.2 adapters simplify integration with third-party sensors.
  
  
• The Tivoli Software Information Centre contains PDF and HTML versions of the complete Tivoli Risk Manager documentation suite, including:
  • Tivoli Risk Manager 4.2 Adapters Guide
  • Tivoli Risk Manager 4.2 Installation Guide
  • Tivoli Risk Manager 4.2 Administration Guide
  
  
• For the latest news on Tivoli Risk Manager adapters, or assistance with any related questions, see the IBM Tivoli Integration Factory home page.
  
  
• Registered Tivoli customers can also download Tivoli Risk Manager adapters at the Tivoli Risk Manager site.
  
  

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks