For some applications that manage users internally, the application user cannot be identified from the traffic. When this happens, you can use the Guardium Application Events API. The Application Events API provides simple “no-op” calls that can be issued from within the application to signal Guardium when a user acquires or releases a connection, or when any other event of interest occurs.
The syntax for each Guardium Application Events API the is described below.
Note: If your Guardium security policy has Selective Audit Trail enabled, the Application Events API commands used to set and clear the application user and/or application events will be ignored by default, and the application user names and/or application events will not be logged. To log these items so that they will be available for reports or exceptions, you should include a policy rule to identify the appropriate commands, specifying the Audit Only rule action.
Use this call to indicate that a new application user has taken control of the connection. The supplied application user name will be available in the Application User attribute of the Access Period entity. For this session, from this point on, Guardium will attribute all activity on the connection to this application user, until Guardium receives either another GuardAppUser call or a GuardAppUserReleased call (which clears the application user name, as described below).
To signal when other events occur (you can define event types as needed), use the GuardAppEvent call, described in the following section.
Syntax: SELECT ‘GuardAppUser:user_name’ FROM location
user_name is a string containing the application user name. This string will be available as the Application User attribute value in the Access Period entity.
FROM location is used only for Oracle, DB2, or Informix. (Omit for other database types.) It must be entered exactly as follows:
Oracle: FROM DUAL
DB2: FROM SYSIBM.SYSDUMMY1
Informix: FROM SYSTABLES
Use the GuardAppUserReleased call to signal that the current user has relinquished control of the connection. Guardium will clear the application user name, which will remain empty for the connection until it receives another GuardAppUser call.
Syntax: SELECT ‘GuardAppUserReleased’ FROM location
FROM location is used only for Oracle, DB2, or Informix. (Omit for other database types.) It must be entered exactly as follows:
Oracle: FROM DUAL
DB2: FROM SYSIBM.SYSDUMMY1
Informix: FROM SYSTABLES
This call provides a more generic method of signaling the occurrence of application events. You can define your own event types and provide text, numeric, or date values to be stored with the event – both when the event starts and when it ends. You may want to use this call together with the GuardAppUser call described above. Guardium will attribute all activity on the connection to this application event, until it receives either another GuardAppEvent:Start command or a GuardAppEvent:Released command.
Syntax: SELECT ‘GuardAppEvent:Start|Released’,
‘GuardAppEventType:type’,
‘GuardAppEventUserName:name’,
‘GuardAppEventStrValue:string’,
‘GuardAppEventNumValue:number’,
‘GuardAppEventDateValue:date’ FROM location
Start | Released - Use the keyword Start to indicate that the event is taking control of the connection or Released to indicate that the event has relinquished control of the connection.
type identifies the event type. It can be any string value, for example: Login, Logout, Credit, Debit, etc. In the Application Events entity, this value is stored in the Event Type attribute for a Start call, or the Event Release Type attribute for a Released call.
name is a user name value to be set for this event. In the Application Events entity, this value is stored in the Event User Name attribute for a Start call, or the Event Release User Name attribute for a Released call.
string is any string value to be set for this event. For example, for a Login event you might provide an account name. In the Application Events entity, this value is stored in the Event Value Str attribute for a Start call, or the Event Release Value Str attribute for a Released call.
number is any numeric value to be set for this event. For example, for a Credit event you might supply the transaction amount. In the Application Events entity, this value is stored in the Event Value Num attribute for a Start call, or the Event Release Value Num attribute for a Released call.
date is a user-supplied date and optional time for this event. It must be in the format: yyyy-mm-dd hh:mm:ss, where the time portion (hh:mm:ss) is optional. It may be the current date and time or it may be taken from a transaction being tracked. In the Application Events entity, this value is stored in the Event Date attribute for a Start call, or the Event Release Date attribute for a Released call.
FROM location is used only for Oracle, DB2, or Informix. (Omit for other database types.) It must be entered exactly as follows:
Oracle: FROM DUAL
DB2: FROM SYSIBM.SYSDUMMY1
Informix: FROM SYSTABLES
The GuardAppEvent call populates an Application Events entity (see Application Events Entity in the Entities and Attributes Appendix). When creating Guardium queries and reports, you can access the Application Events entity from either the Access Tracking domain or the Policy Violations domain.
If any Application Events entity attributes have not been set using the GuardAppEvent call, those values will be empty.
Regarding the two date attributes:
Event Date is set using the GuardAppEvent call, or from a custom identification procedure as described in the following section.
Timestamp is the time that Guardium stores the instance of the Application Event entity.