2.1.1 Understanding Event Makeup

Novell developed a universal event prototype to represent a wide variety of events that might occur in an application running on a network. Each event is made up of several string, integer, and raw data fields, some of which are consistent across applications, and some of which you can customize to provide details about the event you are logging. This consistency, and the centralized nature of Novell Audit 2.0, provide the ability to securely log and search event data across all applications, then retrieve relevant information about any logged event.

All events reported to the Secure Logging Server must be in this format, which is detailed in Event Fields.

Event Fields

An event is made up of several data fields that fall into two basic categories: System attributes, which is mandatory section containing information about the reporting application and other system-related information; and payload, which is an optional section containing data relating to the specific event that occurred. The contents of the system attributes and payload sections are illustrated in the following figure:

Figure 2-1 Novell Audit 2.0 Event Fields

Detailed information on each data field listed in the previous figure is contained in the following sections:

• Component
• Event ID
• Log Level
• Group ID
• IP Address, Client Time Stamp, Server Time Stamp
• String Value 1, String Value 2, String Value 3
• Numerical Value 1, Numerical Value 2, Numerical Value 3
• Target, Target Type, Originator, Originator Type, Subtarget
• Data, DataSize, MIMEHint

Component

This section lists the component of the application which logged the event. A component string is formatted like a DOS path name, with a backslash (\) separating component parts, and must be provided for each event. The intent of the component string is to allow searching across various products, or event IDs.

\eDirectory\Database\Lookup \iChain\Connection Manager\Authentication \NetMail\POP3\Authentication

The first part of the component, the application, is inserted by the Secure Logging Server based on the application ID of the authenticated application. Additional information on application authentication is contained in Section 2.2.3, Secure Event Logging.

Event ID

The event ID is made up of two parts, the application ID and the application event ID. The application ID is assigned through a central registry, and is discussed further in Section 2.1.4, Registering an Application ID. The application event ID is a number assigned by you to uniquely identify an event, usually in ascending order. The reserved range is a set of application ID numbers that are never assigned through the central registry, and are available for application developers to use for development and testing purposes.

The event ID is detailed in Figure 2-2.

Figure 2-2 Event ID Format

Log Level

The log level is an indicator of the severity of the reported event. Although any number can be used, the following levels have predefined meanings and should be used whenever possible:

Flag	Description
LE_EMERGENCY	Events that cause the reporting application to shutdown
LE_ALERT	Events that require immediate attention
LE_CRITICAL	Events that can cause parts of the reporting system to malfunction
LE_ERROR	Events describing errors which can be handled by the reporting system
LE_WARNING	Negative events not representing a problem
LE_NOTICE	Events (positive or negative) an administrator can use to understand or improve the use and operation of reporting system
LE_INFO	Positive events of any importance
LE_DEBUG	Events of relevance for support or engineers to debug operation of the reporting system

Group ID

The Group ID is used to mark multiple log events belonging to a single transaction. When logging events, you are responsible for choosing an appropriate group ID for events. The group ID is used mainly for searching, and all events logged by an application can use the same group ID if appropriate.

IP Address, Client Time Stamp, Server Time Stamp

The IP address of the reporting host, as well as the client and server time stamps, are assigned by the Platform Agent and Secure Logging Server, respectively. These fields are populated by the Secure Logging Server and cannot be provided or changed by a reporting application.

String Value 1, String Value 2, String Value 3

Each string value field contains relevant string data to be logged with an event, and is optional. If an event does not have any associated strings, these fields should be left as NULL.

The recommended usage of these values is as follows:

• String Value 1: Contains the base value or new value of a subtarget that has been acted upon if the value is of type string.
• String Value 2: Contains the prior value of a subtarget that has been acted upon if the value is of type string, and if applicable for the type of event being logged.
• String Value 3: Defined by your application.

Numerical Value 1, Numerical Value 2, Numerical Value 3

Each numerical value field contains relevant integer data to be logged with an event, and is optional. If the event does not have any associated values, these fields should be left as 0.

The recommended usage of these values is as follows:

• Numerical Value 1: Contains the base value or new value of a subtarget that has been acted upon if the value is of type integer.
• Numerical Value 2: Contains the prior value of a subtarget that has been acted upon if the value is of type integer, and if applicable for the type of event being logged.
• Numerical Value 3: Defined by your application.

Target, Target Type, Originator, Originator Type, Subtarget

These values are used to construct the noun-verb part of the event. The target captures who or what the target of the operation was, the originator captures who or what caused the event to happen, and the subtarget captures the subcomponent of the target that was affected by the event.

Target Type and Originator Type are integers that specify which predefined format the target and originator are represented in. Defined values for this type are currently as follows:

• 0: None
• 1: Slash Notation
• 2: Dot Notation
• 3: LDAP Notation

Data, DataSize, MIMEHint

The data field provides, by default, up to three kilobytes of binary data to be logged with an event, and is optional. If necessary, the size of the data field can be expanded by your application. See Section 2.2.2, Configuring the Platform Agent for more information.

You must provide a size along with the data, and, if possible, provide a MIME hint about the type of the data. Predefined MIME hints are in the Novell Audit 2.0 header file, logevents.h.

Generally, data that should be accessed by an administrator should be stored in the string and numerical values of the payload, and the binary section should store information designated to be read by your application, because this data can often be difficult to understand.

2.1.2 Collecting your Current Messages

After you understand the basic structure of events, you need to collect events your application might generate.

For an existing application, or an application in development, your current list of messages or events can be given an ID and payload values, and logged to the Secure Logging Server with any additional events you want to define and report.

The following table contains a sample listing of error codes and messages.

If you have no existing messages, you can start this list from scratch with the information in Section 2.1.3, Mapping Messages and Determining Payload Values.

2.1.3 Mapping Messages and Determining Payload Values

After you have a listing of each event you want to report, you need to determine relevant information to report for each event.

Create a list containing each event you want to log, and map any relevant data you want logged in the payload values with each event. The following table is an example, and can be used as a basic template:

These values correspond to the input parameters of the primary event reporting function, LogEventDirect. Look closely at this function to determine the level of detail required to report an event.

2.1.4 Registering an Application ID

To help ensure that every instrumenting application is unique and secure in your environment, individual applications should have their application ID registered with Novell. By registering an application ID, administrators can easily find events and associate them with your application, and you can use key-pair encryption to ensure that each event reported by your application was logged and originally came from your application.

To obtain an application ID, visit the Novell Developer Services Event ID registration page at http://developer.novell.com/devres/ss/resource.htm.

This value, combined with a 16-bit application event ID assigned by you, is included with each event logged by your application.

2.1.5 Creating a Log Schema File

Log schema files are used by the Secure Logging Server to register each application's events, and to label event fields for each reported event. If your application does not have a schema file installed on the Secure Logging Server, any attempt to send you application events is denied.

See Log Schema Files in the Novell Audit 2.0 Administration Guide for information on using log schema files.

To create a schema file, create a new text file named after your application, followed by an underscore and a 2-character language code, with an .lsc extension. For example, letest_en.lsc.

The first line of the LSC file that isn’t a comment should contain the application ID (see Section 2.1.4, Registering an Application ID), your application name, and a description of your application. For example:

 
 FFF1,LETest,LogEvent Test App Events
 

After this initial line, the schema file contains an index of each event and the corresponding values, in an accessible, localizable format. After you have mapped your messages and determined your payload values, the information for each event should be placed on a separate line in the following format:

 
 EventID,Description,Originator Title, Target Title, SubTarget Title,Text1 Title,Text2 Title, Text3 Title,Value1 Title,Value1 Type,Value2 Title,Value2 Type, Value3 Title, Value3 Type,Group Title,Group Type,Data Title,Data Type,Display Schema
 

For example (the following would appear on a single line in your schema file):

 
 FFF10001,Test Event,Originator,Target,SubTarget,Text1,Text2,Text3,Value1,N,Value2,
 N,Value3,N,Grouping,N,,,A Test Event was sent with Originator $SB; Target $SU; SubTarget $SV; Text1 $SS; Text2 $ST; Text3 $SF; Value1 $N1; Value2 $N2; Value3 $N3; Grouping $NG\r\n
 

The last line, display schema, is used as a display message when the event occurs. If a particular event has no data for a value, simply leave it empty. A spreadsheet application that can export comma-delimited values can be used to create this file.

Values beginning with $ are variables, see Log Schema File Variables for details.

When you application is installed, AuditExt can be used to add your application to the Secure Logging Server. See Log Schema Files in the Novell Audit 2.0 Administration Guide for details.

An example schema file, letest_en.lsc, is included in the build folder of this SDK. Additionally, several complete application schema files are included with Novell Audit 2.0.

 
 #^GROUP^<description>^<events>
 

 
 #^GROUP^Volume^000A0101,000A0102
 

 
 #^GROUP^Server^000A0103,000A0104,000A0105,000A0108,000A0109,000A010A
 

 
 #^GROUP^File System^000A0001-000A0011,000A0016
 

 
 #^GROUP^Logon and Logoff^000A0107,000A010B
 

 
 $FV