Chapter 10. Auditing

Certain government organizations mandate auditing in enterprise applications to ensure the software components of an implementation are traceable, and operating within their design parameters. Additionally, government regulations and standards require audit controls in addition to standard application auditing.
System administrators can enable security event auditing to constantly monitor the operation of the security domain, and deployed Web and EJB applications.

Important

Security event auditing may introduce a performance impact on servers that manage high event volumes. Auditing is deactivated by default, and should be configured to be available on-demand.
Activating security event auditing differs between Web and EJB components. Procedure 10.1, “Enable the security audit feature” describes the minimum steps to enable the audit service for EJBs in your implementation . Procedure 10.2, “Enable security auditing for Web containers” describes how to enable security event auditing for Web containers.

Important

Web container event auditing can expose sensitive user information. Administrators must ensure appropriate data protection procedures such as password hashing are implemented when configuring security auditing for Web container events.

Procedure 10.1. Enable the security audit feature

  1. Open the log4j configuration file

    Navigate to $JBOSS_HOME/server/$PROFILE/conf/
    Open the jboss-log4j.xml file using a text editor.

  2. Uncomment the security audit category

    By default, the Security Audit Provider category definition in the jboss-log4j.xml file is commented out. Uncomment the category definition shown in Example 10.1, “log4j Security Audit Provider category”.

    Example 10.1. log4j Security Audit Provider category

    <?xml version="1.0" encoding="UTF-8"?>

<!-- Limit the verbose MC4J EMS (lib used by admin-console) categories -->
<category name="org.mc4j.ems">
  <priority value="WARN"/>
</category>
   
<!-- Show the evolution of the DataSource pool in the logs [inUse/Available/Max]
<category name="org.jboss.resource.connectionmanager.JBossManagedConnectionPool">
  <priority value="TRACE"/>
</category>
   -->

<!-- Category specifically for Security Audit Provider -->
<category name="org.jboss.security.audit.providers.LogAuditProvider" additivity="false">
<priority value="TRACE"/>
  <appender-ref ref="AUDIT"/>
</category>

   
<!-- Limit the org.jboss.serial (jboss-serialization) to INFO as its DEBUG is verbose -->
<category name="org.jboss.serial">
  <priority value="INFO"/>
</category>

  3. Uncomment the audit appender

    By default, the AUDIT appender definition in the jboss-log4j.xml file is commented out. Uncomment the appender definition shown in Example 10.1, “log4j Security Audit Provider category”.

    Example 10.2. log4j Security Audit Provider category

    ...
<!--  Emit events as JMX notifications
<appender name="JMX" class="org.jboss.monitor.services.JMXNotificationAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Threshold" value="WARN"/>
  <param name="ObjectName" value="jboss.system:service=Logging,type=JMXNotificationAppender"/>
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d %-5p [%c] %m"/>
  </layout>
</appender>
-->

<!-- Security AUDIT Appender -->
<appender name="AUDIT" class="org.jboss.logging.appender.DailyRollingFileAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="File" value="${jboss.server.log.dir}/audit.log"/>
  <param name="Append" value="true"/>
  <param name="DatePattern" value="'.'yyyy-MM-dd"/>
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d %-5p [%c] (%t:%x) %m%n"/>
  </layout>
</appender>
   
   <!-- ================ -->
   <!-- Limit categories -->
   <!-- ================ -->

<!-- Limit the org.apache category to INFO as its DEBUG is verbose -->
<category name="org.apache">
  <priority value="INFO"/>
</category>
...

  4. Save, and restart server

    You have now activated the auditing service for your implementation, as configured in the jboss-log4j.xml file.
    Restart the server to ensure the new security policy takes effect.

  5. Verify security auditing is functioning correctly

    Once the audit service is configured and deployed, audit log entries will verify the audit service and EJB invocation success.
    The audit.log file is located in jboss-as/server/$PROFILE/log/ directory.
    A successful EJB invocation would look similar to the following audit.log output.

    Example 10.3. Successful EJB Invocation log entry

    2008-12-05 16:08:26,719 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-2:) [Success]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518; Resource:=[org.jboss.security.authorization.resources.EJBResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518}:method=public abstract org.jboss.test.security.interfaces.RunAsServiceRemote org.jboss.test.security.interfaces.RunAsServiceRemoteHome.create() throws java.rmi.RemoteException,javax.ejb.CreateException:ejbMethodInterface=Home:ejbName=RunAs:ejbPrincipal=jduke:MethodRoles=Roles(identitySubstitutionCaller,):securityRoleReferences=null:callerSubject=Subject:
        Principal: [roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]
        Principal: Roles(members:extraRunAsRole,identitySubstitutionCaller)
:callerRunAs=[roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]:callerRunAs=[roles=[identitySubstitutionCaller, extraRunAsRole],principal=runAsUser]:ejbRestrictionEnforcement=false:ejbVersion=null];Source=org.jboss.security.plugins.javaee.EJBAuthorizationHelper;Exception:=;
    An unsuccessful EJB invocation would look similar to the following audit.log output.

    Example 10.4. Unsuccessful EJB Invocation log entry

    [Error]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518;Resource:=[org.jboss.security.authorization.resources.EJBResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518}:method=public java.security.Principal org.jboss.test.security.ejb3.SimpleStatelessSessionBean.invokeUnavailableMethod():ejbMethodInterface=Remote:ejbName=SimpleStatelessSessionBean:ejbPrincipal=UserA:MethodRoles=Roles(<NOBODY>,):securityRoleReferences=null:callerSubject=Subject:
        Principal: UserA
        Principal: Roles(members:RegularUser,Administrator)
:callerRunAs=null:callerRunAs=null:ejbRestrictionEnforcement=false:ejbVersion=null];Source=org.jboss.security.plugins.javaee.EJBAuthorizationHelper;Exception:=Authorization Failed: ;

Procedure 10.2. Enable security auditing for Web containers

  1. Enable EJB security auditing

    You must enable security as described in Procedure 10.1, “Enable the security audit feature”.

  2. Activate auditing in the server realm

    Web container auditing must first be activated in the server realm of the server.xml file.
    The server.xml file is located in the jboss-as/server/$PROFILE/deploy/jbossweb.sar/ directory.
    The <Realm> element must have the enableAudit="true" attribute set, as per Example 10.5, “server.xml audit activation”.

    Example 10.5. server.xml audit activation

    <Realm className="org.jboss.web.tomcat.security.JBossWebRealm" certificatePrincipal="org.jboss.security.auth.certs.SubjectDNMapping" allRolesMode="authOnly" 
enableAudit="true"/>

  3. Specify auditing levels system property

    The auditing levels for Web applications must be specified using the org.jboss.security.web.audit system property in the run.conf (Linux) or run.conf.bat (Microsoft Windows) script.
    Alternatively, you can specify the system property in the jboss-as/server/$PROFILE/deploy/properties-service.xml file.

    • Linux

      Add the system property into the jboss-as/bin/run.sh file. 
      ## Specify the Security Audit options
#System Property setting to configure the web audit:
#* off = turn it off
#* headers = audit the headers
#* cookies = audit the cookie
#* parameters = audit the parameters
#* attributes = audit the attributes
#* headers,cookies,parameters = audit the headers,cookie and 
#                               parameters
#* headers,cookies = audit the headers and cookies
JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.security.web.audit=headers,cookies,parameter"

    • Microsoft Windows

      Add the system property into the jboss-as/bin/run.bat file. 
      rem Specify the Security Audit options
rem System Property setting to configure the web audit
rem * off = turn it off
rem * headers = audit the headers
rem * cookies = audit the cookie
rem * parameters = audit the parameters
rem * attributes = audit the attributes
rem * headers,cookies,parameters = audit the headers,cookie and
rem   parameters
rem * headers,cookies = audit the headers and cookies
set JAVA_OPTS=%JAVA_OPTS% " -Dorg.jboss.security.web.audit=headers,cookies,parameter"

    • properties-service.xml

      Update the SystemPropertiesService class MBean in the jboss-as/server/$PROFILE/deploy/properties-service.xml file, and declare the java property as an <attribute>. You can uncomment the relevant operating system block in the code sample below. 
      <mbean code="org.jboss.varia.property.SystemPropertiesService" 
name="jboss:type=Service,name=SystemProperties">
   <attribute name="Properties">
org.jboss.security.web.audit=headers,cookies,parameter
   </attribute>
</mbean>

  4. Verify security auditing is functioning correctly

    Once the system property is specified in the files, audit log entries will verify Web invocation success.
    The audit.log file is located in jboss-as/server/$PROFILE/log/ directory.
    A successful Web invocation would look similar to the following audit.log output.

    Example 10.6. Successful Web Invocation log entry

    2008-12-05 16:08:38,997 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-17:) [Success]policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518;Resource:=[org.jboss.security.authorization.resources.WebResource:contextMap={policyRegistration=org.jboss.security.plugins.JBossPolicyRegistration@76ed4518,securityConstraints=[Lorg.apache.catalina.deploy.SecurityConstraint;@6feeae6, resourcePermissionCheck=true},canonicalRequestURI=/restricted/get-only/x,request=[/web-constraints:cookies=null:headers=user-agent=Jakarta Commons-HttpClient/3.0,authorization=host=localhost:8080,][parameters=],CodeSource=null];securityConstraints=SecurityConstraint[RestrictedAccess - Get Only];Source=org.jboss.security.plugins.javaee.WebAuthorizationHelper;resourcePermissionCheck=true;Exception:=;
    An unsuccessful EJB invocation would look similar to the following audit.log output.

    Example 10.7. Unsuccessful Web Invocation log entry

    2008-12-05 16:08:41,561 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (http-127.0.0.1-8080-4:) [Failure]principal=anil;Source=org.jboss.web.tomcat.security.JBossWebRealm;request=[/jaspi-web-basic:cookies=null:headers=user-agent=Jakarta Commons-HttpClient/3.0,authorization=host=localhost:8080,][parameters=][attributes=];2008-12-05 16:07:30,129 TRACE [org.jboss.security.audit.providers.LogAuditProvider] (WorkerThread#1[127.0.0.1:55055]:)