Auditing

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. Caché auditing is disabled by default for minimal-security installations; it is enabled by default for normal and locked-down installations.”

To turn on auditing, on the Auditing menu (System Administration > Security > Auditing), select the Enable Auditing choice.

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:

• All system events that are enabled

• All user-defined events that are enabled

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 HALT command

• Exiting application mode because of a QUIT command

• Executing the TerminateOpens in a new tab method of the SYS.ProcessOpens in a new tab class to terminate itself (which is the same as executing HALT).

A process generates a %System/%Login/Terminate event if the process exits for any other reason, including:

• The user closes the Terminal window, resulting in a Terminal disconnect. If the process is in application mode, the Description field of the audit record includes the statement “^routinename client disconnect” (where routinename is the first routine that the process ran); if the process is in programmer mode, the Description field includes the statement “Programmer mode disconnect.”

• A Terminal session is ended by an action in another process, including ^RESJOB, ^JOBEXAM, or the Management Portal. If the process is in application mode, the Description field of the audit record includes the statement “^routinename client disconnect” (where routinename is the first routine that the process ran) ; if the process is in programmer mode, the Description field includes the statement “Programmer mode disconnect.” Note that the event data will contain the pid of the process which terminated them.

• A core dump or process exception. When a process gets a core dump or exception, it is too late for it to write to the audit file. Therefore, when the clean daemon runs to clean up the state of the process, it writes an audit record to the log with a description “Pid <process nunber> Cleaned”.

• A TCP Client disconnect. When a process detects that a client has disconnected, this results in an audit record with a Description field which contains the name of the executable that disconnected, such as “<client application> client disconnect”.

About the %System/%SQL/EmbeddedStatement Event

To use the %System/%SQL/EmbeddedStatement event, you must both enable the event and the #sqlcompile audit macro preprocessor directive:

 #sqlcompile audit = ON

For reference information, see the “#sqlcompile audit” section in the “ObjectScript Macros and the Macro Preprocessor” chapter of Using ObjectScript.

If %System/%SQL/EmbeddedStatement is enabled, then executing any embedded SQL after a #sqlcompile audit = ON directive generates an EmbeddedStatement audit event. For example:

   ...
 #sqlcompile audit = ON
   ...
  &sql(delete from MyTable where %ID = :id)
  // This statement is audited at runtime if %System/%SQL/EmbeddedStatement is enabled.

   ...

 #sqlcompile audit = OFF
   ...
  &sql(delete from MyOtherTable where %ID = :id)
  // This statement is not audited at runtime even if %System/%SQL/EmbeddedStatement is enabled.
   ...

Because an application may have hundreds or thousands of SQL statements (such as those generated as part of compiled class code and those included in system code), the combination of the audit event and the preprocessor directive allows you to be selective in defining which embedded SQL statements to audit.

Additional notes:

• The #sqlcompile audit = ON directive on an INSERT, UPDATE, or DELETE statement does not cause the embedded SQL code in any trigger to be audited. To audit a nested SQL statement, you must include an additional #sqlcompile audit = ON directive in the nested code. For example, if trigger code contains embedded SQL, there must be a #sqlcompile audit = ON directive in that trigger code.

• The results of the audited statement are not recorded.

You can audit all embedded SQL statements except:

• %BEGTRANS

• %CHECKPRIV

• %INTRANS

• %INTRANSACTION

• COMMIT

• GET

• ROLLBACK

• SAVEPOINT

• SET OPTION

• STATISTICS

About the %System/%Security/DBEncChange Event

A process generates a %System/%Security/DBEncChange event because of:

• Encryption key activation

• Encryption key deactivation

• Encryption key and key file creation

• Encryption key file modification

• Encryption settings modification, such as enabling interactive database encryption activation at startup.

The EventData includes data relevant to the event, such as the encryption key ID and key file or a key file administrator name.

About the %System/%Security/X509CredentialsChange Event

For create or update operations, the event data lists the changed properties, subject to security considerations. For Subject Key Identifier and Thumbprint, the event data is a hexadecimal string of space-separated one-byte words; for Certificate, PrivateKey, PrivateKeyPassword, and PrivateKeyType, there is no event data.

For delete operations, there is no event data.

About the %System/%System/DatabaseChange Event

A process generates a %System/%System/DatabaseChange because of any of the following changes to a database:

• Creation

• Modification

• Mounting

• Dismounting

• Compaction

• Truncation

• Global compaction

• Defragmentation

For creation and modification, changes to the following properties cause auditing events (which are included in the event data):

• BlockSize (Create only)

• ClusterMountMode (Cluster systems only)

• ExpansionSize

• GlobalJournalState

• MaxSize

• NewGlobalCollation

• NewGlobalGrowthBlock

• NewGlobalIsKeep

• NewGlobalPointerBlock

• ReadOnly

• ResourceName

• Size

For mounting and dismounting, the event data records the database that was mounted or dismounted. For compaction, truncation, global compaction, and defragmentation, the event data includes include the parameters that the user selected.

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.

About User-Defined Audit Events

In addition to system events, Caché allows you to create custom events that your application can be add to the audit database. These are known as user-defined audit events or user audit events.

All currently defined events are listed on the User-Defined Audit Events page (System Administration > Security > Auditing > Configure User Events).

Creating a User-Defined Audit 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, Event, and EventData 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 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 a User-Defined Audit Event

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.

Viewing the Audit Database

To view the audit database:

1. Select View Audit Database from the Auditing menu, which displays the View Audit Database page (System Administration > Security > Auditing > View Audit Database).

2. To refine the search, use the fields in this page’s left pane and select the Search button at the bottom of the pane. (Select Reset Values at the bottom of the pane to restore the default values.) See below for a list of fields for refining your search.

3. To see more detailed information about a particular audit event, click the Details link in its row.

To refine the search, the fields are:

• Event Source — The component of the instance that is the source of the event.

• Event Type — Any categorizing information for the event.

• Event Name — The identifier of the event being logged (also known simply as the Event).

• System IDs — An identifier for the instance that appears in each audit log entry of the form machine_name:instance_name. For example, an instance called MyInstance running on a machine called MyMachine, then its system ID is MyMachine:MyInstance.

• PIDs — The operating-system ID of the process that logged the event.

• Users — The user who performed the activity that triggered the event.

• Authentications — How the user who triggered the audit event was authenticated to the instance.

• Begin Date/Time — The date and time for the first event to be displayed (midnight at the beginning of the current day, by default). To choose a starting date from a calendar, click the calendar icon to the right of the field.

• End Date/Time — The date and time for the last (most recent) event to be displayed (the current time, by default). To choose an end date from a calendar, click the calendar icon to the right of the field.

• Maximum Rows — The maximum number of rows to display in a listing of the audit log (up to 10,000).

For background information on the fields displayed, see “Elements of an Audit Event.”

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 IRISAUDIT database and protected by the %DB_IRISAUDIT 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 as 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:

• Copying — You can copy entries for one or more days to a specified namespace.

• Exporting — You can export entries for one or more days from the log to a file.

• Purging — You can remove entries for one or more days from the log.

Encrypting the Audit Database

Caché allows you to encrypt the database that holds the audit log. This is described in the section “ Configuring Encryption Startup Settings” in the chapter “Managed Key Encryption” in the 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:

• Journaling is always turned on for it.

• You can use standard ObjectScript commands to read it. In addition, its contents are accessible via standard SQL and you can use any standard SQL tool to work with it.

• You can back it up using standard Caché database backup facilities.

• If it becomes full, a <FILEFULL> error occurs and is handled in the same way as for any other Caché database. To avoid this situation, see the “Maintaining the Size of the Audit Database” section.

The %SYS.AuditOpens in a new tab table in the %SYS namespace holds the audit log. All audit data is mapped to the IRISAUDIT 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.AuditOpens in a new tab class, which is available in every namespace, to query the audit log.)

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:

• The default behavior is to generate an error when there is a problem writing to the Audit log.

• Alternatively, a switch can be set so that the system freezes if there is a problem writing to the Audit log.

To set this switch, use the ^SECURITY routine:

1. In the 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 messages.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.