Context Navigation

Log Audit Record

This section provides developers with information on how to log an audit record. Documentation for the REST protocol, as well as code samples for Java, PHP, and cURL, are provided below.

Audit Record Composition

An audit record has the following components.

Event Code. This identifies the type of audit-able event that occurred. There is a set of generic event codes defined in the org.eclipse.higgins.audit.api.AuditEvents class. This set of event codes matches the event taxonomy specified in OpenXDAS. This set of events is likely to meet most applications' auditing needs. This gives analysis tools the ability to focus on analysis, and spend less time on disparate event type and event data correlation. It's often the case that events generated by various applications are either not documented well, or not documented at all, making the correlation issue risky and error prone. By providing a standardized generic event taxonomy, both application developers and analysis tool writers can easily understand the intended meaning of a given generic event. While the XDAS working group tried to define a set of generic events that would meet most needs, they also understood that this was unlikely to satisfy every auditing need, an application may specify one's own event codes. While the intended semantic meaning of a given event may seem obvious at first glance, many applications may not fit the paradigm of traditional security or identity applications, but still the developers or architects of the application feel the need to generate audit events. We submit that if such a need is felt by product architects, then there's probably a good reason for it – the application most likely manages non-traditionally structured security or identity information, making it difficult to see the connection easily. For example, many applications may not create what one might consider to be a traditional user account, and it appears quickly evident to developers of such applications that XDAS generic events simply don't fit with their particular application's needs. However, as the documentation below tries to convey, the developer should try to mentally reclassify the act of account creation into a more generic operation, for this is in fact the intended meaning of account creation from the XDAS perspective.
Outcome Code. This is a standardized event outcome code. These are defined in the org.eclipse.higgins.audit.api.AuditOutcomes class and match those defined by the XDAS specification. The outcome codes are broken into four subsets:
- No Outcome Specified. This subset contains only the value 0xFFFFFFFF, and represents the developer's choice not to specify the outcome code at this time. This is necessary, as the outcome of an event may not be known at the time the event record is initially created.
- Success. This subset indicates success in one way or another. The first value is the primary successful outcome code, and has the special value 0 (zero), which indicates unqualified success.
- Failure. This subset represents various types of operation failure. Note the difference between failure and denial (the final subset). Denial may be considered by some to be a special class of failure codes, and indeed, it is. But XDAS treats denial as a separate class of outcome for ease of analysis.
- Denial. This subset is the set of denial outcome codes. Denial codes represent various types of “permission denied” responses.
Originator. The originator of an audit record is the service that is detecting the audit-worthy event, and requesting the recording of the event. In the context of submitting events from within an instrumented application, the originator then is the identity under which the submitting application is acting, relative to the authority or security realm from which that identity is obtained. The originator is comprised of the following components:
- Originator Location Name. This is the name of the host or service that is reporting the event. It may be as simple as host/service, for example: "waldo/apache".
- Originator Location Address. This is a communication service end point address, which may be a URL, or other type of address that fully specifies a connection point, for example: "http://waldo.mycorp.com".
- Originator Service Type This is the protocol used by the Originator Location Address, for example: "http". One should, under ideal circumstances, be able to establish a communication channel to the originator using the combined data in this component and the Originator Location Address.
- Originator Authentication Authority. This is the name of a server, or domain and realm that provides the identities involved in the associated events. A Unix host name is a good example of an authentication authority. Any service that manages an identity database with authoritative control of a security domain is a valid authentication authority, for example: "waldo".
- Originator Principal Name. This is the user name relative to the Originator Authentication Authority. For example, if the application is the Apache web server, then the Originator Principal Name might be the name of the Unix user account under which Apache is running, or simply “root” if the Apache server is not running under any specific user account. The Originator Principal Name is optional, and may be left empty.
- Originator Principal ID. This is the user id of the principal, relative to the authentication authority. In the example above using Apache, the root user ID might just be 0. On Win32 systems, this might be the GUID of the user under which IIS is running.
Initiator. The initiator is the user or identity that caused the audit-able event. A user logging in through a web server for instance, is an iniatator. (The account under which the web service is running is the originator in this case.) The initiator is comprised of the following components:
- Initiator Authentication Authority. This is the host, service, or domain and realm name of the authentication service that provides the identity attributes for the initiator of an audit-able action, for example: "waldo/nfs".
- Initiator Domain-Specific Name. This is the name of the user or identity that is initiating an audit-able action, relative to the Initiator Authentication Authority, for example "joe". This component is optional.
- Initiator Domain-Specific ID. This is the identifier (uid, guid, etc.) of the user or identity that is initiating the audit-able action, relative to the Initiator Authentication Authority, for example the user name "joe" might have a uid of 15.
Target. The target is the object being acted upon during the audit-able event. For example, a user whose rights are being modified through a web management interface is a target. Be aware that some events don't have a discernible target. The components of the target are similar to the Originator components described above, except these fields indicate information about the object being acted upon, not the actor. The target, if present, is comprised of the following components:
- Target Location Name. This is the name of the target resource, host or service of the event that is being reported, for example "waldo/apache".
- Target Location Address. This is a communication service end point address, which may be a URL, or other type of address that fully specifies a connection point, for example: "http://waldo.mycorp.com/index.html".
- Target Service Type. This indicates the protocol used by the Target Location Address, for example: "http".
- Target Authentication Authority. This is the name of a server, or domain and realm that provides the identities involved in the associated events. The target authentication information may be left empty. A Unix host name is a good example of an authentication authority, for example: "waldo".
- Target Principal Name. This is the user name relative to the Target Authentication Authority. For example, if the application is the Apache web server, then the Target Principal Name might be the name of the Unix user account under which Apache is running, or "root" if not running under any user account. The Target Principal Name is optional.
- Target Principal ID. This is the user id of the target principal, relative to the authentication authority.

IMPORTANT NOTE: Not all events have a target with an associated identity. For example, a file being downloaded from an ftp site might be a target, but there may be no identity information associated with the file, so the Target Authentication Authority, Target Principal Name, and Target Principal ID components would be left empty.

Event Specific Data. This is designed to carry additional information that is specific to the application domain. It is optional. If present, it consists of a series of name/value pairs, for example: "MyParam1=Value1,MyParam2=Value2".

REST

The REST noun (and associated message content) for authenticating a user and creating a new session is as follows:

Relative Noun: /AuditLog. This is the relative path of the URL that should appear after the OTIS server application name. For example:

https://wag.bandit-project.org/otis/AuditLog

HTTP Method: PUT.
Request/Response message details: click here
Description: Logs an audit record to the audit log. The audit record to be logged is provided in the content of the request (see details here).

Java

The following is example Java code that demonstrates how to create and log an audit record:

import org.eclipse.higgins.audit.api.AuditRecord;
import org.eclipse.higgins.audit.api.AuditEvents;
import org.eclipse.higgins.audit.api.AuditOutcomes;
import org.eclipse.higgins.audit.api.AuditException;

try
{

    // The session variable is an IAuthSession object.  The code below obtains an "empty" audit record.

    AuditRecord   auditRecord = session.getAuditRecord();

    // Set various components of the audit record

    auditRecord.setOriginatorInfo( "waldo/apache", "http://waldo.mycorp.com", "http", "waldo", "root", "0");
    auditRecord.setEventNumber( AuditEvents.AE_QUERY_ACCOUNT);
    auditRecord.setOutcome( AuditOutcomes.AUDIT_OUT_SUCCESS);
    auditRecord.setInitiatorInfo( "waldo/nfs", "joe", "15");
    auditRecord.setTargetInfo( "waldo/apache", "http://waldo.mycorp.com/index.html", "http", "waldo", null, null);
    auditRecord.addEventInfo( "MyParam1", "value1");
    auditRecord.addEventInfo( "MyParam2", "value2");

    // Log the audit record

    session.logAuditRecord( auditRecord);
}
catch (AuditException exception)
{
    System.out.println("AuditException: " + exception);
}
catch (AuthSessionException exception)
{
    System.out.println("AuthSessionException: " + exception);
}

The OTIS client Java library may be downloaded from the OTIS download page.

PHP

The following is PHP example code of how to log an audit record:

//Generate an xml for use in the body of the PUT
$xml =
'<?xml version="1.0" encoding="UTF-8"?>
<tns:AuditLogRecord xmlns:tns="http://code.bandit-project.org/schemas/2008/otis">
   <!--
      Create an audit log record
   -->
   <tns:AuditOrigLocationName>waldo/apache</tns:AuditOrigLocationName>
   <tns:AuditOrigLocationAddress>http://waldo.mycorp.com</tns:AuditOrigLocationAddress>
   <tns:AuditOrigServiceType>http</tns:AuditOrigServiceType>
   <tns:AuditOrigAuthAuthority>waldo</tns:AuditOrigAuthAuthority>
   <tns:AuditOrigPrincipalName>root</tns:AuditOrigPrincipalName>
   <tns:AuditOrigPrincipalIdentity>0</tns:AuditOrigPrincipalIdentity>
   <tns:AuditEventNumber>0x01000005</tns:AuditEventNumber>
   <tns:AuditOutcome>0</tns:AuditOutcome>
   <tns:AuditAuthAuthority>waldo/nfs</tns:AuditAuthAuthority>
   <tns:AuditDomainSpecificName>joe</tns:AuditDomainSpecificName>
   <tns:AuditDomainSpecificId>15</tns:AuditDomainSpecificId>
   <tns:AuditTargetLocationName>waldo/apache</tns:AuditTargetLocationName>
   <tns:AuditTargetLocationAddress>http://waldo.mycorp.com/index.html</tns:AuditTargetLocationAddress>
   <tns:AuditTargetServiceType>http</tns:AuditTargetServiceType>
   <tns:AuditTargetAuthAuthority>waldo</tns:AuditTargetAuthAuthority>
   <tns:AuditEventInfoList>
      <tns:AuditEventInfo>
         <tns:AuditEventInfoName>MyParam1</tns:AuditEventInfoName>
         <tns:AuditEventInfoValue>value1</tns:AuditEventInfoValue>
      </tns:AuditEventInfo>
      <tns:AuditEventInfo>
         <tns:AuditEventInfoName>MyParam2</tns:AuditEventInfoName>
         <tns:AuditEventInfoValue>value2</tns:AuditEventInfoValue>
      </tns:AuditEventInfo>
   </tns:AuditEventInfoList>
</tns:AuditLogRecord>';

$length = strlen($xml);
$Host = "wag.bandit-project.org";

// Generate the request header using an xml 
$ReqHeader =
"PUT /otis/AuditLog HTTP/1.1\n".
"Host: $Host\n".
"Content-Type: application/x-www-form-urlencoded\n".
"Content-Length: $length\n".
"Connection: Close\n\n".
"$xml\n";

// Open the connection to the host
$socket = fsockopen("wag.bandit-project.org", 80);

// Do the POST; store in "Result".  "Result" can be looked at to see what the session ID is.
fputs($socket, $ReqHeader);
while (!feof($socket)) 
{
   $tmp = fgets($socket, 128);
   //if the line contains an xml tag, add it
   if(strpos($tmp, ">"))
   {
      $Result .= $tmp;
   }
}

cURL

The following sample code authenticates a user by using a username and password. This code includes line continuations that work on Linux.

curl -X PUT -d \
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<tns:AuditLogRecord xmlns:tns=\"http://code.bandit-project.org/schemas/2008/otis\">
        <!--
                Create an audit log record
        -->
        <tns:AuditOrigLocationName>waldo/apache</tns:AuditOrigLocationName>
        <tns:AuditOrigLocationAddress>http://waldo.mycorp.com</tns:AuditOrigLocationAddress>
        <tns:AuditOrigServiceType>http</tns:AuditOrigServiceType>
        <tns:AuditOrigAuthAuthority>waldo</tns:AuditOrigAuthAuthority>
        <tns:AuditOrigPrincipalName>root</tns:AuditOrigPrincipalName>
        <tns:AuditOrigPrincipalIdentity>0</tns:AuditOrigPrincipalIdentity>
        <tns:AuditEventNumber>0x01000005</tns:AuditEventNumber>
        <tns:AuditOutcome>0</tns:AuditOutcome>
        <tns:AuditAuthAuthority>waldo/nfs</tns:AuditAuthAuthority>
        <tns:AuditDomainSpecificName>joe</tns:AuditDomainSpecificName>
        <tns:AuditDomainSpecificId>15</tns:AuditDomainSpecificId>
        <tns:AuditTargetLocationName>waldo/apache</tns:AuditTargetLocationName>
        <tns:AuditTargetLocationAddress>http://waldo.mycorp.com/index.html</tns:AuditTargetLocationAddress>
        <tns:AuditTargetServiceType>http</tns:AuditTargetServiceType>
        <tns:AuditTargetAuthAuthority>waldo</tns:AuditTargetAuthAuthority>
        <tns:AuditEventInfoList>
                <tns:AuditEventInfo>
                        <tns:AuditEventInfoName>MyParam1</tns:AuditEventInfoName>
                        <tns:AuditEventInfoValue>value1</tns:AuditEventInfoValue>
                </tns:AuditEventInfo>
                <tns:AuditEventInfo>
                        <tns:AuditEventInfoName>MyParam2</tns:AuditEventInfoName>
                        <tns:AuditEventInfoValue>value2</tns:AuditEventInfoValue>
                </tns:AuditEventInfo>
        </tns:AuditEventInfoList>
</tns:AuditLogRecord>" \
 https://wag.bandit-project.org/otis/AuditLog/

Expected response: None

Download in other formats:

Plain Text