Specifications   Search
CEE™ Common Event Expression: A Unified Event Language for Interoperability
CEE Website is in "Archive" status — read the announcement
 

About CEE

Documents

FAQs

CEE Language

Current Release

Previous Releases

CEE Community

CEE Board

Discussion Archive

News & Events

Calendar

Search the Site

CEE Language

Current Release

Specifications

Schemas

Downloads

Profiles

Versioning

Terminology

Implementations

Additional Information

Previous Releases

Terms of Use

CEE Log Syntax (CLS) Specification1.0-beta1

  1. Introduction
  2. CEE Event Model
    1. Profile Reference
    2. Event Body
    3. Categorization into the Taxonomy
  3. CLS Encodings
    1. JSON Encoding
    2. Representing multiple events
    3. Examples
    4. XML Encoding
    5. Examples
  4. Translating between JSON and XML

1 Introduction

This document describes the requirements for encoding and decoding Common Event Expression (CEE) Events into a specific markup format to represent the event either on disk or in transit. These requirements are designed for maximum interoperability with existing event and interchange standards to minimize adoption costs. To ensure that Events are consistently encoded into each markup format CEE defines CEE Log Syntax (CLS) Encodings for each supported markup format (currently JSON and XML). Each CLS Encoding defines how to represent a CEE Event as an event record in the given markup language.

2 CEE Event Model

The CEE Event Model is the high-level description of what the structure of a CEE Event looks. The Event Model is not directly implemented by any tools, instead the tools adopt one or both of the CLS Encodings described below (JSON and XML). The Event Model is a codification of how an event record is represented to conform to a CEE Profile (including the CEE Core Profile).

The CEE Event Model, and therefore each and every CEE Event, consists of a profile reference and a list of fields and zero or more values for each of those fields.

2.1 Profile Reference

Every CEE event has either an explicit or implicit reference to a CEE Profile. Events MAY explicitly reference a specific profile using a URI that identifies a specific profile. It's strongly encouraged that this URI SHOULD be a resolveable URL for easy of use, however this is not a requirement.

The profile reference itself refers to any valid CEE Profile, including either a human-readable profile document that follows the CEE Profile requirements or a machine-processable profile if the given encoding supports it (currently, only XML).

If the profile reference is omitted there SHALL be an assumed reference to the latest release of the CEE Core Profile. The reference URIs for Core Profile are:

2.2 Event Body

The CEE Event Body is a listing of zero or more fields that describe the event. Fields are defined further in the CEE Profile specification; valid field identifiers in a CEE Event are the same as valid identifiers in a CEE Profile.

The order of the fields in a CEE Event is significant and MUST be retained when encoding and decoding.

The listing of fields MUST comply with the following requirements:

  1. Fields are hierarchical in nature; they MAY be nested up to two levels but MUST NOT be nested more than that.
  2. Field ordering SHALL be significant and MUST be retained when encoding and decoding.
  3. Fields that are required in the referenced profile MUST be included.
  4. Fields that are optional in the referenced profile MAY be included.
  5. All fields that are defined in the referenced profile MUST conform to either the specified data type or to the NULL data type.
  6. Fields that are not in a referenced profile MAY be included; the data type for these fields SHALL be assumed to be a string and they MUST be placed in a "native" object. This native object SHALL NOT count as a level of nesting for purposes of the first requirement above.
  7. Each field MAY contain zero to many values.

2.3 Categorization into the Taxonomy

The event categorization is the information that places the Event into the referenced profile's Taxonomy. It consists of a set of categories, from the taxonomy, and the tag value for each category that best describes the event. All taxonomy fields are optional, however if given they MUST contain exactly one non-null value.

3 CLS Encodings

CEE makes a distinction between the event occurence itself, an event record, and an encoding of an event record. The event itself is the original occurence of some set of circumstances that the logging program wishes to record. When the event occurs, the logging program collects any relevant data about it into the abstract notion of an event record using the CEE Event specification. That event record can then be encoded into a markup language using a CLS Encoding. In order to consume the event, the event consumer uses a CLS mapping to decode the markup into the abstract CEE Event.

3.1 JSON Encoding

The JavaScript Object Notation (JSON) format is a text-based data exchange format and is used by a large number of devices and applications. The simplicity, readability, and efficiency of JSON makes it ideal for encoding event record data when performance and small data size are important. Lack of validation and inline digital signature capability makes it less ideal for cases where event chain of custody, integredity, and validity need to be assured. This document describes a method for encoding a CEE Event into a JSON event record.

The use of the CEE JSON Encoding SHOULD be indicated by the use of the MIME (Internet) media type: application/cee+json. As UTF-8 is the only allowable encoding for the CEE JSON encoding, an encoding specification in the MIME type is redundant.

3.1.1 General Encoding Requirements

Mapping JSON to CEE Core Profile Field Types

JSON offers native support for four value types: string, number, bool, and null.

For maximal compatibility, null, number, and bool CEE Field Types SHOULD be encoded using the equivalent, built-in JSON types. Values corresponding to these native types SHOULD NOT appear within quote characters.

All other CEE Core Profile Field Types MUST be represented as JSON string values.

Note that the explicit field types are lost when representing non-CEE Core Profile fields because they're converted to JSON strings. Implementations MAY try to infer these lost types to the maximum precision they are capable of determining. That is, a JSON string value of "10.0.0.2" MAY be resolved to an IPv4 address type when feasible.

3.2 Representing multiple events

JSON provides a simple array mechanism which SHOULD be used to represent multiple events whenever possible.

{"src":{"ipv4": "1.2.3.4"}}

For compatibility reasons, however, the inline field names may also be used:

{"src.ipv4":"1.2.3.4"}

3.3 Examples

3.3.1 Example 1 - Valid

This is a JSON Event Record corresponding to the most minimal event compliant with the CEE Core Profile. Note the lack of a profile reference, implying an implicit reference to the CEE Core Profile.

{
  "host":"system.example.com",
  "pname":"auth",  
  "time":"2011-12-20T12:38:05.123456-05:00"
}

3.3.2 Example 2 - Valid

This is a JSON Event Record generated using the optional fields in the CEE Core Profile.

{
  "host":"system.example.com",
  "pid":123,
  "time":"2011-12-20T12:38:05.123456-05:00",
  "msgid":"abc",
  "msg":"my event message",
  "app":"application",
  "pname":"auth",
  "sev":10,  
  "action":"login",
  "status":"success"
}

3.3.3 Example 3 - Valid

This is a JSON Event Record that a CEE Profile reference.

{
  "profile":"http://vendor.com/events/1.0",
  "host":"host.vendor.com",
  "pname":"proc1",  
  "time":"2012-01-18T05:55:12.4321-05:00",
  "action":"login",
  "status":"ongoing",
  "tags":":hipaa",
  "new_field":"a string value",
  "new_val":1234,
  "product_host":"source.example.com"
}

3.3.4 Example 3 - Valid

This is a JSON Event Record that uses "native" fields not found in the referenced profile.

{
  "profile":"http://vendor.com/events/1.0",
  "host":"host.vendor.com",
  "pname":"proc1",  
  "time":"2012-01-18T05:55:12.4321-05:00",
  "action":"login",
  "status":"ongoing",
  "tags":":hipaa",
  "native": {
    "new_field":"a string value",
    "new_val":1234,
    "product_host":"source.example.com"
  }
}

3.3.5 Example 4 - Valid

This is a list of JSON Event Records (i.e. a log)

[
  {"host":"host.vendor.com","pname":"process1","time":"2012-01-18T05:55:12.4321-05:00"},
  {"host":"host.vendor.com","pname":"process2","time":"2012-01-18T05:55:12.4321-05:01"}
]

3.4 XML Encoding

The W3C Extensible Markup Language (XML) 1.0 format is a text-based data exchange format and is used by a large number of devices and web services. It supports validation of documents against a definition (schema), digital signatures, and advanced compression. This makes it ideal for representing audit data that must be assured.

The use of the CEE XML Encoding SHOULD be indicated by the use of the MIME or Internet media type: application/cee+xml. As UTF-8 is the only allowable encoding for the CEE JSON encoding, an encoding specification in the MIME type is redundant.

3.4.1 General Encoding Requirements

3.4.2 Mapping XML to CEE Value Types

All XML values are contained within XML elements as character sequences.

Based on the content of the XML value, the CEE XML Event Schema, and any corresponding Event Profile schemas, it is up to the application to choose the best mapping for their needs. All CEE applications MUST at least map an XML-encoded field value to the xs:string field type.

However, the value types may be explicitly noted by adding a type attribute to the associated field element. The value of type should be set to one of the following values, each corresponding a CEE Value Type: string, number, bool, ipv4, ipv6, datetime, null, or object.

3.4.3 Conforming to a CEE Profile

Because XML supports a native validation mechanism through XML Schema, the profile reference in a CEE event may be placed both in the profile element and in the schemaLocation attribute on the root element.

The profile reference in the profile element is the normative reference and, if it's a URL, SHOULD point to the URL for a human-readable profile. The profile reference in the schemaLocation attribute is used for XSD Validation and, if used, MUST point to any URL for the profile XSD.

3.5 Examples

3.5.1 Example 1 - Valid

The XML Event Record corresponding to the most minimal event that is compliant with the CEE Core Profile.

<cee:cee xmlns="http://cee.mitre.org/1.0/profile/" xmlns:cee="http://cee.mitre.org/1.0/">
  <cee:event>
    <host>system.example.com</host>
    <pname>auth</pname>
    <time>2011-12-20T12:38:05.123456-05:00</time>
  </cee:event>
</cee:cee>

3.5.2 Example 2 - Valid

A CEE Event generated using type attributes and the CEE Event structure defined in cee.xsd. Note the further lack of a CEE Profile reference, implying the cee.xsd schema.

<?xml version="1.0" encoding="UTF-8"?>
<cee:cee xmlns="http://cee.mitre.org/1.0/profile/" xmlns:cee="http://cee.mitre.org/1.0/">
  <cee:event>
    <host>system.example.com</host>
    <pname>auth</pname>
    <time>2011-12-20T12:38:05.123456-05:00</time>
    <appname>application</appname>
    <pid>123</pid>
    <sev>10</sev>    
    <action>login</action>
    <domain>app</domain>
    <object>account</object>
    <service>web</service>
    <status>success</status>
  </cee:event>
</cee:cee>

3.5.3 Example 3 - Will Not Validate

A CEE XML Record that contains a CEE Profile reference specific to the event producer. Note that this event won't validate since the external profile isn't defined anywhere.

<cee:cee xmlns="http://cee.mitre.org/1.0/profile/" xmlns:cee="http://cee.mitre.org/1.0/">
  <cee:event profile="http://vendor.com/events/1.0">
    <host>host.vendor.com</host>
    <pname>proc1</pname>
    <time>2012-01-18T05:55:12.4321-05:00</time>
    <action>login</action>
    <status>ongoing</status>
    <new_field>a string value</new_field>
    <new_val>1234</new_val>
    <product_host>source.example.com</product_host>
  </cee:event>
</cee:cee>

3.5.4 Example 4 - Valid

A CEE XML Record that contains native (custom) fields not specified in any profile.

<cee:cee xmlns="http://cee.mitre.org/1.0/profile/" xmlns:cee="http://cee.mitre.org/1.0/">
  <cee:event>
    <host>host.vendor.com</host>
    <pname>proc1</pname>        
    <time>2012-01-18T05:55:12.4321-05:00</time>
    <action>login</action>
    <status>ongoing</status>
    <cee:native>
      <custom_field>custom val</custom_field>
    </cee:native>
  </cee:event>
</cee:cee>

4 Translating between JSON and XML

JSON and XML-encoded CEE events reference the same data. As such, there is a 0% data-loss rate when translating between the two formats. The translation rules are:

For example, these are equivalent events:

<cee:cee xmlns:cee="http://cee.mitre.org/1.0/" xmlns:cee="http://cee.mitre.org/1.0/profile/">
  <cee:event profile="http://vendor.com/events/1.0">
    <host>host.vendor.com</host>
    <pname>proc1</pname>
    <time>2012-01-18T05:55:12.4321-05:00</time>
    <cee:native>
      <custom_field>custom val</custom_field>
    </cee:native>
  </cee:event>
</cee:cee>

[
  {
    "profile": "http://vendor.com/events/1.0",
    "host": "host.vendor.com",
    "pname": "proc1",
    "time": "2012-01-18T05:55:12.4321-05:00",
    "native": {"custom_field": "custom val"}   
  }
]

BACK TO TOP

Page Last Updated: August 09, 2012