White Paper Audit Management for EMC Documentum Abstract This white paper explains the process of enabling, searching, and purging audit on specific types of objects in Web Development Kit-based applications. June 2011
Copyright 2011 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is a registered trademark of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners. Part Number h8823 2
Table of Contents Executive summary... 4 Audience...4 User Privilege Requirements... 4 Auditing by Object Type...7 Use case for auditing by Object type...10 Auditing by Object instance...13 Auditing by events for all objects in the repository...15 dm_auditmgt and Job Performance Impact...18 Search audit...19 Viewing, verifying, or purging audit trails...21 Audit policy...22 Conclusion... 24 3
Executive summary This white paper explains the process of enabling, searching, and purging audit on specific types of objects in Web Development Kit-based applications. Critical documents must be monitored, and changes must be logged to enable changes to be tracked and verified later. This paper describes use cases and behavior of content stored in audit records. Auditing is a security feature for monitoring events that occur in a repository or application. Auditing an event creates an audit trail, a history in the repository of the occurrence of the event. Audit information can be used to analyze the pattern to access an object, monitor the activity of a specific user, record all or specific events in the repository, and so on. An audit trail is a recorded history of event occurrences that have been marked for auditing. Each occurrence is recorded in one audit trail record. The server stores audit trail records as objects in the repository. Depending on the event, the objects are dm_audittrail, dm_audittrail_acl, and dm_audittrail_group objects. Auditing an event stores pertinent data in the audit trail object, such as when the event occurred and what object was involved. Audience This white paper is intended for customers, partners, and consultants who are planning to track and monitor changes to their critical documents, effectively. User Privilege Requirements Audit management requires extended privileges. The user who does not have the extended privileges can only search and view the audit trail created in the repository. Audit management, administration functionality, is available as a node in Documentum Administrator. Users who do not have extended privileges, can view only the Search Audit and Audit Policies options in the Audit Management page. 4
Figure 1. User without extended privileges A user with the Config, View and Purge audit extended privileges can create audit rules. This privilege is granted when the user is created. To create a user with the required audit privileges: 1. Log in to Documentum Administrator as an Admin user. 2. Navigate to Administration > User Management > Users. 3. Select File > New User. The New user creation page appears. 4. Enter the required fields such as User Name, Login Name, Email Address, and so on. 5. In the Extended Privileges drop-down list, select the Config, View and Purge Audit privilege. 5
Figure 2. New User creation page with extended privileges 6. Click OK. The new user can create audit rules based on object type, object instance, and events. An existing user can also grant extended audit privileges. To grant the extended audit privileges: 1. Log in to Documentum Administrator as an Admin user. 2. Navigate to Administration > User Management > Users. 3. Right-click a user name and select Properties. 4. In the Extended Privileges drop-down list, select the Config, View and Purge Audit privilege. 6
Figure 3. User with extended privileges Users with extended privileges or permissions can create audit rules based on object type, object instance, and events. Auditing by Object Type Auditing by object type creates audit trails for events for all objects of a specific type. You must have the Config Audit privileges to configure auditing, view audit privileges to view audit trails, and purge audit privileges to remove audit trails from a repository. To audit by object type: 1. Log in to Documentum Administrator as a user with the extended privilege for auditing. 2. Navigate to Administration > Audit Management. The Audit Management list page appears. 3. Click Manage Auditing by Object Type. The Choose a type page appears. The object locator lists aspect types and existing standard types. Note: To audit object instances with aspect attributes, you must register the related aspect type for auditing. 7
Figure 4. Object type selector 4. Select a type to audit, and click OK. The Register Audit page appears with the selected object type. Figure 5. Register audit before event selection 5. Click Add Audit. A detailed Register Audit page appears. 8
Figure 6. Event and attribute selection for the dm_document object type 6. Click the Select attributes link to select specific attributes to audit. All attributes specific to the type selected in Step 2 are listed. All attributes are audited if you do not select any attribute. 7. Click Add to select an event on which the audit trail must be generated. You can select more than one event. 8. Select the required attributes and events and click OK. The summary of the audit is displayed. You can edit the audit or unaudit the audit. Using the summary, all objects of type dm_document will generate an audit trail when attributes, keywords, and title are edited and saved. 9. Select the type to unaudit and click Unaudit to remove the audit. 9
Figure 7. Register audit summary after event and attribute selection 10. Click OK to save your changes. Use case for auditing by Object type You have registered an audit based on the dm_document object type. As a result, when you create an object of type dm_document and add or edit keywords and title, an audit trail is generated. To create an object of type dm_document and add or edit keywords and title: 1. Select File > New document. 2. Specify an object name and click Next. 3. Add the title and keywords. For example, specify instance, title1 and key1, key2, and key3, respectively. 10
Figure 8. New document creation 4. Click Finish. Now, a new audit trail record is generated. You can use the Search Audit option to set the query criteria that retrieve the required audit trails. Execute the following DQL command in the DQL editor: Select * from dm_audittrail where object_type = 'dm_document' and event_name='dm_save' order by time_stamp desc If you want to run a search based on attributes added in the audit rule, modify the query as follows: Select attribute_list_old, attribute_list from dm_audittrail where object_type = 'dm_document' and event_name='dm_save' order by time_stamp desc The attribute_list_old attribute contains the previous value(s) for the attribute and the attribute_list attribute contains the current value(s). In the example, we added the single-valued Title attribute, and a repeating attribute, Keyword, in the attributes to audit. When you modify these values and save the dm_document object, an audit trail is generated. For example, an object is created with the title as title1 and keyword values as key1, key2, key3. If you change the value of the title from title1 to title1updated and the value of keywords from key2 to key2updated, the following audit trail is generated for the specified query: 11
Select attribute_list_old, attribute_list from dm_audittrail where object_type = 'dm_document' and event_name='dm_save' and object_name= audit_test1 attribute_list_old keywords="'','',''", title="word 97/2000 Document" keywords=, key2, title= title1 attribute_list keywords="'key1','key2','key3'", title="title1" keywords=, key2updated, title= title1updated The attribute_list_old attribute contains the previous values of the audited attributes and the attribute_list attribute contains the current values. In the case of single-valued attributes, if you consider the values in the audit trail, the old value is replaced by the new value. In the case of repeating attributes, only the index in which the value is modified is displayed. The common values or unchanged values should not be part of any list. If the index positions [0] and [2] of keywords are not modified, only position [1] is modified from key2 to key2updated. Hence, the index position [1] of keywords contains the previous value and the current value, and the other index positions that are unchanged, are blank. Let us consider some more examples by appending, deleting, and shuffling values to the keywords attribute. attribute_list_old attribute_list keywords="'','',''", title="word 97/2000 Document" keywords=, key2, title= title1 keywords=,,,, keywords="'key1','key2','key3'", title="title1" keywords=, key2updated, title= title1updated keywords=,,, key4, key5 The third entry in the table is the result displayed where two values are added to the keywords indices [3] and [4] whose previous values were blank. Since you have not modified the value for title, it is not reflected in the attribute_lists. attribute_list_old attribute_list keywords="'','',''", title="word 97/2000 Document" keywords=, key2, title= title1 keywords=,,,, keywords=,, key3, key4 keywords="'key1','key2','key3'", title="title1" keywords=, key2updated, title= title1updated keywords=,,, key4, key5 keywords=,, key4, key5 The fourth entry in the table shows the search result after the index position [2] is deleted, when the value key3 is deleted from keywords. When a value in the index position [2] is deleted, the value at [3] and [4] are copied to the positions [2] and [3]. Hence, the positions [2] and [3] are indicated as modified values and the lists show the previous and current values of these indices. 12
attribute_list_old keywords="'','',''", title="word 97/2000 Document" keywords=, key2, title= title1 keywords=,,,, keywords=,, key3, key4 keywords= key1, key2, key4, key5 attribute_list keywords="'key1','key2','key3'", title="title1" keywords=, key2updated, title= title1updated keywords=,,, key4, key5 keywords=,, key4, key5 keywords= key5, key4, key1, key2 The fifth entry is the result of shuffling the values. Since each index position has changed, all values are included in the list. Auditing by Object instance Auditing by object instance creates audit trails for events for a specific object in the repository. You must have the Config Audit privilege to audit object instances. To audit by object instance: 1. Log in to Documentum Administrator as a user with the extended privilege for auditing. 2. Navigate to Administration > Audit Management. The Audit Management list page appears. 3. Click Manage Auditing by Object Instances. The Choose Objects page appears. 4. Select the required objects using the object selector and click OK. By default, the Choose Objects page displays the cabinets in the repository. Click a cabinet name or folder name within a cabinet to browse to the required documents. 13
Figure 9. Object selector 5. Select an object in the list on the left and move it to the list on the right. Each selected object is audited separately. 6. Click OK. The Register Audit page where you can select the events for the selected objects, appears. Figure 10. Register audit before event selection 14
7. When you select one of the objects in the list, the Edit and Unaudit buttons are enabled so that the events and the attributes on which the audit trail must be generated, can be added to the audit trail. Note: All attributes are audited if you do not select any attribute. 8. Click Edit. A detailed Register Audit page appears. 9. Specify the audit criteria and audit events for the object instances. Figure 11. Events and attribute selector for the object instance 10. Click OK after selecting the required events and attributes. In the example we are currently considering, the image001.jpg object generates an audit trail on the dm_save event, and the data structures and algorithms.pdf object generates an audit trail when a checkout or checkin operation is performed. 11. Select the objects to unaudit and click Remove to remove the selected audit. 12. Click OK to register/unregister the audit. The use case described for auditing by object type is valid for auditing by instance and audit trail will be generated whenever the object image001.jpg is saved. Auditing by events for all objects in the repository You must have Config Audit privileges to audit all objects in the repository. To enable auditing for all objects in the repository: 1. Log in to Documentum Administrator as a user with extended privileges for auditing. 15
2. Navigate to Administration > Audit Management. The Audit Management list page appears. 3. Click Manage Auditing by events selected for all objects in the repository. The Register Audit page appears. Figure 12. Register audit before event selection 4. Click Add to add events. The Event Selector page appears. 16
Figure 13. Event selector page 5. Select the events required for auditing and click OK. For instance, select dm_save. All objects in the repository will generate audit trail when the object is saved. 6. Select the event to be unaudited and click Remove to remove the audit. Figure 14. Register audit after event selection 17
7. Click OK to register or unregister the audit. dm_auditmgt and Job Performance Impact Auditing by events for all objects in the repository will affect the performance of the application, considerably, because an audit trail is generated every time the specified event occurs (dm_save in the above example). If the audit trail entries are not removed periodically, the tables for the dm_audittrail object type can grow unwieldy, and performance will degrade when audited events occur. To delete audit entries that are not required or audit entries that occurred within a specified time frame, you can use the dm_auditmgt job. Navigate to Job Management > Jobs to locate this job. Auditing by events for all objects in the repository will affect the performance of the application, considerably, because an audit trail is generated every time the specified event occurs (dm_save in the above example). If the audit trail entries are not removed periodically, the tables for the dm_audittrail object type can grow unwieldy, and performance will degrade when audited events occur. To delete audit entries that are not required or audit entries that occurred within a specified time frame, you can use the dm_auditmgt job. Navigate to Job Management > Jobs to locate this job. Figure 15. dm_auditmgt Audit Job You can pass the following arguments to this job: Cutoff days: A minimum age in days, of objects to delete. All audit trail objects older than the specified number of days, which meet the specified qualification, are deleted. 18
Custom predicate: A where clause qualification for the query that selects audit trail entries for deletion. If you do not specify a value for the custom_predicate or cutoff_days argument, all system-generated dm_audittrail entries older than 90 days, are deleted. For more information about all arguments, see the Content Server Administrator Guide. Search audit The Search audit feature enables you to search and view audit trails. You must have the View Audit extended privileges to search and view existing audit trails. To search an audit trail: 1. Log in to Documentum Administrator as a user with extended privileges for auditing. 2. Navigate to Administration > Audit Management. The Audit Management list page appears. 3. Click Search Audit. The Search Criteria page appears. Figure 16. Search by criteria defined 4. Select the DQL option, for which you can use the clause in DQL statements specified in the Use case for auditing by Object type section. 19
Figure 17. Search by DQL 5. Click OK. All audit trails matching the DQL query or selection criteria are displayed. You can sort the audit trails by clicking the Object Name, Event Name, User Name, or Date Created column. Figure 18. Audit trail listing page 20
Viewing, verifying, or purging audit trails You can view the properties of an audit trail after performing a search operation. To view the audit trail: 1. Select the audit trail in the Audit Trails page. 2. Select View > Properties > Info. Alternatively, you can right-click and select Properties to view the audit trail. The Info page with attribute name and value, appears. Figure 19. View audit properties Note: You can verify only signed audit trails. To verify an audit record: 1. Select an audit trail in the Audit Trails page. 2. Select Tools > Verify audit trail. Alternatively, right-click an audit trail and select Tools > Verify Audit Record. You must have Purge Audit privileges to purge audit records. If the audit record is protected by an audit policy, you can purge the record only if the purge policy is assigned to you or the group to which you belong. To purge an audit record: 1. Select one or more audit trails in the Audit Trails page. 2. Select Tools > Purge Audit Record(s). 21
Alternatively, right-click an audit trail and select Tools > Purge Audit Record(s). Note: To purge all audit records, without selecting any object in the Audit Trails page, select Tools > Purge all audit records. Audit policy An audit policy ensures that only users or groups that are specified in the Purge policy can delete an audit record. If an unauthorized user or group attempts to delete the audit record, Content Server throws an error message. If multiple policies are associated with a user, the policy with the highest permissions, is in effect. Audit policies specify users, groups, or roles that can purge audit trails. You must be an Install Owner to access and manage audit policies. Other users can only view the list of audit policies. To find the Install owner later, dm_server_config can be used. (The value of attribute r_install_owner ). To create an audit policy: 1. Log in to Documentum Administrator as a user with the extended privilege for auditing. 2. Navigate to Administration > Audit Management. The Audit Management list page appears. 3. Click the Audit policies link. The available audit policies are displayed in the datagrid. Figure 20. Audit policy listing page 4. Select File > New > Audit policy. The New Audit policy page appears. 22
5. Specify the name of the audit policy, the user/group/role to which this audit policy is assigned, and the policy rules. Figure 21. New audit policy page For example, consider the following audit policy where the accessor name is set to Administrator, and object_type and event name are added to the Audit policy rules. Figure 22. Audit Policy example 23
After the audit policy is created, whenever an audit trial is generated for the sample_type object type on the dm_save event, those records can be processed (verified/purged) only by the Administrator. Conclusion The paper explains the user privileges required to configure, view and purge audit. You can use it as a step-by-step guide to enable audit for repository objects based on object type, object instance, and user events specific to one or all objects. It explains configuring audit policies, a set of use cases on how effectively an attribute change can be captured on critical documents, and the different ways to search for audit trail records that are logged for a particular object. If all the objects in the repository are audited, it may cause performance issues based on the system load, because every event generates an audit trail record. You can run the dm_auditmgt Job to purge old records after specifying a duration. 24