Audit Filter

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

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



Core Repository ServicesAuditing


Links


Auditing (from V3.4)




Introduction


This page describes how Alfresco global properties may be used to filter audit data generated by any audit data producer. Audit Filters were introduced in the 4.0 nightly community builds.


Technical Description


Audit data producers call AuditComponent.recordAuditValues(rootPath, auditMap) once for each event to be audited. Filters are applied to reject events so that their values are never used by audit configurations. The rootPath identifies the data producer and the auditMap is the event data. The rootPath value and keys in the map represent a tree structure.

Example rootPath and auditMap



rootPath:
    /alfresco-access/transaction

auditMap:
    'action'         => 'MOVE'
    'node'           => 'workspace://SpacesStore/90a398d1-8e0d-462a-8c3b-f0b17a2d1143'
    'move/from/node' => 'workspace://SpacesStore/a82446e9-4dca-49d2-9ce0-4526687fb310'
    'move/from/path' => '/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:folder1'
    'move/from/type' => 'cm:folder'
    'move/to/node'   => 'workspace://SpacesStore/517bd4d0-99bc-47ad-8cd7-5d425f94c7db'
    'move/to/path'   => '/app:company_home/st:sites/cm:fred/cm:documentLibrary'
    'move/to/type'   => 'cm:folder'
    'path'           => '/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:Word 123.docx'
    'sub-actions'    => 'moveNode readContent'
    'type'           => 'cm:content'
    'user'           => 'admin'

The last component in the rootPath is considered by the AuditFilter to be the event action. The keys in an audit map identify each audit value. Global properties may be defined to accept or reject each value. If any value in an audit map is rejected, the whole map is rejected. So that one does not have to define too many properties, a default event action property may be defined. This will be inherited by all actions unless a property is defined for a particular event action.

Example Filter



audit.filter.alfresco-access.default.enabled=true
audit.filter.alfresco-access.default.user=~System;.*
audit.filter.alfresco-access.default.type=cm:folder;cm:content
audit.filter.alfresco-access.default.path=/app:company_home/.*
audit.filter.alfresco-access.transaction.user=
audit.filter.alfresco-access.login.user=jblogs
...

Each property value defines a list of regular expressions that will be used to match the actual audit map values. In the above example, events created by any user except for the internal user 'System' will be recorded by default for all event actions. However the property for the transaction event action overrides this to record even 'System' events.

For any filters to be applied to an event action, that action's filters must be enabled with an 'enabled' property set to 'true'. However this may also be done by using the default event action, as shown above. 
Property names have a 'audit.filter.' prefix and use '.' as a separator where as components of rootPath and keys in the audit map use '/'.

Lists are evaluated from left to right allowing one flexibility to accept or reject different combinations of values. If no match is made by the end of the list the value is rejected. If there is not a property for a given value or an empty list is defined (as above for the 'user' value on a 'transaction' action) any value is accepted. 
Each regular expression in the list is separated by a semicolon (';'). Expressions that include a semicolon may be escaped using a '\'. An expression that starts with a '~' indicates that any matching value should be rejected. If the first character of an expression needs to be a '~', it too may be escaped with a '\'.

A property value may be a reference to another property, which saves having multiple copies of the same regular expression. This is indicated by a '$' as the first character of the property value. If the first character of an expression needs to be a '$' it too may be escaped with a '\'.

Redirected properties



audit.filter.alfresco-access.transaction.type=$transaction.content.types

transaction.content.types=$general.content.types
general.content.types=cm:folder;cm:content

Debug Information


The  PropertyAuditFilter provides log4j debug information (in the alfresco.log file) when it rejects values. Turning on this debug can generate large volumes of output.
Enable debug



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

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

Customization


Additional filter properties may be defined and predefined filter values may be overridden. If using tomcat, add a properties to <tomcat>/shared/classes/alfresco-global.properties.

Attachments

    Outcomes