Content Auditing

From alfrescowiki

Jump to: navigation, search

Warning: Obsolete
This page addresses a topic that does not apply to modern versions of Alfresco. It is likely that we will completely remove this page in the future.

The official documentation is at: http://docs.alfresco.com

Links

Auditing (from V3.4)
Audit Filter

Introduction

This page describes how Alfresco may be used to audit actions performed on your content and folders. A Technical Description is followed by examples of how the standard configuration may be customized.

The 4.0 nightly community build, contains an audit data producer and configuration to report actions performed against user content and folders. These actions are be at a level high enough to allow one to follow who has viewed, modified or deleted content.

Technical Description

Building on the auditing architecture (described in Auditing (from V3.4)) the data producer org.alfresco.repo.audit.access.AccessAuditor gathers together lower events into user recognisable events. For example the download or preview of content are recorded as a single read. Similarly the upload of a new version of a document is recorded as a single create version. By contrast the AuditMethodInterceptor data producer typically would record multiple events.

A default audit configuration file located at <alfresco.war>/WEB-INF/classes/alfresco/audit/alfresco-audit-access.xml is provided that persists audit data for general use. This may be enhanced to extract additional data of interest to specific installations. For ease of use, login success, login failure and logout events are also persisted by the default configuration.

Default audit filter settings (see Audit Filter) are also provided for the AccessAuditor data producer, so that internal events are not reported. These settings may be customized (by setting global properties) to include or exclude auditing of specific areas of the repository, users or some other value included in the audit data created by AccessAuditor.

No additional functionality is provided for the retrieve of persisted audit data, as all data is stored in the standard way, so is accessible via the AuditService search, audit web scripts, database queries and Alfresco Explorer show_audit.ftl preview.

Example Audit Trail

The following is an example audit trail. The user actions from the Share interface were:

  1. Create a new folder called My Documents
  2. Upload a document (The fox.odt)
  3. Preview of the document
  4. Update the meta data
  5. Upload a new version
  6. Copy the document to a folder called MyPictures
  7. Delete the copy of the document

Example audit trail

1. /alfresco-access/transaction/action=CREATE
   /alfresco-access/transaction/aspects/add=[cm:titled]
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents
   /alfresco-access/transaction/properties/add=...
   /alfresco-access/transaction/sub-actions=createNode updateNodeProperties addNodeAspect
   /alfresco-access/transaction/type=cm:folder
   /alfresco-access/transaction/user=admin

2. /alfresco-access/transaction/action=CREATE
   /alfresco-access/transaction/aspects/add=[cm:titled, cm:author]
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
   /alfresco-access/transaction/properties/add=...
   /alfresco-access/transaction/sub-actions=createNode  updateNodeProperties readContent createContent updateContent  addNodeAspect
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin

3. /alfresco-access/transaction/action=READ
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
   /alfresco-access/transaction/sub-actions=readContent
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin

4. /alfresco-access/transaction/action=updateNodeProperties
   /alfresco-access/transaction/aspects/add=[cm:taggable]
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
   /alfresco-access/transaction/properties/add=...
   /alfresco-access/transaction/properties/from={cm:modified=Mon Jun 13 15:34:05 BST 2011}
   /alfresco-access/transaction/properties/to={cm:modified=Mon Jun 13 15:39:35 BST 2011}
   /alfresco-access/transaction/sub-actions=updateNodeProperties addNodeAspect readContent
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin

5. /alfresco-access/transaction/action=CHECK IN
   /alfresco-access/transaction/aspects/add=[cm:versionable]
   /alfresco-access/transaction/copy/from/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My  Documents/cm:The fox (Working Copy).odt
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
   /alfresco-access/transaction/properties/add=...
   /alfresco-access/transaction/properties/from=...
   /alfresco-access/transaction/properties/to=...
   /alfresco-access/transaction/sub-actions=updateNodeProperties  addNodeAspect createVersion readContent deleteNodeAspect updateContent  copyNode checkIn
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin
   /alfresco-access/transaction/version=2.0

6. /alfresco-access/transaction/action=COPY
   /alfresco-access/transaction/aspects/add=[cm:titled, cm:copiedfrom, cm:author, cm:taggable]
   /alfresco-access/transaction/copy/from/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My  Documents/cm:The fox.odt
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Pictures/cm:The fox.odt
   /alfresco-access/transaction/properties/add=...
   /alfresco-access/transaction/sub-actions=createNode readContent createContent updateNodeProperties addNodeAspect copyNode
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin

7. /alfresco-access/transaction/action=DELETE
   /alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Pictures/cm:The fox.odt
   /alfresco-access/transaction/sub-actions=deleteNode
   /alfresco-access/transaction/type=cm:content
   /alfresco-access/transaction/user=admin

The property values have been truncated to "..." as the made the page rather wide.

Using Alfresco Explorer to view the audit trail

The audit trail of individual content may be viewed from within Alfresco Explorer. Locate the content and select the option "Preview in Template", using the show_audit.ftl preview. The following is an example of some high level events.

Show audit.flt.jpg

Share Audit Dashlet

There is also a Share audit dashlet project in Share Extras on GitHub that displays audit events. The source for the project may be found here and the pre-built jar for the latest release here. Currently, the latest release is 0.55. It may be configured to query, filter and limit the audit entries displayed. The following images show example output and configuration :


  • Example ouput :

Audit-dashlet-default.png


  • Configuration dialog :

Audit-dashlet-configuration-dialog.png


Read the associated README file for more information on installation, configuration, and usage. It supersedes the previous wiki page previously found in Google Code.


Enabling Auditing Of Content

To turn on auditing of these events and sub events add the following property to alfresco-global.properties:

Enable the alfresco-access audit application

# Enable audit in general
audit.enabled=true

# Enable the alfresco-access audit application
audit.alfresco-access.enabled=true

# Enable the auditing of sub-actions. Normally disabled as these values are
# not normally needed by audit configurations, but may be useful to
# developers
#audit.alfresco-access.sub-actions.enabled=true

Default Audit Filter Settings

The following properties are set by default to discard events where the user is null or "System", the content or folder path is under "/sys:archivedItem" or under "/ver:" or the node type is not "cm:folder", "cm:content" or "st:site". These values result in events only being recorded for common actions initiated by users of the system. These values may be overridden if required.

Default Audit Filter Settings

audit.filter.alfresco-access.default.enabled=true
audit.filter.alfresco-access.transaction.user=~System;~null;.*
audit.filter.alfresco-access.transaction.type=cm:folder;cm:content;st:site
audit.filter.alfresco-access.transaction.path=~/sys:archivedItem;~/ver:;.*

Audit Data Generated By AccessAuditor

Folder and content changes generate the following audit data structure. Elements are omitted if not changed by the transaction. The /sub-action/<sequence> structure holds cut down details of each sub-action, but are only included if the global property audit.alfresco-access.sub-actions.enabled=true.

Structure of Audit Data

    /alfresco-access
      /transaction
        /action=<actionName>
        /sub-actions=<sub action list>
        /path=<prefixPath>
        /type=<prefixType>
        /node=<nodeRef>
        /user=<user>
        /copy
          /from
            /node=<nodeRef>
            /path=<prefixPath>
            /type=<prefixType>
        /move
          /from
            /node=<nodeRef>
            /path=<prefixPath>
            /type=<prefixType>
        /properties
           /from=<mapOfValues>
             /<propertyName>=<propertyValue>
             ...
           /to=<mapOfValues>
             /<propertyName>=<propertyValue>
             ...
           /add=<mapOfValues>
             /<propertyName>=<propertyValue>
             ...
           /delete=<mapOfValues>
             /<propertyName>=<propertyValue>
             ...
         /aspects
           /add=<mapOfNames>
             /<aspectName>=null
             ...
           /delete=<mapOfNames>
             /<aspectName>=null
             ...
         /version-properties=<mapOfValues>
         /sub-action/<sequence>
           /action=<actionName>
           /copy
             ...
           /move
             ...
           /properties
             ...
           /aspects
             ...

Example audit data

 
Inbound audit values:
    /alfresco-access/transaction/action=MOVE
     /alfresco-access/transaction/node=workspace://SpacesStore/74a5985a-45dd-4698-82db-8eaeff9df8d7
     /alfresco-access/transaction/move/from/node=workspace://SpacesStore/d8a0dfd8-fe45-47da-acc2-fd8df9ea2b2e
     /alfresco-access/transaction/move/from/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder1/cm:Word 123.docx
     /alfresco-access/transaction/move/from/type=cm:folder
     /alfresco-access/transaction/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder2/cm:Word 123.docx
     /alfresco-access/transaction/sub-actions=moveNode readContent
     /alfresco-access/transaction/type=cm:content
     /alfresco-access/transaction/user=admin
     /alfresco-access/transaction/sub-action/00/action=moveNode
     /alfresco-access/transaction/sub-action/00/move/from/node=workspace://SpacesStore/d8a0dfd8-fe45-47da-acc2-fd8df9ea2b2e
     /alfresco-access/transaction/sub-action/00/move/from/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder1/cm:folder1/cm:Word 123.docx
     /alfresco-access/transaction/sub-action/00/move/from/type=cm:folder
     /alfresco-access/transaction/sub-action/01/action=readContent 

Persisted Audit Data

The default audit configuration file alfresco-audit-access.xml only copies the following audit data elements. It also adds login, loginFailure and logout persisted data.

Default Structure of Persisted Audit Data

/alfresco-access
  /login/user=<user>
  /loginFailure/user=<user>
  /logout/user=<user>
  /transaction/
   /action=<actionName>
   /sub-actions=<sub action list>
   /path=<prefixPath>
   /type=<prefixType>
   /user=<user>
   /version=<version>
   /copy/from/path=<prefixPath>
   /move
     /from/path=<prefixPath>
   /properties
      /from=<mapOfValues>
      /to=<mapOfValues>
      /add=<mapOfValues>
      /delete=<mapOfValues>
      /fromName=<oldName>
      /toName=<newName>
    /aspects
      /add=<mapOfNames>
      /delete=<mapOfNames>

The version value is sourced from either the add/cm:versionLabel or to/cm:versionLabel.

With the exception of the property 'name', individual property and aspect changes are not included, as it is not possible to know all possible names. The map values of all changes is however included. The individual property 'name' value is included as it is a well known property, which changes if content or a folder is renamed within the same parent folder.

Debug Information

The AccessAuditor provides log4j debug information (in the alfresco.log file) which is useful when creating custom audit configurations or even when developing other alfresco code. It logs persisted audit data and the full audit data that was generated.

Enable Access AuditorDebug

# Change file appender to include debug from any source
log4j.appender.File.Threshold=debug

# Enable debug from the AccessAuditor
log4j.logger.org.alfresco.repo.audit.access.AccessAuditor=debug

When using the log output as a developer to see what is going on rather than to create a new audit application, it is generally better to use trace (rather than debug) level auditing as the log messages are cut down to make them more human readable.

log4j.appender.File.Threshold=trace
log4j.logger.org.alfresco.repo.audit.access.AccessAuditor=trace

Very occasionally it is also useful to enable debug from the AuditFilter to see why it has rejected generated audit data. See (Audit Filter for details).

Customization

There are two customizations available.

  • Creating a custom audit filter
  • Creating a custom configuration

Custom Audit Filter

The most common customization is to change the default audit filter values. These filter values are used to include or exclude selected events. Global property names identifies elements in the generated audit data. Each property value is a list of regular expressions that either accept or reject the generated data value. If any value is rejected in a set of data the whole set is rejected. For example to audit the users "jblogs" and any user that starts with "temp" other than "tempmanager", override the following global property value. If using tomcat, add a value to <tomcat>/shared/classes/alfresco-global.properties.

Example custom filter

    audit.filter.alfresco-access.transaction.user=~tempManager;test.*;jblogs    

The list is semicolon separated. Any regular expression that starts with a '~' indicates that a matching value should be rejected. The list is evaluated from left to right until there is a match. If no match is made the value is rejected. If the list is empty (zero length) all values are accepted.It is possible to filter on any of the generated data values. For a more detailed description of filter properties see Audit Filter.

Custom Audit Configuration

The most common reason to customize the audit configuration is if there is a need to extract individual property or aspect values that have special meaning to a particular Alfresco installation. For example, a security clearance level has been added to content and it is important to include that clearly in the persisted audit data, rather than having to find it deep within a map of all properties. The default configuration includes an example. It extracts the name property. It is generally a good idea to create a new audit configuration file that includes a mapped path to avoid confusion with the default. If running under Tomcat place the audit configuration file in the <tomcat>/shared/classes/alfresco/extension/audit directory. The following example is simply a cut down version of the default with the path mapped to a new value.

myApp.xml

<?xml version="1.0" encoding="UTF-8"?>
<Audit xmlns="http://www.alfresco.org/repo/audit/model/3.2"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.alfresco.org/repo/audit/model/3.2
    alfresco-audit-3.2.xsd">

  <DataExtractors>
    <DataExtractor name="simpleValue"
        registeredName="auditModel.extractor.simpleValue"/>
  </DataExtractors>

  <PathMappings>
    <PathMap source="/alfresco-access" target="/my-app" />
  </PathMappings>

  <Application name="my-app" key="my-app">
    <RecordValue
        key="action" dataExtractor="simpleValue"
        dataSource="/my-app/transaction/action"
        dataTrigger="/my-app/transaction/action" />
    <RecordValue
        key="user" dataExtractor="simpleValue"
        dataSource="/my-app/transaction/user"
        dataTrigger="/my-app/transaction/user" />
    <RecordValue
        key="path" dataExtractor="simpleValue"
        dataSource="/my-app/transaction/path"
        dataTrigger="/my-app/transaction/path" />
  </Application>

</Audit>

AccessAuditor debug for a move action

 
Audit data:
    /my-app/action=MOVE
    /my-app/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:Word 123.docx
    /my-app/user=admin

Inbound audit values:
    /alfresco-access/transaction/action=MOVE
    /alfresco-access/transaction/node=workspace://SpacesStore/90a398d1-8e0d-462a-8c3b-f0b17a2d1143
    /alfresco-access/transaction/move/from/node=workspace://SpacesStore/a82446e9-4dca-49d2-9ce0-4526687fb310
    /alfresco-access/transaction/move/from/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:folder1/cm:Word 123.docx
    /alfresco-access/transaction/move/from/type=cm:folder
    /alfresco-access/transaction/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:Word 123.docx
    /alfresco-access/transaction/sub-action/00/action=moveNode
    /alfresco-access/transaction/sub-action/00/move/from/node=workspace://SpacesStore/a82446e9-4dca-49d2-9ce0-4526687fb310
    /alfresco-access/transaction/sub-action/00/move/from/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:folder1/cm:Word 123.docx
    /alfresco-access/transaction/sub-action/00/move/from/type=cm:folder
    /alfresco-access/transaction/sub-action/01/action=readContent
    /alfresco-access/transaction/sub-actions=moveNode readContent
    /alfresco-access/transaction/type=cm:content
    /alfresco-access/transaction/user=admin
Personal tools
© 2015 Alfresco Software, Inc. All Rights Reserved. Legal | Privacy | Accessibility