CEE Profile Specification1.0-beta1

1. Introduction
2. CEE Profile Specification
   1. Parent Profile Reference
   2. Canonical URI
   3. Field Dictionary
   4. Event Taxonomy
3. CEE Core Profile
   1. Versioning
   2. Core Field Dictionary
   3. Core Taxonomy
4. CEE Profiles in XML Schema
   1. Structure
   2. Validation
5. Appendix 1: CEE Profile Template
   1. Introduction
   2. Field Dictionary
   3. Taxonomy

1 Introduction

The CEE Profile Specification allows communities of interest, product vendors, and regulatory bodies to publish a shared vocabulary used for event logging. This shared vocabulary (a CEE Profile) can then be adopted to produce, consume, and analyze CEE event records while being assured of a consistent vocabulary.

2 CEE Profile Specification

The CEE Profile Specification defines the method for describing a class of event. Each CEE Profile includes:

1. A reference to a parent profile
2. A canonical URI used to identify it
3. A field dictionary that standardizes the field names and data types
4. A taxonomy that standardizes the categorizations

Because CEE supports both XML and JSON CLS syntaxes CEE Profile does not require an encoding format at this time. As such the default form for a profile document is simply a text document conforming to the requirements below and following the template in [Appendix 1][]. However, if organizations wish to validate events against a profile or accept a machine-readable profile they may adopt the XML CLS Encoding and the associated CEE Profile XSD format to do so. Future versions of CEE may publish an open source profile validator for the JSON syntax, but for this version it's recommended that users who need validation use the XML formats.

The ability to describe events in a common format means that individual communities of interest can develop a shared set of fields, data types, values, and categorizations for events related to that community. CEE itself provides a Core CEE Profile with a field dictionary and taxonomy suited to reporting events across many application types (operating system, web application, network appliance, etc). All other CEE Profiles MUST either directly or indirectly extend the Core CEE Profile to ensure compatibility with CEE.

CEE Profile Requirements

1. CEE Profiles (except the CEE Core Profile) SHALL inherit from the CEE Core Profile, including all fields, taxonomy facets, and data types.
2. CEE Profiles MAY define 0-n additional fields and values
3. CEE Profiles MAY define 0-n additional taxonomy facets
4. CEE Profiles SHALL NOT define additional data types. Data types can be suggested in a profile but SHALL NOT be normative of events implementing this profile
5. CEE Profiles MUST specify a single canonical URI for references for each profile type (human-readable, XML Schema).
6. The canonical URI SHOULD be a resolveable URL to the profile itself.

2.1 Parent Profile Reference

Profiles that include an explicit reference to a parent profile inherit the field dictionary, taxonomy, and event classes of that parent profile. Profiles that do not include an explicit reference to a parent profile SHALL have an implicit reference to the latest version of the CEE Core Profile and therefore inherit its field dictionary and taxonomy.

2.2 Canonical URI

A profile's canonical URI is the mechanism used to identify it both in other CEE Profiles and in CEE events themselves. As such, once a profile is published and has a defined URI that URI SHOULD NOT be changed unless the profile itself changes. If the profile does change, either due to versioning or some other reason, the URI SHOULD change. An best practice to ensure URI consistency and change control is to include a version number in the profile URI, such as ```http://example.com/cee-profile/1.1".

If a profile is published both as a text profile and as an XSD profile, the URI MUST be identical if and only if the two versions are semantically identical. If this is the case and resolveable URLs are being used as the profile URI, the URL SHOULD resolve to the text profile (which may then reference the XSD profile).

2.3 Field Dictionary

The field dictionary is a list of fields and data types that may be used to describe events. Each field in the dictionary consists of a field identifier, a field type, and whether that field is optional or required.

2.3.1 Field Identifiers

Field identifiers are case insensitive and hierarchically structured as a combination of zero or more context objects and the identifying field name. The field identifier (i.e., both the object and name components) must only consist of lowercase ASCII alphanumeric and _ (underline) characters: [0-9a-z_]+.

Field name that have a context object SHOULD be represented as separated with a dot (.) when displayed outside of one of the supported [CLS Encodings][CLS]. This is known as the inline field syntax. For example, the ipv4 field in the src object can be represented as src.ipv4. This pattern follows many common programming languages, including Java, C++, and Javascript.

2.3.2 Field Type

In addition to a field identifier, each field in the field dictionary MUST specify a data type that specifies how values for the field are represented. If there are no type restrictions, the string type should be used. The field type MUST be a reference to a valid CEE Data Type, data types outside of this list MUST NOT be used. Valid data types are:

1. string: A sequence of zero or more UTF-8 encoded Unicode characters
2. bool: A boolean value of true or false
3. number: An integer or floating point numerical value. Number values can be positive or negative and may use scientific notation.
4. null: An empty or null value.
5. datetime: Datetime values represent timestamps and allow for full specification of the time down to the millisecond and include timezone UTC offsets. If no timezone information is provided, it MUST be assumed that the datetime is given in UTC. The preferred representation format is the datetime format defined in ISO8601.
6. ipv4: IPv4 values are used to represent IPv4 network addresses. The preferred format is to use dotted-decimal string representation: 10.10.0.2, 128.0.0.1
7. ipv6: IPv6 values represent IPv6 network addresses. The preferred format of IPv6 addresses is the standard hex-colon notation and all of the approved abbreviation formats (e.g., ::).
8. object: Object values consist of additional structured data represented as a sequence of name-value pairs.

2.4 Event Taxonomy

The event taxonomy is used to classify an event across zero or more facets (categories). This categorization is used to understand what the type of an event is, while fields in the field dictionary are used to specify specific data points about an event. In contrast to the field dictionary, when an event may have many values for a single field, an event may only have one value for each field in the event taxonomy.

Event facets are very similar to fields in the field dictionary with the following restrictions:

• Event facet identifiers SHALL be valid Field Identifiers.
• Event facets SHALL be an enumerated restriction on the data type string.
• Event facet definitions MUST specify at least one possible value.

Profiles MAY add additional facets for event categorization but MUST NOT add additional values to existing facets that were defined in the inherited profile(s).

3 CEE Core Profile

The CEE Core Profile is a CEE Profile that provides a field dictionary and taxonomy suited to reporting common event types as well as providing a base for other profiles to build off of with common fields and taxonomy categories.

The current CEE Core Profile is available at cee.mitre.org.

3.1 Versioning

The Core Profile is published and versioned separately from the CEE specification. The versioning policy of the CEE Core Profile is:

1. The set of data types published in the CEE Core Profile SHALL NOT change unless the CEE Specification itself is versioned
2. The set of required fields and data types SHALL NOT change unless the CEE Specification itself is versioned
3. Optional fields and their data types SHALL NOT be changed unless the CEE Specification itself is versioned
4. Additional, optional, fields MAY be added without requiring a new version of the CEE Specification
5. Categories in the CEE Taxonomy SHALL NOT be removed unless the CEE Specification itself is versioned
6. Additional categories in the CEE Taxonomy MAY be added without requiring a new version of the CEE Specification
7. Additional taxonomy facets in the CEE Taxonomy MAY be added without requiring a new version of the CEE Specification

Together, this versioning policy means that CEE Profiles are ALWAYS backwards-compatible to the versioned released alongside the latest version of the CEE Specification itself.

3.1.1 Deprecation

When a field, taxonomy value, taxonomy category, or event class must be removed from the Core Profile it will go through a deprecation phase per the CEE Versioning Policy deprecation rules.

3.2 Core Field Dictionary

The CEE Field Dictionary is a list of fields and values that CEE provides for use across the event reporting community. Conceptually, it contains a core set of required fields (which can be thought of as an event header) that MUST be present in all CEE event records and a set of optional fields that MAY be used for any event reporting. The Field Dictionary is a constantly evolving document and as such is versioned separately from the core CEE Specification (which includes the CLS and CLT specifications).

In order to ensure that fields are useful across many products and to truly standardize event reporting, all fields in the field dictionary and facets in the taxonomy must conform to the following requirements:

1. Fields MUST meet the naming and nesting specifications listed above.
2. Fields MUST NOT be specific to a certain vendor or product. Different applications from different vendors that perform the same function should use the same fields in the dictionary to report information, so fields specific to an application or vendor should be generalized. Even if only one vendor or application reports that information the field name will be generalized to allow for future entrants to use the field.
3. Fields MUST be common enough to warrant inclusion. Fields that are not common or general-purpose will not be included.

The Core CEE Profile specifies three header fields that are required in all CEE Events:

These header fields SHALL NOT change unless the CEE Specification itself changes.

An un-encoded example of a CEE Header would be:

host: hosta.example.com
pname: sys
time: 2012-04-15T07:39:21.5438-05:00

The minimally-valid CEE event is simply the three header fields as shown above. Any producer creating a CEE Event MUST include the above fields, with exactly value, in the record.

In addition to the header fields, the Core Profile defines a list of additional fields that MAY be used in all CEE events. These fields SHALL be used when conveying information that matches the definition. Or put more simply, fields from the Core Profile MUST be used rather than redefining these fields in a custom profile or using a custom name when creating an event record. For example, in reporting a hostname the host field in the Core Profile must be used, rather than creating a new field in a profile called hostname.

Fields in the CEE Dictionary are developed by the CEE Community with final approval given by the CEE Board. Suggestions may be submitted to the cee-discussion-list; please include the field name, data type, description, and a justification for why the field should be included in the dictionary for each field being suggested. Additionally, please make sure the above requirements are met before suggesting a field.

The official CEE Field Dictionary is located in the CEE Core Profile at: Core Profile Field Dictionary.

3.3 Core Taxonomy

The Core Taxonomy is a set of facets (categories) that are valid for Event Classification and, for each facet, the possible tag values that may be used. The categories and allowed tag values are developed by the CEE Community with final approval given by the CEE Board. Suggestions may be submitted to the cee-discussion-list; please include a use case justification for each change.

The official CEE Taxonomy is located in the CEE Core Profile at: Core Profile Taxonomy.

4 CEE Profiles in XML Schema

Although CEE Profiles are language agnostic and may be used easily in JSON, XML provides additional validation capabilities through XML Schema that may be used to validate events against an extended profile. This section describes how to represent a CEE profile using a subset of XML Schema.

4.1 Structure

CEE Profiles represented in XML Schema MUST conform to the XML Schema Specification. Additionally, they may not define any structures other than as explained below to define the field dictionary and taxonomy.

Note that, in addition to the restrictions below, all CEE Profiles in XSD MUST comply with the general profile requirements for field identifier naming, field types, and the taxonomy as described in the relevant specifications.

The namespace for CEE Profile fields and taxonomy facets is http://cee.mitre.org/1.0/profile. This MUST be used as the namespace and targetNamespace for the schema. Types are referenced through the CEE namespace, http://cee.mitre.org/1.0.

4.1.1 Inheriting

To inherit from another profile, use an include element with the reference to that profile's schema. One and only one include is allowed, it must reference either the CEE Core Schema or some other extended schema. This will include the field dictionary and taxonomy from the extended schema.

The direct or indirect reference to CEE Core Profile will, by extension, include the core CEE schema.

4.1.2 Field Dictionary

The field dictionary is described using the element element of XML Schema. The general structure for fields that do NOT have a context object is:

  <xs:element name="###FIELD IDENTIFIER###" type="###FIELD TYPE###" />

The field identifier is included exactly as it would be in a general CEE Profile.

The field type is imported from the CEE namespace is taken from the following mapping:

The field description, which is optional, may be placed inside a standard XML Schema annotation/documentation block.

Fields with context object

All fields with the same context object are represented under an element for that object. The context object itself uses the following format:

   <xs:element name="###CONTEXT OBJECT IDENTIFIER###" block="#all" final="#all">
     <xs:complexType>
       <xs:complexContent>
         <xs:extension base="ObjectField">
           <xs:sequence maxOccurs="unbounded" minOccurs="1">
             ...
           </xs:sequence>
         </xs:extension>
       </xs:complexContent>
    </xs:complexType>
  </xs:element>

The name of the context object is placed in the name field of the element descriptor. Fields for the context object are listed, as above, inside the sequence element. Standard XML Schema annotation/documentation elements may be used to describe the context object.

4.1.3 Taxonomy

To create an additional category in which to categorize events, use the following template:

   <xs:element name="###CATEGORY IDENTIFIER###">
     <xs:simpleType>
       <xs:union>
         <xs:simpleType>
           <xs:restriction base="cee:tag_ext" />
           <xs:restriction base="cee:tag">
             <xs:enumeration value="###CATEGORY VALUE###" />
           </xs:restriction>
         </xs:simpleType>
      </xs:union>
    </xs:simpleType>
  </xs:element>

The category identifier is placed in the element's name attribute while each value is placed in an enumeration element within the second restriction.

4.2 Validation

Validation against a profile is accomplished simply by validating either a single event (root element: event) or an event list (root element: cee) against the profile.

5 Appendix 1: CEE Profile Template

The template below provides a starting point to publish CEE Profiles.

5.1 Introduction

Information about the purpose and audience of the schema should go here. If the parent profile is not the CEE Core Profile, the name and URI of the parent profile should be included here as well.

It would also be helpful to list the canonical URI of this profile and, if applicable, the location of the profile XSD.

5.2 Field Dictionary

5.3 Taxonomy

5.3.1 Categorization 1

Explain here what you would use this categorization for. If this is an extension of a categorization from the inherited profile the name should match exactly. Below, the list of values possible for this categorization should be listed along with when they should be used and what they mean.

Value 1

Explanation of value 1

BACK TO TOP

Page Last Updated: March 18, 2013