Audit 1.0

The Audit feature is used to report and track auditable events to ensure the integrity of your system.

The Audit feature introduces an infrastructure that serves two purposes: - Confirming the effectiveness and integrity of the existing configuration - Identifying areas where improvement to the configuration may be needed

The Audit feature can capture a range of auditable events, including events related to authentication, authorization, and logout. The feature provides a default implementation, the AuditFileHandler, which emits human-readable audit records to a file-based log. Each audit record is emitted in JSON format.

Enabling this feature

To enable the Audit 1.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>audit-1.0</feature>

Examples

Audit File Handler

The audit file handler is made available by specifying the audit-1.0 feature. It can be customized by specifying any of the config attributes, along with the <auditFileHandler> element. For more information, see Default Audit File Handler.

When the maximum number of archived audit logs is reached, after the audit.log file that is being written to reaches its maximum size, then the oldest archived audit log is overwritten.

The following example shows an Audit file handler with maxFiles, maxFileSize, and compact mode specified:

<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>[.underline]#jsp#-2.2</feature>
    <feature>[.underline]#servlet#-3.1</feature>
    <feature>audit-1.0</feature>
    <feature>[.underline]#timedexit#-1.0</feature>
</featureManager>

<auditFileHandler maxFiles="50" maxFileSize="100" compact=”true”>
</auditFileHandler>

In the example, the audit logs are written to the default $\{server.output.dir}/logs directory. Each audit file has a maximum 100 MB size before they are archived and new audit records are written to a new audit.log file. The maximum number of archived audit logs is 50. Once 50 audit logs are archived, and the current audit.log file that is written to reaches the 100 MB size, then the oldest archived audit.log file is overwritten.

All audit events and possible outcomes are emitted to the audit logs.

Events

To specify only those audit events and outcomes that may be of relevance in an environment, the <event> element can be defined with the audit event name and outcome:

The following example specifies audit events and outcomes:

<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>[.underline]#servlet#-4.0</feature>
    <feature>audit-1.0</feature>
</featureManager>

<auditFileHandler maxFiles="5" maxFileSize="20" compact="true">
    <events name="AuditEvent_1" eventName="SECURITY_AUTHN" outcome="SUCCESS"/>
    <events name="AuditEvent_2" eventName="SECURITY_AUTHN" outcome="REDIRECT"/>
    <events name="AuditEvent_3" eventName="SECURITY_AUTHN" outcome="FAILURE"/>
    <events name="AuditEvent_4" eventName="SECURITY_AUTHZ"/>
</auditFileHandler>

In the example, only the security authentication events whose outcome is success, redirect, or failure, and security authorization events whose outcome includes all supported outcomes are captured.

If an event is specified with only an outcome attribute, with no eventName specified, then no audit records are produced. However, an eventName can be specified without an outcome attribute, in which case all possible outcomes for that eventName are emitted.

Encrypting and Signing Audit

It is important for the recorded audit data to be preserved in such a way that not only can the access be restricted but also so that the data itself is tamper-proof. The ability to both encrypt and sign the audit records data is provided.

To encrypt audit records, the encrypt attribute must be specified in the auditFileHandler element, along with the alias name of the certificate that is used to encrypt the audit data, and the keystore in which that certificate exists.

To sign audit records, the sign attribute must be specified in the auditFileHandler element, along with the alias name of the certificate that is used to sign the audit data, and the keystore in which that certificate exists.

SHA256withRSA is used as the default crypto algorithm for both encryption and signing. The following example shows the audit file handler with encryption and signing enabled:

<featureManager>
    <feature>appSecurity-2.0</feature>
    <feature>[.underline]#jsp#-2.2</feature>
    <feature>[.underline]#servlet#-3.1</feature>
    <feature>audit-1.0</feature>
</featureManager>

<keyStore id="auditEncKeyStore” password="Liberty" location="$\{server.config.dir}/resources/security/AuditEncryptionKeyStore.jks" type="JKS" />

<keyStore id="auditSignKeyStore" password="\{[.underline]#xor#}EzY9Oi0rJg==" location="$\{server.config.dir}/resources/security/AuditSigningKeyStore2.[.underline]#jks#" type="JKS" />

<auditFileHandler encrypt="true" encryptAlias="[.underline]#auditencryption#" encryptKeyStoreRef="auditEncKeyStore" sign="true" signingAlias="auditsigning2" signingKeyStoreRef="auditSignKeyStore"
</auditFileHandler>

All audit events and possible outcomes are emitted to the audit logs.

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-14.0

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

com.ibm.websphere.appserver.audit-1.0; type="osgi.subsystem.feature"