4
SOAP Audit Logging

The Oracle SOAP audit logging feature monitors and records SOAP usage. Audit logging maintains records for postmortem analysis and accountability. SOAP The SOAP audit logging feature complements the audit logging capabilities available with the transport-specific server, the Apache HTTP listener, which hosts the SOAP Request Handler Servlet (SOAP server).

Oracle SOAP stores audit trails as XML documents. Using XML documents, Oracle SOAP creates portable audit trails and enables the transformation of audit trails or individual audit records to different formats.

By default, Oracle SOAP audit logging uses an audit logger class that implements the Handler interface (part of the oracle.soap.server package). The audit logger class is invoked conditionally to monitor events including service requests, service responses, and errors.

This chapter covers the following topics:

• Audit Logging Information

• Auditable Events

• Configuring the Audit Logger

Audit Logging Information

Table 4-1 lists the audit logging elements available for each audit log record. Individual audit log records may not contain all these elements. In the log file, each audit log record is stored as a SoapAuditRecord element.

Table 4-1  Available Audit Record Elements

Audit Record Element	Description
HostName	Specifies the hostname of the client that sent the request.
IpAddress	Specifies the IP address of the client that sent the request.
Method	Specifies the method name for the SOAP request.
Request	Provides the complete SOAP request message.
Response	Provides the complete SOAP response message.
ServiceURI	Specifies the service URI, for the SOAP request.
SoapAuditRecord	Contains an individual record. The chainType attribute indicates if the record is generated as part of a request or a response.
TimeStamp	SPecifies the system time when the SOAP audit record was generated.
User	Specifies the username associated with the request. Note, this element is only provided when a user context is associated with the service request or service response.

Audit Logging Output

The XML schema for the generated audit log is provided in the file SoapAuditTrail.xsd in the directory $SOAP_HOME/schema on UNIX or %SOAP_HOME%\schema on Windows NT. Refer to the schema file for complete details on the format of a generated audit record.

Auditable Events

The audit logger class is invoked when an auditable event occurs and the SOAP Request Handler Servlet is configured to enable auditing for the event. Auditable events include a service request or a service response.

Audit Logging Filters

An audit logging filter can be added to the SOAP configuration file to specify the set of auditable events that are recorded to the audit log. The SOAP server applies event filters to request and response events. Table 4-2 shows the filter attributes that a filter selects for an audit logger event filter specification. When applied, filters limit the number of records generated in the audit log. For example, when a filter is specified for a particular host, only the auditable events that are generated for the specified host are saved to the audit log.

The filter syntax for defining auditable events is derived from RFC 2254. Table 4-3 shows the filter syntax, and Example 4-1 provides several examples.

See Also: "Configuring the Audit Logger"

Table 4-2  Audit Trail Events Filter Attributes

Audit Event Filter Attributes	Description
Host	Specifies the hostname of the host for the service request or response. If this attribute is not used in a filter, the hostname of the client is not used in filtering. Fully specify the hostname of the client or use wildcards ("*"). Wildcards embedded within the specified hostname are not supported (see the examples below showing valid and invalid uses of wildcards). If a wildcard is used then the wildcard must be the first character in the filter. Case is ignored for hostnames. Care should be used in setting this attribute. Depending on the DNS setup, the hostname returned could be fully qualified or nonqualified; for example, explosives.acme.com or explosives. For some IP addresses, the DNS may not be able to resolve the hostname. Legal values for a host filter include the following examples: explosives.acme.com, *.acme.com, *.com Illegal values for a host filter include the following examples: *, explosives.acme.*, explosives.*, ex*s.acme.com, *ives.acme.com
ip	Specifies the IP address of the client for the service request or response. The IP address of the client has to be either specified fully, using all four bytes, in the dot separate decimal form, or specified using wildcards ("*"). Embedded wildcards are not supported. If a wildcard is used then the wildcard must be the last character in the filter. If this attribute is not used in a filter then the IP address of the client is not used in filtering. Examples of legal values: 138.2.142.154, 138.2.142.*, 138.2.*, 138.* Examples of illegal values: *, 138.2.*.154, *.2, 138.*.152, 138.2.142, 138.2, 138
urn	Specifies the service URN. Wild cards are not supported for this attribute.
username	Specifies the transport level username associated with the client. Wild cards are not supported in a username filter attribute.

Table 4-3  Audit Log Filter Syntax

Filter Value	Description
filter	"("filtercomp")" Whitespaces between "("filtercomp and ")" are not allowed.
filtercomp	and | or | not | item and = "&" filterlist or = "|" filterlist not = "!" filter
filterlist	2*2 filter
item	attr filtertype value Whitespaces between attr, filtertype and value are not allowed.
filtertype	equal
equal	"="
attr	1*(any US-ASCII char except "*", "(", ")", "&", "|", "!", "*", "=")
value	1*(any octet except ASCII representation of ")" - 0x29). The character "*" has a special meaning. The "*" character is referred to as a wildcard and matches anything.

Example 4-1 Audit Log Filters

(ip=138.2.142.154) 
(!(host=localhost))
(!(host=*.acme.com))
(&(host=*.acme.com)(username=daffy))
(&(ip=138.2.142.*)(|(urn=urn:www-oracle-com:AddressBook)(username=daffy))) 

Configuring the Audit Logger

Configure the default SOAP Audit Logger supplied with Oracle SOAP by setting parameters in the SOAP configuration file, soapConfig.xml. To enable the default audit logger and turn on audit logging, do the following in the configuration file.

• Define the name and options for the audit log handler. The default SOAP audit logger is defined in the class oracle.soap.handlers.audit.AuditLogger. The default audit logger supports several options that you specify in the configuration file. Table 4-4 shows the available audit logger options.

• Add the audit logging handler name to the requestHandler, responseHandler, or errorHandler chain (or to all of the handler chains).

Example 4-2 shows a sample segment from a SOAP configuration file including the audit logging configuration options. Example 4-2 shows configuration options set to use all options. However, this configuration would produce an extremely large audit log, and is not recommended.

Note: When you audit errors using the audit logger, it is possible that the request or response message may not be included in the audit log record, even with includeRequest or includeResponse enabled.

Example 4-2 Audit Logging Configuration

<osc:handlers>
   <osc:handler name="auditor"
      class="oracle.soap.handlers.audit.AuditLogger">
      <osc:option name="auditLogDirectory"
           value="/private1/oracle/app/product/tv02/soap/webapps/soap/WEB-INF"/>
      <osc:option name="filter" value="(!(host=localhost))"/>
      <osc:option name="includeRequest" value="true"/>
      <osc:option name="includeResponse" value="true"/>
   </osc:handler>
</osc:handlers>
<osc:requestHandlers names="auditor"/>
<osc:responseHandlers names="auditor"/>
<osc:errorHandlers names="auditor"/>

Table 4-4 Audit Logger Configuration Options

Option	Description
auditLogDirectory	Specifies the directory where the audit log file is saved. The auditLogDirectory option is required. The name of the generated audit log file is OracleSoapAuditLog.timestamp, where timestamp is the date and time the file is first generated. Valid values: any string that is a valid directory
filter	Specifies the audit event filter. The audit event filter option is optional. If filter is not specified SOAP server logs every event. Valid values: any that is a valid filter.
includeRequest	Specifies that the audit record include the request message for the event that generated the audit log record. Valid values: true, false Any value other than true or false is treated as an error. Default Value: false
includeResponse	Specifies that the audit record include the response message for the event that generated the audit log record. Valid values: true, false Any value other than true or false is treated as an error. Default Value: false

See Also: "Configuring the Request Handler Servlet"