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. 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. 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_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. 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_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. 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_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. 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_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. 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.; 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.; 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: 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.

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.

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