Auditable security events

Auditable security events are security events with audit instrumentation that is added to the security runtime code to enable them to be recorded. Event filters are configured to specify which auditable security events are recorded to the audit log files.

The following list describes each valid auditable event that you can specify as an enabled event type when you create an event filter:
Table 1. Event types. Valid auditable events can be specified as an enabled event type when creating an event filter:
Event name Description
ADMIN_REPOSITORY_SAVE Depending on the outcome of the save, an audit record results. If needed, configure checkpoints.
SECURITY_AUTHN Audits all authentication events
SECURITY_AUTHN_MAPPING Audits events that record mapping of credentials where two user identities are involved
SECURITY_AUTHN_TERMINATE Audits authentication termination events such as a form-based logout
SECURITY_AUTHZ Audits events related to authorization checks when the system enforces access control policies
SECURITY_RUNTIME Audits runtime events such as the starting and the stopping of security servers. This event type is not meant for administrative operations performed by a system administrator as such operations need to use the other SECURITY_MGMT_* event types.
SECURITY_MGMT_AUDIT Audits events that record operations related to the audit subsystem such as starting audit, stopping audit, turning audit on or off, changing configuration of audit filters or level, archiving audit data, purging audit data, and so on.
SECURITY_RESOURCE_ACCESS Audits events that record all accesses to a resource. Examples are all accesses to a file, all HTTP requests and responses to a given web page, and all accesses to a critical database table
SECURITY_SIGNING Audits events that record signing such as signing operations used to validate parts of a SOAP Message for web services
SECURITY_ENCRYPTION Audits events that record encryption information such as encryption for web services
SECURITY_AUTHN_DELEGATION Audits events that record delegation, including identity assertion, RunAs, and low assertion. Used when the client identity is propagated or when delegation involves the use of a special identity. This event type is also used when switching user identities within a given session.
SECURITY_AUTHN_CREDS_MODIFY Audits events to modify credentials for a given user identity
SECURITY_FORM_LOGIN Audits events of the user being logged in and the remote IP address from which the login is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.login property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter. Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types.

SECURITY_FORM_LOGOUT Audits events of the user being logged out and the remote IP address from which the logout is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.logout property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter.Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types.

[8.5.5.21 or later]SECURITY_KERBEROS_LOGIN

Audits events of the user performing a web login into Kerberos and the remote IP address from which the login is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.login property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter. Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types.

[8.5.5.21 or later]SECURITY_KERBEROS_LOGOUT

Audits events of the user performing a web logout into Kerberos and the remote IP address from which the logout is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.logout property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter. Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types.

[8.5.5.21 or later]SECURITY_SPNEGO_LOGIN

Audits events of the user performing a web login into Spnego and the remote IP address from which the login is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.login property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter. Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types.

[8.5.5.21 or later]SECURITY_SPNEGO_LOGOUT

Audits events of the user performing a web logout into Spnego and the remote IP address from which the logout is initiated along with the timestamp and the outcome. To enable this event, the com.ibm.audit.terse.form.logout property needs to be configured in the audit.xml file. Currently this event is not shown in the administrative console, but the audit event is activated in the BinaryAudit.log file.

[z/OS]This event type cannot be used with the SMF based emitter. Use only the file-based emitter with this event type. If the SMF based emitter is selected, the events are stored in SMF, but the SMF unload utility, IRRADU00, cannot format out these event types

.

For each audit event type, you must specify an outcome. Valid outcomes include SUCCESS, FAILURE, REDIRECT, ERROR, DENIED, WARNING, and INFO. Not all outcomes are applicable with all event types.

The resulting audit event contains only the following details.
  • The timestamp
  • The ID of the user who is being logged in or out
  • The remote IP address from which the login or logout is initiated.
  • The outcome of the event

Terse audit record custom properties

The following properties support federal regulation compliance with minimal performance usage by allowing for the capture of web UI logins and logouts with a minimum amount of audit data. These properties must be manually specified in an audit.xml file and are not configurable through the administrative console or scripting.
com.ibm.audit.terse.form.login
The value for this property consists of a space-delimited list of valid outcomes. It enables the SECURITY_FORM_LOGIN event. Specify the outcomes to be included in this audit event in the value parameter.
[8.5.5.21 or later]In version 8.5.5.21 and later, the com.ibm.audit.terse.form.login property enables the SECURITY_FORM_LOGIN, SECURITY_KERBEROS_LOGIN, and SECURITY_SPNEGO_LOGIN audit events. Specify the outcomes to be included in these audit events in the value parameter. When this property is added in the audit.xml file, web logins to environments where Kerberos or SPNEGO are configured produce a minimum amount of audit data.
com.ibm.audit.terse.form.logout
The value for this property consists of a space-delimited list of valid outcomes. It enables the SECURITY_FORM_LOGOUT audit event. Specify the outcomes to be included in this audit event in the value parameter.
[8.5.5.21 or later]In version 8.5.5.21 and later, the com.ibm.audit.terse.form.logout property enables the SECURITY_FORM_LOGOUT, SECURITY_KERBEROS_LOGOUT, and SECURITY_SPNEGO_LOGOUT audit events. Specify the outcomes to be included in these audit events in the value parameter. When this property is added in the audit.xml file, web logouts from environments where Kerberos or SPNEGO are configured produce a minimum amount of audit data.
com.ibm.audit.terse.progname
[8.5.5.21 or later] When this property is set to true, the name of the application that is being logged in to and out of is included in the terse audit record. Valid values are true or false. By default, the application name is not included in the terse audit record.

Examples for setting audit custom properties in the audit.xml file

The following example shows an audit.xml file with both the com.ibm.audit.terse.form.login and com.ibm.audit.terse.form.logout properties set.
<?xml version="1.0" encoding="UTF-8"?>
<security:Audit xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:security="http://www.ibm.com/websphere/appserver/schemas/5.0/security.xmi" xmi:id="Audit_1173199825578">
  <auditSpecifications xmi:id="AuditSpecification_1173199825610" enabled="true" name="DefaultAuditSpecification_3">
    <event>SECURITY_AUTHN_TERMINATE</event>
    <outcome>SUCCESS</outcome>
    <outcome>REDIRECT</outcome>
    <outcome>FAILURE</outcome>
  </auditSpecifications>
  <auditPolicy xmi:id="AuditPolicy_1173199825608" auditEnabled="true" auditorId="sadie" auditorPwd="{xor}" sign="false" encrypt="false" batching="false" verbose="false">
    <auditEventFactories xmi:id="AuditEventFactory_1173199825608" name="auditEventFactoryImpl_1" className="com.ibm.ws.security.audit.AuditEventFactoryImpl" auditServiceProvider="AuditServiceProvider_1173199825608" auditSpecifications="AuditSpecification_1173199825610"/>
    <auditServiceProviders xmi:id="AuditServiceProvider_1173199825608" name="auditServiceProviderImpl_1" className="com.ibm.ws.security.audit.BinaryEmitterImpl" eventFormatterClass="" maxFileSize="10" maxLogs="100" fileLocation="$(LOG_ROOT)" auditSpecifications="AuditSpecification_1173199825610"/>
  <properties xmi:id="Property_1" name="com.ibm.audit.terse.form.login" value="SUCCESS FAILURE" description="custom property"/>
  <properties xmi:id="Property_2" name="com.ibm.audit.terse.form.logout" value="SUCCESS FAILURE ERROR" description=" custom property"/>
  </auditPolicy>
</security:Audit> 
In this example the custom properties are specified in the auditPolicy element. The Property_1 property (com.ibm.audit.terse.form.login) specifies that the SECURITY_FORM_LOGIN audit event is captured and that it is reported only for outcomes of either SUCCESS or FAILURE. The Property_2 property (com.ibm.audit.terse.form.logout) specifies that the SECURITY_FORM_LOGOUT audit event is captured and that it is reported for outcomes of SUCCESS, FAILURE, or ERROR.

[8.5.5.21 or later]In version 8.5.5.21 and later, Property_1 also captures the SECURITY_KERBEROS_LOGIN and SECURITY_SPNEGO_LOGIN audit events. Property_2 also captures the SECURITY_KERBEROS_LOGOUT and SECURITY_SPNEGO_LOGOUT audit events.

[8.5.5.21 or later]The following example shows an audit.xml file with both the com.ibm.audit.terse.form.login and com.ibm.audit.terse.form.logout properties set and the com.ibm.audit.terse.progname property set to true.
<?xml version="1.0" encoding="UTF-8"?>
<security:Audit xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:security="http://www.ibm.com/websphere/appserver/schemas/5.0/security.xmi" xmi:id="Audit_1173199825578">
  <auditSpecifications xmi:id="AuditSpecification_1173199825610" enabled="true" name="DefaultAuditSpecification_3">
    <event>SECURITY_AUTHN_TERMINATE</event>
    <outcome>SUCCESS</outcome>
    <outcome>REDIRECT</outcome>
    <outcome>FAILURE</outcome>
  </auditSpecifications>
  <auditPolicy xmi:id="AuditPolicy_1173199825608" auditEnabled="true" auditorId="sadie" auditorPwd="{xor}" sign="false" encrypt="false" batching="false" verbose="false">
    <auditEventFactories xmi:id="AuditEventFactory_1173199825608" name="auditEventFactoryImpl_1" className="com.ibm.ws.security.audit.AuditEventFactoryImpl" auditServiceProvider="AuditServiceProvider_1173199825608" auditSpecifications="AuditSpecification_1173199825610"/>
    <auditServiceProviders xmi:id="AuditServiceProvider_1173199825608" name="auditServiceProviderImpl_1" className="com.ibm.ws.security.audit.BinaryEmitterImpl" eventFormatterClass="" maxFileSize="10" maxLogs="100" fileLocation="$(LOG_ROOT)" auditSpecifications="AuditSpecification_1173199825610"/>
  <properties xmi:id="Property_1" name="com.ibm.audit.terse.form.login" value="SUCCESS FAILURE" description="custom property"/>
  <properties xmi:id="Property_2" name="com.ibm.audit.terse.form.logout" value="SUCCESS FAILURE ERROR" description="custom property"/>
<properties xmi:id="Property_3" name="com.ibm.audit.progname" value="true" description="custom property"/>
  </auditPolicy>
</security:Audit>

In this example the custom properties are specified in the auditPolicy element. The Property_1 property (com.ibm.audit.terse.form.login) specifies that the SECURITY_FORM_LOGIN, SECURITY_KERBEROS_LOGIN, and SECURITY_SPNEGO_LOGIN audit events are captured and that these audit events are reported only for outcomes of either SUCCESS or FAILURE. The Property_2 property (com.ibm.audit.terse.form.logout) specifies that the SECURITY_FORM_LOGOUT, SECURITY_KERBEROS_LOGOUT, and SECURITY_SPNEGO_LOGOUT audit events are captured and that these audit event are reported for outcomes of SUCCESS, FAILURE, or ERROR. The Property_3 property (com.ibm.audit.progname) specifies that the application name is included in the terse audit records.

[z/OS]

Audit filters, event outcomes, and descriptions for the system management facility (SMF) component

The following tables map the Security auditing event types and event outcomes to the SMF interpretations.

Table 2. Event Type SMF Codes. The following table lists the SMF code and unload keyword for each audit able security event.
Event name SMF Code SMF Unload Keyword
SECURITY_AUTHN 1 *WASAUTN
SECURITY_AUTHN_MAPPING 3 *WASAUTM
SECURITY_AUTHN_TERMINATE 2 *WASAUTT
SECURITY_AUTHZ 4 *WASAUTZ
SECURITY_RUNTIME 7 *WASRUNT
SECURITY_MGMT_AUDIT 13 *WASAUDI
SECURITY_RESOURCE_ACCESS 14 *WASACCE
SECURITY_SIGNING 15 *WASSIGN
SECURITY_ENCRYPTION 16 *WASCRYP
SECURITY_AUTHN_DELEGATION 17 *WASDELE
Table 3. Event Outcome SMF Qualifier. The following table lists the event outcome SMF Qualifier.
Event Outcome SMF Qualifier SMF Unload Keyword
SUCCESSFUL 0 SUCCESS
INFO 1 INFO
WARNING 2 WARNING
FAILURE 3 FAILURE
REDIRECT 4 REDIRECT
DENIED 5 DENIED
Table 4. SMF relocation to audit field mapping. The following table gives descriptions for the SMF relocation to audit field mapping.
Description SMF Qualifier SMF Unload Keyword
Last ID associated with a transaction.  Verbose mode content. 100 eventLastTrailId
A unique identifier associated with a transaction that can be used to correlate events 101 eventTrailId
A date stamp of the event. For format and value ranges, refer to your JDK's API documentation for Date.toString(). 102 eventCreationTime
Unique identifier of this event 103 eventide
Custom field (See Note after the table) 104 eventCustom
ID for the user’s session 105 sessionId
IP for outcomes the remote host 106 sessionRemoteAddress
Port of the remote host 107 sessionRemotePort
Hostname of the remote host 108 sessionRemoteHost
Custom field (See Note after the table) 109 sessionCustom
Name of the program that is involved in this event 110 accessProgram
What action specific to the event type is being performed. 111 accessAction
User’s name in the registry 112 accessRegistryUser
User’s name within a given application 113 accessApplicationUser
What is the decision of the authorization call. 114 accessDecision
Name of the resource in the context of the application 115 accessNameInApplication
Type of the resource 116 accessResourceType
Resource’s unique identifier 117 accessResourceId
Permissions that are being checked during the authorization call 118 accessPermissionChecked
Permissions that are granted 119 accessPermissionGranted
Roles being checked 120 accessRoleChecked
Roles granted 121 accessRoleGranted
Custom field (See Note after the table) 122 accessCustom
Identity of first user in caller list 123 callerFirst
List of names representing the user’s identities, after the first user. Verbose mode content. List format "Name1, Name2, Name3" 124 caller
Custom field (See Note after the table) 125 callerCustom
Domain user belongs to Verbose mode content. 126 domain
The registry partition that the user belongs to 127 realm
Custom field (See Note after the table) 128 processCustom
Type of registry (LDAP, AIX, and so on.) 129 registryType
Custom field (See Note after the table) 130 registryCustom
runAsClient, runAsSpecified, runAsSystem 131 delegationType
Run as role 132 delegationRole
The user ID is used as a result of the delegated role, that is, the caller identity or the system identify, and so on. 133 delegationUserInformation
Custom field (See Note after the table) 134 delgationCustom
Type of authentication (depends on arthroscope). Possible authentication types:challengeResponse, returnResponse, trustRelationship, transportLayer, spnego, basicAuth; 135 authenticationType
Custom field (See Note after the table) 136 authenticationCustom
Provider of the authentication or authorization service 137 provider
Was the authentication or authorization  event processed successfully by the provider? 138 providerStatus
Custom field (See Note after the table) 139 providerCustom
Indicates the security domain after mapping 140 mappedDomain
Indicates the realm after mapping 141 mappedRealm
Indicates the username after mapping 142 mappedUser
Custom field (See Note after the table) 143 mappedCustom
Reason for termination 144 terminateReason
Custom field (See Note after the table) 145 terminateCustom
Name of the policy 146 policy
Type of the policy 147 policyType
Custom field (See Note after the table) 148 policyCustom
The key or certificate label 149 keyLabel
Physical location of the key database 150 keyLocation
The date stamp of the certificate's expiration. For format and value ranges, refer to your JDK's API documentation for Date.toString(). 151 keyCertLifetime
Custom field (See Note after the table) 152 keyCustom
Type of management operation. Possible management types: server, subSystem, config, notification, WASServer, AuditSubSystem, SecurityServer 153 managementType
What application-specific command is being performed. 154 managementCommand
Information about one or more secondary objects that are involved in this operation. Verbose mode. List is a comma and space separated list of management attribute names and UIDs as key-value pairs, that is, MgmtAttrName1 = nameValue1, MgmtAttrUid1 = uidValue1, MgmtAttrName2 = nameValue2, MgmtAttrUid2 = uidValue2, … 155 managementAttribute
Custom field (See Note after the table) 156 managementCustom
URL of the http request 157 requestUrl
HTTP request headers given by the client. Verbose mode content. 158 requestHeaders
HTTP response headers returned by the server. Verbose mode content. 159 responseHeaders
Custom field (See Note after the table) 160 responseCustom
Note: Custom fields are Key-value pairs of data that is provided by user-defined CustomPropertyContextObj objects. For more information, see Context object fields. Output is in the form of a string of key-value pairs and the prefix Extended_ is prepended to each key name. However, the pairs are printed in a different format by the binary emitter compared to the SMF emitter. For example, given the key-value pairs {abc:value1},{def:value2},{ghi:value3}. The binary emitter outputs: Extended_abc = value1 | Extended_def = value2 | Extended_ghi = value3. The SMF emitter outputs: customKey: Extended_abc customValue: value1, customKey: Extended_def customValue: value2, customKey: Extended_ghi customValue: value3