Caché Security Administration Guide
Auditing
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Logging certain key events in a secure audit database is a major aspect of Caché security. Caché allows you to monitor events and add entries to the audit database when those events occur. These events can be within Caché itself or part of an application. The knowledge that all activities are being monitored and that all logs can be reviewed is often an effective deterrent.

This chapter provides information on various topics:
Basic Auditing Concepts
Caché allows you to enable or disable auditing for the entire Caché instance. When auditing is enabled, Caché logs all requested events. Auditable events fall into two categories:
Caché system events are built-in events that monitor actions within Caché, such as start-up, shutdown, logins, and so on; system events also monitor security-related events, such as changes to security or audit settings.
Caché does not automatically audit database activity, such as inserts, updates, or deletes for a table, because this kind of activity typically generates so many audit entries as to be useless — or even counterproductive — due to the performance impact on the system. For example, if a medical records application were to log all access to patient medical information, then one such access event might result in hundreds or thousands of database accesses. It is much more efficient to have the application create a single audit entry, rather than have the database manager generate thousands.
Enabling or Disabling Auditing
In the Auditing menu (System Administration > Security > Auditing), there are selections to enable and disable auditing. If the Enable Auditing choice is available, this means that auditing is disabled; if the Disable Auditing choice is available, this means that auditing is enabled. By default, Caché auditing is disabled.
Enabling Auditing
To turn on auditing, on the Auditing menu (System Administration > Security > Auditing), select the Enable Auditing choice.
Disabling Auditing
To turn off auditing, on the Auditing menu (System Administration > Security > Auditing), select the Disable Auditing choice.
If you enable (turn on) auditing, then Caché audits:
About Audit Events
The following sections describe different aspects of audit events:
Note:
This section describes how to manage audit events with the Management Portal. To manage audit events programmatically, use the Security.Events class.
Elements of an Audit Event
Audit information is available in the CACHEAUDIT database. New entries are added to the end of the log. When you view the audit log, you see the following elements for each entry:
Time (also called UTCTimestamp)
UTC date/time when the event was logged.
Event Source*
The component of the Caché instance that is the source of the event. For Caché events, this is always “%System”. For user-defined events, the name can be any string that includes alphanumeric characters or punctuation, except for colons and commas; it can begin with any of these characters except for the percent sign. This can be up to 64 bytes.
Event Type*
Categorizing information for the event. This string can include any alphanumeric characters or punctuation, except for colons and commas; it can begin with any of these characters except for the percent sign. This can be up to 64 bytes.
Event* (also called Event Name)
Identifier of the event being logged. This string can include any alphanumeric characters or punctuation, except for colons and commas; it can begin with any of these characters except for the percent sign. This can be up to 64 bytes.
PID (also known as a Process ID)
Operating system ID of the Caché process that logged the event. On Windows and UNIX®, Caché uses the OS PID in its native form; on OpenVMS, Caché uses the PID in decimal form, converting it from the operating system’s hexadecimal form.
CSP Session (search results only)
The session ID, if there is one, of the CSP session that caused the event.
User (also called Username)
Value of $USERNAME for the process that logged the event.
Description
A short field which can be used by applications to summarize the audit event. This field is intended for display/explanation purposes only. The combination of EventSource, EventType, and Event uniquely define a particular kind of audit event. The Description is a user readable explanation. This can be up to 128 characters.
*Each different kind of event is uniquely identified by the combination of its EventSource, its EventType, and the Event itself.
When you click Details, you see some of the same elements and the following additional elements:
Timestamp
Date/time when the event was logged, in local time.
JobId
ID of the job.
IP Address
IP address of client associated with the process that logged the event.
Executable
The client application associated with the process that logged the event, if there is one.
System ID
The machine and Caché instance that logged the event. For example, for the machine MyMachine and the instance MyInstance, the system ID is MyMachine:MyInstance.
Index
The index entry in the data structure containing the audit log.
Roles
For all events except LoginFailure, the value of $ROLES for the process that logged the event. For LoginFailure, a value of “”, as the user is not logged in.
Namespace
The namespace that was current when the event was logged.
Routine
The routine or subroutine that was running when the event was logged.
User Info
User-defined information about the process, added programmatically via the %SYS.ProcessQuery interface.
O/S Username
Username given to the process by the operating system. When displayed, this is truncated to 16 characters.
This is the actual operating system username only for UNIX or OpenVMS systems.
For Windows:
Status
The value of any %Status object that was audited.
Event Data
A memo field where applications can store up to 16 KB of data associated with the audit event. For example, it can contain a set of application values at the time of the event or can summarize the old and new states of a record or field.
About System Audit Events
System audit events are predefined events that are available for auditing by default. General information about them appears in the table on the System Audit Events page (System Administration > Security > Auditing > Configure System Events), where the columns are:
They monitor events within the Caché system and are distinguishable by their EventSource value of %SYSTEM:
System Audit Events
Event Type and Event Occurs When EventData Contents Default Status
%DirectMode/
DirectMode
Any command is executed in direct mode. Text of command. Off
%Login/
Login
A user successfully logs in.   Off
%Login/
LoginFailure
A login attempt fails. Username. Varies*
%Login/
Logout
A user logs out.   Off
%Login/
Terminate
A process terminates abnormally. Varies, as does the Description field’s content; see below. Off
%SMPExplorer/
Change
Data is altered using the Portal, such as by creating, editing, deleting, compiling, dropping, replacing, or purging classes or tables. Varies, as does the Description field, depending on the action taken. Includes relevant content such as the compile flags or the schema and table being dropped. Off
%SMPExplorer/
ExecuteQuery
A query is executed using on the Portal’s SQL page. The syntax of the executed query. Off
%SMPExplorer/
Export
Data is exported through the Portal. The options selected for data export. Off
%SMPExplorer/
Import
Data is imported through the Portal. The options selected for data import. Off
%SMPExplorer/
ViewContents
Data is viewed through the Portal. The filters that determined what data was viewed. The Description field specifies what was viewed, such as a list of classes, an individual global, or process information. Off
%Security/
ApplicationChange
An application definition is created, changed, or deleted. Action (create new, modify, or delete), old and new application data. On
%Security/
AuditChange
Auditing is stopped or started, entries are erased or deleted, or the list of events being audited is changed. Action (stop, start, erase, delete, or specify), old and new audit settings. On
%Security/
AuditReport
Any standard audit report is run. Identification of audit report. On
%Security/
DBEncChange
There is a change related to database or data-element encryption. Varies, as does the Description field’s content. See below. On
%Security/
DomainChange
A domain definition is created, changed, or deleted. Action (new, modify, delete), old and new domain data. On
%Security/
LoginRuleChange
This event is not currently in use. Even when it is enabled (On), it does not appear in the audit log.   On
%Security/
Protect
A process generates a security protection error. Error. Off
%Security/
ResourceChange
A resource definition is created, changed, or deleted. Action (new, modify, or delete), old and new resource data. On
%Security/
RoleChange
A role definition is created, changed, or deleted. Action (create new, modify, or delete), old and new role data. On
%Security/
SSLConfigChange
An SSL/TLS configuration’s settings are changed. The changed fields with old and new values. On
%Security/
ServiceChange
A service’s security settings are changed. Old and new service security settings. On
%Security/
SystemChange
System security settings are changed. Old and new security settings. On
%Security/
UserChange
A user definition is created, changed, or deleted. Action (create new, modify, or delete), old and new user data. On
%System/
AuditRecordLost
An audit entry has not been added to the audit database due to resource limitations that constrain the audit system (such as disk or database full). None. On
%System/
ConfigurationChange
Caché successfully starts with a configuration different than the previous start, a new configuration is activated while Caché is running, or a lock is deleted through the Portal or through the ^LOCKTAB utility. Username for the user who made the change; previous and new values of the changed element. For deleted locks, information about which lock was deleted. On
%System/
JournalChange
Journaling is started or stopped for a database or process. When journaling is started, the name of the database and its maximum size; when journaling is stopped, none. On
%System/
RoutineChange
A method or routine is compiled or deleted on the local instance. For more details, see below. No content, though the Description field depends on the change itself; see below. Off
%System/
Start
Caché starts. Indication of whether recovery was performed. On
%System/
Stop
Caché is shut down.   On
%System/
SuspendResume
A process is suspended or resumed. The process ID of the process. Off
%System/
UserEventOverflow
An application attempts to log an undefined event. The name of the event that the application attempted to log. On
*The LoginFailure event is off by default for minimal-security installations; it is on by default for normal and locked-down installations.
If auditing is enabled, then all enabled events are audited.
About the %System/%Login/Logout and %System/%Login/Terminate Events
A process generates a %System/%Login/Logout event if the process ends because of:
A process generates a %System/%Login/Terminate event if the process exits for any other reason, including:
About the %System/%Security/DBEncChange Event
A process generates a %System/%Security/DBEncChange event because of:
The EventData includes the encryption key’s ID and key file when these are relevant to the event.
About the %System/%System/RoutineChange Event
A process generates a %System/%System/RoutineChange event because a routine has been compiled or deleted. When enabled, this event causes a record to be written to the audit log whenever a routine or class is compiled. The Description field of the audit record includes the database directory where the modification took place, what routine or class was modified, and the word “Deleted” if the routine was deleted.
Caché audits events on the local server but not for associated instances. For example, if one instance of Caché is an application server that is associated with another instance that is a database server, creating and compiling a new routine on the application server is not audited on the database server, even if the RoutineChange audit event is enabled on the database server. To create a comprehensive list of all changes on all associated instances, enable the relevant events on all the instances and combine their audit logs.
Enabling and Disabling System Events
To enable or disable system events:
  1. From the Management Portal home page, go to the System Audit Events page (System Administration > Security > Auditing > Configure System Events).
  2. On the Configure System Audit Events page, locate the event that you wish to enable or disable and select Change Status from the right-most column of the table. This changes the Enabled status from No to Yes, or vice versa.
About User Events
In addition to system events, Caché allows you to create custom events that can be added to the audit database through your application. All currently defined events are listed on the User-Defined Audit Events page (System Administration > Security > Auditing > Configure User Events).
Creating a User-defined Event
For Caché to audit a user-defined event, it must be added to the list of events and then enabled. The procedure is:
  1. In the Management Portal, go to the User-Defined Audit Events page (System Administration > Security > Auditing > Configure User Events).
  2. Click Create New Event. This displays the Edit Audit Event page.
  3. On this page, enter values in the Event Source, Event Type, Event Name, and Description fields where these components have the purposes described in Elements of an Audit Log Entry.”
  4. By default, the Enabled check box on this page is selected. Click it to disable the event.
  5. Click the page’s Save button to create the event.
  6. Make sure that auditing is enabled.
  7. Once the event is defined and auditing is enabled, you can add the event to the audit log by executing the following command:
    Do $SYSTEM.Security.Audit(EventSource,EventType,Event,EventData,Description)
    using the EventSource, EventType and Event Name values that you defined in the Portal. For more details, see the section Adding an Entry to the Audit Log.”
Adding an Entry to the Audit Log
Applications can add their own entries to the audit log with the $SYSTEM.Security.Audit function:
Do $SYSTEM.Security.Audit(EventSource,EventType,Event,EventData,Description)
where EventSource, EventType, Event, EventData, and Description are as described in the section Elements of an Audit Log Entry.” Both the EventData and Description arguments can hold variables or literal values (where strings must appear in quotation marks). Caché provides all other elements of the log item automatically.
The content of EventData can span multiple lines. Its content is processed in a manner similar to the argument of the Caché ObjectScript Write command, so it uses the following form:
"Line 1"_$Char(13,10)_"Line 2"
In this case, the content listed in the Audit Detail is displayed as “Line 1”, then $Char(13,10) is a carriage return and line feed, then there is “Line 2”.
For example, a medical records application from XYZ Software Company might use values such as:
 $SYSTEM.Security.Audit(
     "XYZ Software",
     "Medical Record",
     "Patient Record Access",
     765432,
     "Access to medical record for patient 765432"
     )
Note that the application uses the EventData element to record the ID of the patient whose record was accessed.
Further, if there is an “XYZ Software/Record Update/Modify Assignment” event defined and enabled, then the following code changes the value of a user-selected element of a list and notes the change in the audit database:
 For i=1:1:10 {
     Kill fVal(i)
     Set fVal(i) = i * i
 }

 Read "Which field to change? ",fNum,!
 Read "What is the new value? ",newVal,!
 Set oldVal = fVal(fNum)
 Set fVal(fNum) = newVal
 Set Data = "Changed field " _ fNum _ " from " _ oldVal _ " to "_ newVal _ "."
 Set Description = "Record changed by user with an application manager role"
 Do $SYSTEM.Security.Audit(
     "XYZ Software", 
     "Record Update", 
     "Modify Assignment",
     Data,
     Description
 )
 Write "Field changed; change noted in audit database."
Audit returns 1 or 0 to indicate that the addition succeeded or failed.
No privilege is required to add an entry to the audit log.
Deleting User Events
If you delete a user event, it is no longer available as part of the Caché instance for auditing. To delete a user event:
  1. From the Management Portal home page, go to the User-Defined Audit Events page (System Administration > Security > Auditing > Configure User Events).
  2. On this page, locate the event that you wish to enable or disable and select Delete from the column near the right-hand part of the table.
  3. When prompted, confirm that you wish to delete the event.
Managing Auditing and the Audit Database
When events are logged, they are visible in the audit database, CACHEAUDIT. The audit database also contains general information, including the name of the server, the name of the Caché configuration, when the log was started, and when the log was closed.
The following actions are available for managing the audit log:
Viewing the Audit Database
To view the audit database, select View Audit Database from the Auditing menu. This displays the View Audit Database page (System Administration > Security > Auditing > View Audit Database). This page allows you to view the audit database and refine a search based on the following fields:
Copying, Exporting, and Purging the Audit Database
The audit log is stored in the %SYS.Audit table in the %SYS namespace; all audit data is mapped to the CACHEAUDIT database and protected by the %DB_CACHEAUDIT resource. By default, the %Manager role holds the Read permission on this resource and no role holds the Write permission.
The audit log database is managed with the same tools other Caché databases. For example, you can use the Management Portal to specify its initial size, growth increment, and location; while the audit log database does not have a specified maximum size, it is constrained by disk space and other such factors.
The Management Portal allows you to perform special management operations on the audit database:
Note:
All these operations act on all entries for one or more days. There are no operations for particular entries.
Copying the Audit Database
Caché allows you to copy all or part of an audit database to a namespace other than CACHEAUDIT. To do this:
  1. From the Management Portal home page, go to the Copy Audit Log page (System Administration > Security > Auditing > Copy Audit Log).
  2. On the Copy Audit Log page, first select either:
  3. Next, use the drop-down menu to choose the namespace where you wish to copy the audit entries.
  4. If you wish to delete the audit items after they are copied, select the check box with that choice.
  5. Click OK to copy the entries.
Caché places the selected audit log entries in the ^CacheAuditD global in the selected namespace. To view this data:
  1. From the Management Portal home page, go to the Globals page (System Explorer > Globals).
  2. From the Globals page, select the following items in the following order:
    1. The Databases radio button from the upper left area of the page.
    2. The name of the database holding the copied audit log entries.
    3. The System check box that appears above the list of globals.
    This displays a list of globals in the database, including ^CacheAuditD. Globals are listed without the preceding “^” character that is needed to manipulate them programmatically or in the Caché Terminal.
    Note:
    Clicking View Globals on this page refreshes the page but unchecks in the System check box, thereby making ^CacheAuditD unavailable.
  3. Click Data from the CacheAuditD line to display detailed information on the audit log entries.
Once you have copied audit data to another namespace, you can use the queries of the %SYS.Audit class to look at that data.
Exporting the Audit Database
Caché allows you to export all or part of an audit database. To do this:
  1. From the Management Portal home page, go to the Export Audit Log page (System Administration > Security > Auditing > Export Audit Log).
  2. On the Export Audit Log page, first select either:
  3. Next, in the Export to file field, enter the path of the file where you wish to export the audit entries. If you do not enter a full path, the root for the path provided is cachesys/Mgr/ where cachesysis the default name of the installation directory.
  4. If you wish to delete the audit items after they are exported, select the check box with that choice.
  5. Click OK to export the entries.
Purging the Audit Database
Caché allows you to purge all or part of a database.
Important:
Purging the database is not a reversible action — purged items are permanently removed. You cannot restore items to the audit database once you have purged them.
To do this:
  1. From the Management Portal home page, go to the Purge Audit Log page (System Administration > Security > Auditing > Purge Audit Log).
  2. On the Purge Audit Log page, first select either:
  3. Click OK to purge the entries.
Encrypting the Audit Database
Caché allows you to encrypt the database that holds the audit log. This is described in the section Configuring Caché Database Encryption Startup Settings in the chapter “Managed Key Encryption” in the Caché Security Administration Guide.
General Management Functions
Because the audit log is stored in a table, you can manage it with standard Caché system management tools and techniques:
Note:
All access is subject to standard security restrictions at the database and/or namespace levels, or through SQL for table-based activity.
The %SYS.Audit table in the %SYS namespace holds the audit log. All audit data is mapped to the CACHEAUDIT database. (You can also copy audit data to any other database using the functionality described in the section Copying the Audit Database; you can then use the %SYS.Audit class, which is available in every namespace, to query the audit log.)
Maintaining the Size of the Audit Database
As Caché runs, it writes to the audit log. Without intervention, this will eventually fill the audit database. If the audit database becomes full, Caché halts. To properly store audit information and also prevent any downtime, you should regularly export and save the contents of the audit database and then purge its contents.
To do this:
  1. Export the contents of the audit database as described in the Exporting the Audit Database section.
    Note:
    InterSystems recommends that you export all entries from the database.
  2. Check that the exported contents of the audit database are valid.
    Important:
    InterSystems recommends that you confirm that this data is valid, as purging the data is a non-reversible action.
  3. Purge old entries from the existing database as described in Purging the Audit Database.
    Important:
    InterSystems recommends that you purge all entries except those of the last day, which ensures that there is an overlap in the different groups of saved entries.
Caution:
If the audit database becomes full, Caché does not record audit entries for actions that cause audit events. Further, in a forensic context, the existence of only a single AuditRecordLost audit entry indicates that at least one record was lost.
Other Auditing Issues
This section covers the following topics:
Freezing Caché If There Can Be No Audit Log Writes
During operations of Caché, it may become impossible to write to the audit database. This can happen due to a filled disk, a failed network connection, or some other reason. If this occurs, Caché can then work in either of two different modes:
To set this switch, use the ^SECURITY routine:
  1. In the Caché Terminal, go to the %SYS namespace:
    > zn "%SYS"
  2. Start ^SECURITY:
    > Do ^SECURITY
  3. Within ^SECURITY, choose option 6 (Auditing Setup); within Auditing Setup, choose option 1 (Enable auditing).
  4. When it displays the prompt: Freeze system on audit database error? Enter “Yes” or “Y”. Confirm any changes when prompted.
This establishes the behavior of freezing the system.
For a disk full error, the way to recover from this is to force down the system, free up space on the audit disk, then restart. For an error caused by database corruption, the audit database must be moved or deleted, and a new one created or copied into its place. Note that a restart of the system will not be enough to clear the error, since the restart may write audit records, and cause the system to freeze again.
For example, with the default behavior, if the disk containing the audit database fills up, then the attempt to write to the audit log will generate a <FILEFULL> error (disk full). The audit record is not written to the audit log, and is therefore lost. When the problem is resolved, an entry is written into the audit log that lists how many audit events were lost.
When this switch is set, and a write error occurs when writing to the audit log, the process which was trying to write to the audit log receives an error (such as <FILEFULL>). The process then writes the error message to the cconsole.log, and then freezes the system.
About Counters
To facilitate security monitoring, Caché keeps a counter for each audit event type and makes these counters available via the Caché monitoring interface. These counters are maintained even if auditing is not enabled. As an example, a site might monitor the LoginFailure event counter, to help detect break-in attempts.
Resetting the Counters for a System Event
To reset the counters for a system event:
  1. From the Management Portal home page, go to the System Audit Events page (System Administration > Security > Auditing > Configure System Events).
  2. On this page, locate the event that you wish to enable or disable and select Reset from the column near the right-hand part of the table.
  3. When prompted, click OK. This resets both the Total and Written counters for the event.
Resetting the Counters for a User Event
To reset the counters for a user event:
  1. From the Management Portal home page, go to the User-Defined Audit Events page (System Administration > Security > Auditing > Configure User Events).
  2. On this page, locate the event that you wish to enable or disable and select Reset from the column near the right-hand part of the table. This resets both the Total and Written counters for the event.
  3. When prompted, click OK. This resets both the Total and Written counters for the event.