CSI Audit Generation and Configuration

CSI provides audit trail generation and configuration.

An audit destination may write an audit record to a file. All audit destinations have the ability to use an audit formatter, although they may be configured to ignore this if they do their own formatting. Audit destinations may be configured to initialize a default formatter. Audit destinations must be thread safe, unlike other CSI providers. CSI guarantees that each audit destination is created only once per factory instance.

However, it may be desirable for an audit destination to be aware of other instances of itself instantiated in the same VM and ensure that these instances appropriately share access to common resources, such as audit files. Audit destinations may also add additional attributes to the audit record, such as a sequential record ID, to guard against log tampering or signature attributes that can be later verified to check for audit record tampering.

The primary sources for generating audit records are:

CSI core classes perform a variety of operations that generate audit records. Examples of events that are audited include authentication and authorization decisions, self registration attempts, and configuration information such as active provider sets.
Providers may audit additional information about the operations to which they contribute. An example of extra information might be an extended response from the authentication server that indicates why an operation failed in more detail.

Providers that need to issue audit records can take advantage of auditing APIs defined in the com.sybase.security.providers.ProviderServices interface. Those audit APIs require the provider pass in an audit token. This token identifies which provider is issuing the audit request. The provider can retrieve and save this token from the provider configuration using the constant ProviderConst.AUDIT_TOKEN_CONFIG_PROPERTY in the provider's init() method or a LoginModule's initialize method.

An audit record includes five common parts:

timestamp - the time at which the event occurred
resource class - the scope used when processing the resource ID
resource ID - the object on which an operation is being performed
action - the operation that is being performed
decision - the result of the security check

The decision has four potential values: PERMIT, DENY, ABSTAIN or NOTAPPLICABLE. The NOTAPPLICABLE decision is used for those cases where the audit is an event rather than a security decision.

In addition to the core of the audit record, there are additional attributes. These attributes vary with the type of audit record being generated but may include context ID, provider identifier, and failure reason.

The auditing providers consist of the following configurable components:

The com.sybase.security.provider.AuditDestination interface defines APIs for the audit destination component, which decides where to write audit record. The framework includes a simple file-based audit destination component, com.sybase.security.core.FileAuditDestination, that uses an audit formatter to retrieve a string representation of the audit record, and writes it to a file.
The com.sybase.security.provider.AuditFilter interface defines APIs for audit filtering components, which decide whether an audit record should be audited or not. The default filter component, com.sybase.security.core.DefaultAuditFilter, adopts a filter string to perform audit record filtering. The syntax for the filter consists of zero or more filter expressions, delimited by parenthesis (brackets denote optional values). For example, (expr1)[(expr2)...]. Each of these expressions has syntax like the following: [key1=value [,key2=value...]]. The allowed keys are: ResourceClass, Action, and Decision. For example, filter string (ResourceClass=core.*,Decision=Deny) enables auditing all of the CSI core resource classes involved in a deny decision.

The default formatter, com.sybase.security.core.XmlAuditFormatter, stores the audit record in one type of XML format. Each audit destination component is associated with one audit filter and one audit formatter. The framework supports an audit destination control flag scheme similar to Java's JAAS LoginModule control flags of required, requisite, sufficient, and optional.

Control Flag Settings for AuditDestination
Control Flag Value	Description
Required	If the audit filter associated with the destination enables logging a particular event, the audit record is always logged to the audit destination, and the logging must succeed. Regardless of whether or not the audit record is successfully logged to the destination, the other configured audit providers are invoked.
Requisite	If the audit filter associated with the destination enables logging a particular event, the audit record is required to be successfully logged to the audit destination. If the audit record is successfully logged to the audit destination provider, subsequent providers are executed but can fail (except for providers with the JAAS control flag set to required).
Sufficient	If the audit filter associated with the destination enables logging a particular event, the audit record is not required to be successfully logged to the audit destination. However, if the audit record is successfully logged by the provider, no subsequent providers are executed. If audit record logging fails, the audit filter proceeds down the list of configured providers.
Optional	If the audit filter associated with the destination enables logging a particular event, the logging of the audit record by the provider is allowed to succeed or fail. However, if all the audit destination providers are configured with control flag set to optional, the audit record must be successfully logged by at least one provider.

Note: The audit results are combined in the same way authentication results of login modules are combined to decide if the authentication succeeds or not overall. If the combined audit result fails, then the security operation being audited fails. For example, if an authorization check is audited and the audit filter is set up to log that event, the authorization check fails if the audit record cannot be successfully logged even if the authorization provider returns VOTE_YES.