Help

Content Auditing

cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Content Auditing

resplin
Intermediate
1 1 11.1K
‎6 Jun 2015 0:40 AM

Obsolete Pages{{Obsolete}}

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



Core Repository ServicesAuditing


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=
        /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
<pre>
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
<pre>
/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
<pre>


  1. Change file appender to include debug from any source

log4j.appender.File.Threshold=debug


  1. 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. 
<pre>
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
<pre>

   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
<pre>
<?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
<pre>
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




Labels
1 Comment
Alfresco Content Services Hub Docs

Ask for and offer help to other Alfresco Content Services Users and members of the Alfresco team.

Related links:

We use cookies on this site to enhance your user experience

By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods).   If you are not ok with these terms, please do not use this website.