CEE Profile Specification

Specifications		Search

CEE Website is in "Archive" status — read the announcement

CEE Language
Current Release Specifications Schemas Downloads Profiles Versioning Terminology Implementations Additional Information Previous Releases Terms of Use

Additional Information

Previous Releases

CEE Profile Specification v1.0α

Introduction

The purpose of the CEE Profile is to improve the audit process and users' ability to effectively interpret and analyze event log and audit data. This is accomplished by defining an extensible unified event structure, which users and developers can leverage to define and describe their event structures.

The CEE Event structure consists of a common header, an extensible body profile, and zero or more modules. The header is a collection of fields that are required by all events, such as the time and event producer information. The profile is the core of an event. A profile is defined by the user or developer, and provides the specific fields and data unique to that type of event.

A CEE Event and Event Profile structure is made up of reusable components: fields, field types, and event tags. The Field Dictionary provides consistent recording of event characteristics by reusing common event field definitions. The Event Taxonomy defines lists of event tags and categories, which allow events to be identified and categorized based on the type of event.

Many of the CEE Profile components are defined in XML Schema. These schemas and more can be found in the cee.xsd, dictionary.xsd, and taxonomy.xsd schemas.

CEE Profile

The CEE Profile provides a unified and extensible interface to event users. It consists of three (3) major components, each of which is defined in an XML Schema document:

Event Taxonomy (taxonomy.xsd)
Field Dictionary (dictionary.xsd)
CEE Event & Event Profile Schema (cee.xsd)

Figure 1: Profile XML Schema Documents

The CEE Event definition defines the minimum structure of a CEE Event, an Event and zero or more Event Modules. Event Modules provide a mechanism that allows for the supplementing of additional data or features to a CEE Event.

The Event Taxonomy provides a listing of tags that can be used to classify and identify similar event types. The Field Dictionary is a listing of fields that should be used to represent common event data.

CEE Event

A CEE Event contains exactly one event block and zero or more event modules. Each event block consists of a common group of header fields, a Type block, and an extensible Profile block. Event modules are defined in the Module section and provide a method of supplementing of extending the event capabilities with features such as non-destructive event augmentation or integrity validation using digitial signatures.

Figure 2: CEE Event Structure

The XML representation of a CEE Event is defined below using XML Schema, and may also be found in the cee.xsd schema.

  <xs:element name="CEE" block="#all" final="#all">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="Event" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element block="#all" final="#all" name="Event">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" ref="crit" maxOccurs="1"/>
        <xs:element minOccurs="0" ref="id" maxOccurs="1"/>
        <xs:element minOccurs="0" ref="p_app" maxOccurs="1"/>
        <xs:element ref="p_proc" maxOccurs="1" minOccurs="1"/>
        <xs:element minOccurs="0" ref="p_proc_id" maxOccurs="1"/>
        <xs:element ref="p_sys" maxOccurs="1" minOccurs="1"/>
        <xs:element minOccurs="0" ref="pri" maxOccurs="1"/>
        <xs:element ref="time" maxOccurs="1" minOccurs="1"/>
        <xs:element minOccurs="0" name="Type" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element ref="action" maxOccurs="1" minOccurs="1"/>
              <xs:element minOccurs="0" ref="domain" maxOccurs="1"/>
              <xs:element minOccurs="0" ref="object" maxOccurs="1"/>
              <xs:element minOccurs="0" ref="service" maxOccurs="1"/>
              <xs:element ref="status" maxOccurs="1" minOccurs="1"/>
              <xs:element minOccurs="0" ref="subject" maxOccurs="1"/>
              <xs:element minOccurs="0" ref="tags" maxOccurs="1"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="0" name="Profile" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element ref="BaseProfile"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element maxOccurs="unbounded" minOccurs="0" name="Module">
          <xs:complexType>
            <xs:choice>
              <xs:element ref="Augment"/>
            </xs:choice>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

Naming Conventions

In order to maximize compatibility and ease development of support libraries, CEE imposes naming conventions on Field, Tag, and Profile names.

Each Field, Tag, or Profile MUST have a name that is unique within the context of the Event Schema. The name MUST also meet the following requirements:

Contain at least 1, but no more than 32 characters
Start with an ASCII letter (ABNF ALPHA) letter or underscore (_, ABNF %x5F) character
Consist only of ASCII letter, digit (ABNF DIGIT), and underscore characters

Generally, all CEE component names must conform to the following regular expression: [A-Za-z_][A-Za-z0-9_]{0,31}

Event Header Fields

A CEE Event block starts with an <Event> the following nine (9) header fields, which may appear in any order.

Table 1: Base Fields

Name	Field Type	Use	Description
crit	xs:byte	optional	A relative indication of the criticality, or impact, of an event. Events with a higher crit value have a potential for greater impact. For example, a hard disk failure is more critical that a user login.
id	xs:string	optional	The event message id. Events generated by the same producer and having the same id value must be of the same event type.
p_app	xs:string	optional	The application that is responsible for generating the event. Where applicable, the `p_app` identifier should uniquely identify the application using the application name, version, and vendor information.
p_proc	xs:string	required	The name of the process that produced the event. The process should belong to the application identified by the `p_app` field. If necessary, the process ID (pid) can be included via the `p_proc_id` field.
p_proc_id	xs:string	optional	The process identifier (pid) of the process that generated the event.
p_sys	hostname	required	The hostname of the system that generated the event.
pri	xs:byte	optional	The event priority, expressed as an integer value. A higher pri value indicates a higher processing or transmission priority. Systems the produce or process event logs should use the `pri` field to prioritize their processing queues.
time	xs:dateTime	required	The time the event occurred. This timestamp should have microsecond granularity (1E-6 seconds) and include the timezone GMT offset.
uuid	xs:string	optional	The event identifier. The value of the `uuid` field is used to uniquely identify this individual event instance.

The three (3) fields marked with a use of required (i.e., the p_proc, p_sys, and time fields) MUST be present in the Event block. Fields marked as optional SHOULD appear, especially if they are known or applicable to the event. Further information on field value types can be found in the Field Types section. Additional fields and field requirements are further extended by defining additional CEE events as described below.

Event Type

The event type is indicated through CEE Taxonomy tags place in the Event's <Type> block. This block consists of fields representing the seven (7) tag fields:

Table 2: Event Type Fields

Name	Field Type	Use	Description
action	actionTag	required	The primary type of action that was undertaken as part of the event. The status or result of the action should be detailed in the `status` field.
domain	domainTag	optional	The environment or domain of the event. Typical event domains include network (net), operating system (os), and application (app).
object	objectTag	optional	The type of object that is targeted or otherwise affected by the event.
status	statusTag	required	The end result or status of the event action identified by the `action` field.
subject	objectTag	optional	The type of object that initiated or started the event action identified by the `action` field.
service	serviceTag	optional	The service the event involves. The service field value provides context to the event action or more precision to the event domain.
tags	tag	optional	A list of uncategorized CEE Taxonomy tags.

A more thorough discussion of tags and tag categories can be found in the Taxonomy section of this document.

Event Profile

The <Profile> section of a CEE Event contains the user-defined, custom profile for this particular event. The Profile block contains exactly one element - the profile of all of the fields that are applicable for this event.

A profile MUST consist of at least the following two (2) fields:

Table 3: Base Profile Fields

Name	Field Type	Use	Description
schema	xs:anyURI	optional	A URI that resolves to the location of an XML Schema that profiles the CEE Event structure.
schema_ver	xs:string	optional	The version of the XML Schema that was used to construct the event. The actual XML Schema location should be denoted by the value of the `schema` field.

The structure and contents of the profile should correspond to the profile definition provided by the schema and schema_ver fields.

For further information on how to use and define custom profiles, refer to the Extending CEE Events with Profiles section.

Event Taxonomy

The Event Taxonomy defines common tags that can be used to classify events or help identify related events. These tag definitions are located in the CEE Profile taxonomy.xsd document. These tags are organized into several categories, which are associated with an event classification criterion.

Current tag categories include:

action: The primary type of action that was undertaken as part of the event. The status or result of the action should be detailed in the status field.
domain: The environment or domain of the event. Typical event domains include network (net), operating system (os), and application (app).
object: The type of object that is targeted or otherwise affected by the event
service: The service the event involves. The service field value provides context to the event action or more precision to the event domain.
status: The end result or status of the event action identified by the action field.
subject: The type of object that initiated or started the event action identified by the action field.

Events having similar sets of tags are similar. Also, users can use tags to quickly identify certain types of events. For example, a user can search for all events having a login action tag.

Tag Definitions

Tags are defined in the taxonomy.xsd part of the CEE Profile. Each tag has a name, category, and a description. A tag name MUST conform to the CEE naming conventions.

Each tag value is defined as part of an XML enumerated tag type associated with the tag category that extends the CEE tag field type. For example, all of the action category tags are defined in an actionTag field type and object category tags are defined in the objectTag type.

Event producers may choose to define their own tag values. These custom tag values MUST start with a colon (:, ABNF %x3A) character, followed by a tag name conformant to the CEE naming conventions. The XML Schema definition for custom tag names is provided by the tag_ext field type defined in the CEE Taxonomy.

Unfortunately, users cannot directly add or modify tags or tag categories defined in the CEE Taxonomy.

Tag Examples

Below is an example of taxonomy.xsd content:

<xs:simpleType name="actionTag">
  <xs:union>
    <xs:simpleType>
      <xs:restriction base="tag_ext"/>
    </xs:simpleType>
    <xs:simpleType>
      <xs:restriction base="tag">
          <xs:enumeration value="access">
            <xs:annotation>
              <xs:documentation>Access Event</xs:documentation>
              <xs:appinfo>
                  <meta:description>A file, user account, network share, or other object has been accessed. If more is known regarding the access, use a more precise action such as "read", "write", or "execute".</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <!-- ... -->
          <xs:enumeration value="login">
            <xs:annotation>
              <xs:documentation>Login Event</xs:documentation>
              <xs:appinfo>
                  <meta:description>A user or other entity gains access to a system through a successful authentication or login attempt</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="logout">
            <xs:annotation>
              <xs:documentation>Logout Event</xs:documentation>
              <xs:appinfo>
                  <meta:description>An entity that has already gained access to a system or application (through a login action), ends their user account session. Another session can be established to the user account only through another successful logon action.</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="move">
            <xs:annotation>
              <xs:documentation>Move Event</xs:documentation>
              <xs:appinfo>
                  <meta:description>An object was moved. Usually 'move' describes the moving of a file between directories. A 'move' may be implemented as a sequence of [copy] and [remove] actions.</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="read"/>
          <!-- ... -->
      <xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>
<xs:simpleType name="statusTag">
  <xs:union>
    <xs:simpleType>
      <xs:restriction base="tag_ext"/>
    </xs:simpleType>
    <xs:simpleType>
      <xs:restriction base="tag">
          <xs:enumeration value="failure">
            <xs:annotation>
              <xs:documentation>Event Failed</xs:documentation>
              <xs:appinfo>
                  <meta:description>The event failed due to some unmet condition, such as an incorrect password</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="success">
            <xs:annotation>
              <xs:documentation>Event Success</xs:documentation>
              <xs:appinfo>
                  <meta:description>The event completed successfully. For example, a successful user authentication event would be an instance where the authentication activity was successfully completed and the user was fully authenticated.</meta:description>
               </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
      <xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

User-Defined Tags

Users can define their own tags. While this is discouraged as it negatively affects usability, there are occasions when the CEE-defined tags and tag categories are not sufficient.

A custom tag MUST adhere to the following naming restrictions:

The tag name MUST start with a colon (':', ABNF %x3A) to indicate that it is a custom tag. This character does not count against the 32-character tag name limit.
The remainder of the tag name MUST meet the naming requirements outlined above.

If the new tag belongs an existing CEE tag category, the new tag name can be entered into the corresponding field in the event type. Otherwise, if the tag does not conform with an existing category, then it can be placed into the generic tags field.

Field Dictionary

There is substantial overlap in the field and data requirements of many events. The Field Dictionary provides definitions of commonly used fields. These fields are defined in the dictionary.xsd file for easy inclusion into any CEE Event.

All field names MUST be consistent with the CEE naming conventions.

Field Types

CEE supports a subset of the XML Schema Datatypes and defines several additional datatypes.

The supported XML datatypes include:

xs:string
xs:byte, xs:unsignedByte
xs:short, xs:unsignedShort
xs:int, xs:unsignedInt
xs:long, xs:unsignedLong
xs:float
xs:double
xs:dateTime
xs:hexBinary
xs:anyURI
xs:boolean

NOTE: xs:integer, and xs:decimal are not supported by this specification. All integer values MUST be representable in a 64-bit integer value. Decimal values MUST be able to be encoded as a 64-bit binary IEEE-754 ("double precision") encoded number.

The datatypes defined by CEE are restrictions placed on the xs:string type:

tag
ipAddress
macAddress
hostname
anyCEEType

Figure 3: CEE Field Types

tag Type

The tag field type is a special field type within the CEE that is used to include references to event tags, or keywords. Each tag value SHOULD correspond to a tag definition in the CEE Taxonomy. If the tag value is not defined in the CEE Taxonomy, the tag value must start with a colon (:, ABNF %x3A).

A variety of CEE tag values are predefined in the CEE taxonomy.xsd file.

A CEE tag value MUST begin with an ASCII letter (ABNF ALPHA) or underscore (_, ABNF %x5F), and be followed by no more than 31 letter, digit (ABNF DIGIT), and underscore characters.

<xs:simpleType name="tag">
  <xs:restriction base="string">
    <xs:pattern value=":?[A-Za-z0-9_]{1,32}"/>
  </xs:restriction>
</xs:simpleType>

ipAddress Type

The ipAddress field type holds a single network address within an IP network. IPv4 address values are represented using dotted-decimal notation.

The representation of a CEE ipv6Address value MUST adhere to a valid IPv6 address formats as defined in RFC 4007 and RFC 4291.

<xs:simpleType name="ipAddress">
  <xs:restriction base="string">
    <!-- IPv4 Address Pattern -->
    <xs:pattern value="(((25[0-5])|(2[0-4]\d)|(1?\d{1,2}))\.){3}((25[0-5])|(2[0-4]\d)|(1?\d{1,2}))"/>
    <!-- Normal IPv6 -->
    <xs:pattern value="([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}(%[!-$&-\.0-~]+)?"/>
    <!-- IPv6 Hex Compressed -->
    <xs:pattern value="(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)(%[!-$&-\.0-~]+)?"/>
    <!-- IPv6 Hex + IPv4 Dec -->
    <xs:pattern value="(([0-9A-Fa-f]{1,4}:){6,6})(25[0-5]|2[0-4]\d|[0-1]?\d?\d)(\.(25[0-5]|2[0-4]\d|[0-1]?\d?\d)){3}(%[!-$&-\.0-~]+)?"/>
    <!-- IPv6 Hex Compressed + IPv4 Dec -->
    <xs:pattern value="(([0-9A-Fa-f]{1,4}(:[0-9A-Fa-f]{1,4})*)?)::(([0-9A-Fa-f]{1,4}:)*)(25[0-5]|2[0-4]\d|[0-1]?\d?\d)(\.(25[0-5]|2[0-4]\d|[0-1]?\d?\d)){3}(%[!-$&-\.0-~]+)?"/>
  </xs:restriction>
</xs:simpleType>

macAddress Type

The CEE macAddress field type represents Media Access Control (MAC) address values that are the physical network address of a network interface.

The representation for a CEE macAddress value MUST adhere to a valid MAC address representation format as defined in IEEE 802.

<xs:simpleType name="macAddress">
  <xs:restriction base="string">
    <xs:pattern value="([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}"/>
  </xs:restriction>
</xs:simpleType>

hostname Type

The CEE hostname field type represents a system hostname or fully-qualified domain name (FQDN).

The representation of a CEE hostname value MUST NOT contain more than 255 characters and MUST adhere to a valid hostname or FQDN representation format as defined in RFC 1035.

<xs:simpleType name="hostname">
  <xs:restriction base="string">
    <xs:pattern value="[A-Za-z]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z]([A-Za-z0-9-]*[A-Za-z0-9])?)*"/>
    <xs:maxLength value="255"/>
  </xs:restriction>
</xs:simpleType>

anyCEEType Type

The anyCEEType field type is a convenience type and represents any CEE-compatible simple type. That is, the anyCEEType is similar in concept to the XML Schema anySimpleType and is the combination of all of the 19 field types defined above, excluding the eventDataType.

Field Definition

Fields can be defined or reused within an XML Schema. A field definition is simply a new xs:element in an XML Schema document. The element name attribute contains the field name and field type is included through a reference in the type attribute or defined in the local scope of that field element.

The field type MUST be one of the supported field types defined in the Field Types section, or a restriction of one of those types.

More information is in the Defining New Fields section.

Modules

Modules provided a means of adding or including information alongside an CEE Event. They are an agile way for CEE to support things such as digital signatures and non-destructive augmentation of event data.

The different types and structural requirements for various modules are defined alongside the CEE Event definition in the cee.xsd schema. Events MUST NOT use any module, which is not defined as part of the CEE specification. However some modules, such as the Augment module, allow for the end user some flexibility to extend the base the module content.

Currently, CEE defines the following event modules:

Augment: Allows events to be augmented with additional event-related data without affecting the integrity of the original event.

Augment Module

Augment module permit the addition of fields and field data to a CEE Event while preserving the integrity of the original event. Instead of modifying the event contents directly, a process may choose to append an Augment module to the CEE Event.

An Augment module has similar requirements to a CEE Event and uses a similar structure to that of the CEE Event defined above.

As with events, additional data can be added to Augment module by appending more fields.

  <xs:element name="Augment" block="#all" final="#all">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" ref="id" maxOccurs="1"/>
        <xs:element minOccurs="0" ref="p_app" maxOccurs="1"/>
        <xs:element ref="p_proc" maxOccurs="1" minOccurs="1"/>
        <xs:element minOccurs="0" ref="p_proc_id" maxOccurs="1"/>
        <xs:element ref="p_sys" maxOccurs="1" minOccurs="1"/>
        <xs:element ref="time" maxOccurs="1" minOccurs="1"/>
        <xs:element minOccurs="0" name="Profile" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element ref="BaseProfile"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

Processing

Augments can be processed individually or as part of a merged CEE Event.

Merging an augment with an existing event involves can be explained with the following psuedo-code.

Assuming an Augment Module, AUGMENT, to an Event, EVENT;

foreach field in AUGMENT:
    if field.name in EVENT:
        EVENT.fields[field.name].add_value(field.value)
    else:
        EVENT.add_field(field)

Extending Events with Profiles

New CEE Event Profiles and fields can be defined by creating a Profile Schema. This schema is an XML Schema file that extend extends from the base Profile Schema (cee.xsd) or any other CEE Profile Schema file.

When creating a Profile Schema, the following restrictions apply:

The new profile schema MUST be a valid XML Schema according to the XML Schema 1.0 specifications
The <xs:schema> targetNamespace attribute of the CEE schema MUST be http://cee.mitre.org
The <xs:schema> version attribute should be set to an appropriate version identifier
An <xs:include> element MUST be present and MUST be a URI that resolves to a valid CEE Profile Schema file

For example, this skeleton XML Schema file shows the minimal information necessary for a new Profile Schema that derives from the cee.xsd schema.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema version="1.0" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cee.mitre.org" xmlns="http://cee.mitre.org">

  <xs:include schemaLocation="cee.xsd"/>

</xs:schema>

Defining New Event Profiles

Users and developers are free to define their own event profiles. New profiles can be created by defining a new XML element. The profile element must be given a valid XML name that corresponds to the CEE naming conventions, associate with a valid profile type, and placed into the BaseProfile substitutionGroup.

Profile Structure

The structure of the CEE Event Profile MUST be defined by extending another valid CEE Event Profile. A valid profile structure MUST extend from the BaseProfileType defined in cee.xsd or from another, valid CEE Event Profile definition. The format of this structure can be found in the Event Profile section.

In addition to having to extend from another valid profile, such as the BaseProfileType, the only other structural profile requirements are the following:

All profile elements MUST have simple content. They MUST NOT have additionally nested elements.
Profiles MUST only contains element defintions; profiles MUST NOT contain any XML attributes.

Global versus Scoped Profiles

There are two ways to extend a CEE Event Profile, either via global types or locally scoped definitions. While each method requires access to the publicly defined event XML Schema complexType definition, using a scoped type does not allow for further extension. For this reason, they preferred way is to extend CEE Events using global types.

The CEE naming requirements do not apply to named simpleType or complexType blocks used in a CEE Profile Schema. These types are never present in an encoded CEE Event.

For those familiar with XML Schema Design Patterns, the global types pattern is equivalent to "Salami Slice", while the scoped definitions is related to the XML "Russian Doll" pattern.

Global Type Definitions

Using global profile type definitions is the preferred method to define new CEE Event Profiles, as it allows for others to extend the event.

First, define a new, global complexType with a descriptive name. For this example, we will define an event profile called ExampleGlobalProfile with a global type of GlobalProfileType. The profile will be defined in a named xs:element element and associated with the type defined in a global, named xs:complexType element. Starting with the skeleton XML Schema template from above:

<xs:schema version="1.0" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cee.mitre.org" xmlns="http://cee.mitre.org">

  <xs:include schemaLocation="cee.xsd"/>

  <!-- The Profile Type -->
  <xs:complexType name="GlobalProfileType">
    <!-- The Profile Structure -->
  </xs:complexType>
  <!-- The Profile Definition -->
  <xs:element name="ExampleGlobalProfile" type="GlobalProfileType" substitutionGroup="BaseProfile"/>

</xs:schema>

Next, find the name of the complexType definition associated with the profile that will be extended to create our new event profile. We will add this as a reference as the base attribute in an <xs:extension> element. In this case, we will extend the Profile's BaseProfileType. The extension is enclosed with an <xs:complexContent> block and added as a child to our GlobalProfileType type:

<xs:schema version="1.0" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cee.mitre.org" xmlns="http://cee.mitre.org">

  <xs:include schemaLocation="cee.xsd"/>

  <!-- The Profile Type -->
  <xs:complexType name="GlobalProfileType">
    <xs:complexContent>
      <xs:extension base="BaseProfileType">
        <xs:sequence>
          <!-- Field Definitions/References go here -->
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <!-- The profile definition -->
  <xs:element name="ExampleGlobalProfile" type="GlobalProfileType" substitutionGroup="BaseProfile"/>
</xs:schema>

Finally, within the <xs:extension> element, we will put the fields that will comprise the event profile content. The profile fields can either be referenced from external CEE Profile Schemas, such as cee.xsd, or can be defined locally, within the scope of the extension element.

Scoped Definitions

Scoped event definitions are created in a similar manner to the Global Type Definitions. The only difference is that instead of defining a global, named complexType structure, the type definition is included as a local, anonymous, scoped child type within the profile element:

<xs:schema version="1.0" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cee.mitre.org" xmlns="http://cee.mitre.org">

  <xs:include schemaLocation="cee.xsd"/>

  <!-- The Profile Definition -->
  <xs:element name="ExampleScopedProfile">
    <!-- The Profile Type -->
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="BaseProfileType">
          <xs:sequence>
            <!-- Field Definitions/References go here -->
          </xs:sequence>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>
</xs:schema>

Reusing CEE Dictionary Fields

To use any fields defined by CEE as part of the Field Dictionary, simply include the dictionary.xsd file via an <xs:include> statement that points to the location of the actual dictionary.xsd file.

For example, to include the latest version of the CEE dictionary.xsd file, include the following towards the top of the CEE Schema file:

<xs:include schemaLocation="http://cee.mitre.org/releases/v10alpha/dictionary.xsd"/>

Once complete, a field defined in that Dictionary file can simply be referenced via an XML Schema element with a ref that points to the name of the referenced dictionary.xsd field.

To include the src_ip and dst_ip fields from dictionary.xsd in a new CEE Event named DictionaryExample, the following Profile XML Schema could be used:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema version="1.0" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://cee.mitre.org" xmlns="http://cee.mitre.org">

  <xs:include schemaLocation="http://cee.mitre.org/releases/v10alpha/dictionary.xsd"/>

  <!-- This include is not necessary as it is included via dictionary.xsd -->
  <xs:include schemaLocation="http://cee.mitre.org/releases/v10alpha/cee.xsd"/>

  <!-- Global Type Profile Definition -->
  <xs:complexType name="DictionaryExampleType">
    <xs:complexContent>
      <xs:extension base="BaseProfileType">
        <xs:sequence>
          <xs:element ref="dst_ip"/>
          <xs:element ref="src_ip"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="CustomDictProfile" type="DictionaryExampleType" substitutionGroup="BaseProfile"/>

</xs:schema>

Defining New Fields

Instead of using an already defined field, users and developers may opt to define new fields to use within their event profile.

This process is similar to the one used for Defining New Event Profiles and has similar options - either fields can be defined globally or scoped. The preferred method is to define fields globally, as it maximizes the amount of reuse.

By default, all fields are defined as being required. To change the cardinality of a field, adjust the minOccurs and maxOccurs values. An optional field has a minOccurs value of 0. Fields should only have a minOccurs value of 0 or 1, and a maxOccurs value of 1.

Defining Field Types

Each field must have an associated type and that type must be an field type listed in the Field Types section, or a restriction of one of those types. Restrictions must be done by using the XML Schema restriction element on a validly derived CEE Field Type.

A list of the valid CEE Field Types reproduced here:

xs:string
xs:byte
xs:unsignedByte
xs:short
xs:unsignedShort
xs:int
xs:unsignedInt
xs:long
xs:unsignedLong
xs:float
xs:double
xs:dateTime
xs:hexBinary
xs:anyURI
xs:boolean
tag
ipAddress
macAddress
hostname
anyCEEType

For example, a port field type can be defined by restricting the xs:int type using the procedures outlined for simpleType types in the XML Schema Datatypes specification. The port field type can then be associated with the src_port field:

<xs:simpleType name="port">
  <xs:restriction base="xs:int">
    <xs:minInclusive value="0"/>
    <xs:maxInclusive value="65535"/>
  </xs:restriction>
</xs:simpleType>
<xs:element name="src_port" type="port"/>

Or this restriction can be defined within the scope of the field element:

<xs:element name="src_port">
  <xs:simpleType>
    <xs:restriction base="xs:int">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="65535"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

Global Field Definitions

This is the preferred method to define new CEE fields.

First, define a new, document-level element with the field name. Then associate a field type with it. Field types can be defined using the process described in the Defining Field Types section.

For this example, we will define a new field called GlobalField with a string type. Then we will use it in a new event definition.

<!-- The GlobalField Field -->
<xs:element name="GlobalField" type="xs:string"/>
<!-- The GlobalIPField Field -->
<xs:element name="GlobalIPField">
  <xs:restriction base="ipAddress">
    <!-- All GlobalIPField values must be ipAddresses that start "127." -->
    <xs:pattern value="127\..*"/>
  </xs:restriction>
</xs:element>

<xs:complexType name="ExampleProfileType">
  <xs:complexContent>
    <xs:extension base="BaseProfileType">
      <xs:sequence>

        <!-- Include the Fields from the CEE Dictionary by reference -->
        <!-- GlobalField is required -->
        <xs:element ref="GlobalField"/>
        <!-- GlobalIPField is optional -->
        <xs:element ref="GlobalIPField" minOccurs="0"/>

      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
<xs:element name="ExampleProfile" type="ExampleProfileType" substitutionGroup="BaseProfile"/>

Scoped Definitions

A field can also be defined within the scope of the event where it is used.

<xs:complexType name="ExampleProfileType">
  <xs:complexContent>
    <xs:extension base="BaseProfileType">
      <xs:sequence>

        <!-- Include the Fields by reference -->
        <!-- ScopedField is required -->
        <xs:element name="ScopedField" type="xs:string">

        <!-- ScopedIPField is optional -->
        <xs:element name="ScopedIPField" minOccurs="0">
          <xs:restriction base="ipAddress">
            <!-- All ScopedIPField values must be ipAddresses that start "127." -->
            <xs:pattern value="127\..*"/>
          </xs:restriction>
        </xs:element>

      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>
<xs:element name="ExampleProfile" type="ExampleProfileType"/>

Associating Events and Profile Schemas

A Profile Schema is of little value if we cannot use them to help validate the event content. In order to validate an event using an Event Schema, we have to know which Event Schema to use and were to find it.

In CEE, events can indicate the actual location of the CEE XML Schema by placing the location as a resolvable URL of the Event Schema into the schema field. This field is defined as part of the Event Profile in cee.xsd. Additionally, the precise version of the schema used can be indicated in the schema_ver field.

<CEE>
  <Event>
    <p_proc>proc1</p_proc>
    <p_sys>host.vendor.com</p_sys>
    <time>2012-01-18T05:55:12.4321-05:00</time>
    <Type>
      <action>login</action>
      <status>ongoing</status>
      <tags>:hipaa</tags>
    </Type>
    <Profile>
      <CustomProfile>
        <schema>http://vendor.com/events/cee-profile.xsd</schema>
        <schema_ver>1.0</schema_ver>
        <new_field>a string value</new_field>
        <new_val>1234</new_val>
        <product_host>source.example.com</product_host>
      </CustomProfile>
    </Profile>
  </Event>
</CEE>

In the above CEE Event, encoded according to the CEE CLS XML specification and the CEE Event Schema rules defined in this specification, the schema field of the custom CustomProfile event defines that the location of the CEE Schema should be found at http://vendor.com/events/cee-profile.xsd.

It also indicates that this event was created using version 1.0 of that CEE Event Schema document.

This is similar to the use of the schemaLocation attribute, which is defined as part of the http://www.w3.org/2001/XMLSchema-instance XML namespace. The first value of the schemaLocation defines the XML namespace, while the second value defines the URI where the schema for that namespace may be found.

Event Extensions and Profiles

As mentioned previously, not only can profiles used in an event, but they are also applicable to various CEE Event Modules.

Below is an example of a profile used in an event with an Augment Module:

<CEE>
  <Event>
    <p_proc>proc1</p_proc>
    <p_sys>host.domain.com</p_sys>
    <time>2012-01-21T13:00:01Z</time>
  </Event>
  <Module>
    <Augment>
      <p_proc>aug_proc_1</p_proc>
      <p_sys>relay.domain.com</p_sys>
      <time>2012-01-21T13:02:17.0125Z</time>
      <Profile>
        <VendorDictProfile>
          <schema>http://vendor-domain.com/cee-profiles/default.xsd</schema>
          <schema_ver>1.01</schema_ver>
          <dst_ip>10.10.0.2</dst_ip>
          <src_ip>127.0.0.1</src_ip>
        </VendorDictProfile>
      </Profile>
    </Augment>
  </Module>
</CEE>

Querying and Validating Events

Since the CEE Event and Event Profiles are represented using XML and XML Schema, we can make use of other XML-based standards to perform operations on CEE Events.

Given a CLS-encoded CEE Event Record, it can be transformed into its CEE Event XML equivalent by decoding the CLS syntax. Once in a compliant CEE XML format, we can utilize tools such as Schematron and XQuery to perform validation and queries over the event data.

Event content requirements can be written using Schematron. A Schematron rule can be used to select a subset of events based on the event identifier, tags, or other field content. Schematron assertions can be tested over that event set to audit whether those events and their field data are compliant with the policy encoded in the Schematron checks.

Events can also be selected or queried using XQuery, or "XML Query". While Schematron checks are used to make assertions on event content, XQuery behaves similar to SQL statemements and simply returns a list of CEE Events that match the XQuery statement. XQuery can also be used to merge related events into a new CEE Event, aggregate events based on the number of times they appear over a period of time, or to filter out irrelevant event records.

While XQuery and Schematron provide standardized languages for querying and validating CEE Events, they require some effort to learn and do not offer the performance of more native or optimized solutions.

Page Last Updated: August 10, 2012

Additional Information

CEE Profile Specification v1.0α

Table of Contents

Introduction

CEE Profile

CEE Event

Naming Conventions

Event Header Fields

Event Type

Event Profile

Event Taxonomy

Tag Definitions

Tag Examples

User-Defined Tags

Field Dictionary

Field Types

tag Type

ipAddress Type

macAddress Type

hostname Type

anyCEEType Type

Field Definition

Modules

Augment Module

Processing

Extending Events with Profiles

Defining New Event Profiles

Profile Structure

Global versus Scoped Profiles

Global Type Definitions

Scoped Definitions

Reusing CEE Dictionary Fields

Defining New Fields

Defining Field Types

Global Field Definitions

Scoped Definitions

Associating Events and Profile Schemas

Event Extensions and Profiles

Querying and Validating Events