CEE Log Syntax (CLS) Encoding: XML (application/cee+xml)
draft-cls-xml-06-6

Abstract

This document defines a Common Event Expression (CEE) Log Syntax (CLS) encoding that is compatible with the W3C Extensible Markup Language (XML) 1.0 format. This syntax encoding specifies how to encode a CEE event record using XML, as well as how to extract the CEE event record data from an XML encoded event record.

Copyright Notice

Copyright (c) 2011 The MITRE Corporation. All rights reserved.

Document License

The MITRE Corporation (MITRE) hereby grants you a non-exclusive, royalty-free license to use CEE for research, development, and commercial purposes. Any copy you make for such purposes is authorized provided that you reproduce MITRE's copyright designation and this license in any such copy.

Disclaimers

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Table of Contents

1.  Introduction
2.  Conventions Used in This Document
3.  XML Event Record Encoding Process
4.  XML Syntax Encoding
    4.1.  Field
        4.1.1.  Field Name
        4.1.2.  Field Value
        4.1.3.  Fields with No Values
        4.1.4.  Fields with More Than One Value
    4.2.  Value Types
        4.2.1.  string
        4.2.2.  binary
        4.2.3.  tag
        4.2.4.  integer
        4.2.5.  float
        4.2.6.  boolean
        4.2.7.  timestamp
        4.2.8.  duration
        4.2.9.  ipv4Address
        4.2.10.  ipv6Address
        4.2.11.  macAddress
    4.3.  Core Fields
5.  Event Extensions
    5.1.  Event Augmentation
6.  Event Logs
7.  Event Identification
8.  XML Encoded CEE Event Record Examples
9.  Acknowledgments
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  CEE XML Schema
§  Author's Address

1.  Introduction

The W3C Extensible Markup Language (XML) 1.0 format is a text-based data exchange format and is used by a larger number of devices and web services. The simplicity, readability, and efficiency of XML makes it ideal for encoding event record data. This document describes a method for encoding a CEE event record into a XML compatible format.

The XML format is documented in [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.). The CEE event record format and CLS syntax encoding requirements are defined in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.). An overview of the CEE Architecture, including the CEE event format and CLS encodings is provided in [CEE.ARCH] (CEE Board, “CEE Architecture Overview,” May 2010.).

2.  Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Guidance for use of XML follows that from [RFC3470] (Hollenbeck, S., Rose, M., and L. Masinter, “Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols,” January 2003.).

3.  XML Event Record Encoding Process

CEE makes a distinction between the event recording and the event encoding process. Once an event occurs that should be recorded, the relevant data from that event is captured as a CEE event record. When the event record is to be recorded in a log or shared, the CEE record should be encoded according to one or more CLS encodings.

In order for event consumers to consume CLS encoded event record, the consumer must simply decode the CLS encoded record into the original CEE event record. The encoding and decoding of CEE event records using of CLS encodings MUST be able to be performed without data loss.

XML encoded event records MUST be processed in a manner that meets the event record processing instructions detailed in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.).

+---------+        +----------+  encode  +-----------+
|         |  data  |  CEE     | =======> |  XML      |
|  Event  | =====> |  Event   |          |  Encoded  |
|         |        |  Record  | <======= |  Record   |
+---------+        +----------+  decode  +-----------+

4.  XML Syntax Encoding

Each XML encoded CEE event record MUST be encoded in a format that conforms to [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.) and MUST validate against the official CEE XML Event schema in Appendix A (CEE XML Schema).

Each CEE XML document SHOULD include an XML header that indicates the text encoding. If no XML header is included, the CEE XML MUST be interpreted as being encoded in UTF-8, as described in [RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.). All insignificant whitespace occurring in and around XML elements and other structures MUST be ignored.

Each CEE XML record SHOULD include an XML namespace. If it does, the namespace for each element defined in this specification MUST be "http://cee.mitre.org".

The XML syntax encoding of a CEE event record MUST begin with a "CEE" XML element and have an "Event" child element that provides the event fields. Additional child elements MAY be present and MUST be valid XML-encoded data after the "Event" element.

An XML encoded CEE event record MUST NOT exceed 64 KB (65535 octets) in size.

Examples of XML encoded CEE event records can be found in Section 8 (XML Encoded CEE Event Record Examples). The full XML CEE event record XML Schema is included in Appendix A (CEE XML Schema).

4.1.  Field

In the CLS XML encoding, CEE core field and name-value fields are encoded differently within an event record.

Name-value fields MAY appear in any order and are represented as an XML "Field" element. The field name MUST be placed in the Field element's "name" attribute. Each field has zero or more field values, which are represented within child elements that correspond to the field value's type. The text representation of the value is then placed as the value element's text node. If the field has no child field type elements, then it MUST be interpreted that the name-value field has no value.

The CEE core event fields are encoded as predefined in the CEE XML Event Schema as XML elements. Core fields MUST be specified before any name-value fields and MUST appear in the order defined in Section 4.3 (Core Fields).

4.1.1.  Field Name

The field name is an identifier to provide context to the field values.

Each CEE field name MUST be encoded as a UTF-8 XML string and contained within double quote ('"', ABNF %x22) characters. Each XML field name MUST also meet the restrictions for a valid CEE Field Name from [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.):

• A CEE field name MUST contain between 1 and 32 characters
• Each field name MUST start with an ASCII letter (ABNF ALPHA) or underscore ('_', ABNF %x5F) characters
• A field name MUST contain only number (ABNF DIGIT), ASCII letter, and underscore characters

4.1.2.  Field Value

Each field MUST have zero or more field values and each value MUST be encoded based on its CEE value type and per the W3C XML 1.0 specification ([W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.)). The encoding for each value type is defined in Section 4.2 (Value Types).

A field MUST NOT have more than 255 field values. Each encoded field value MUST NOT exceed 2 KB (2048 octets) in size.

4.1.3.  Fields with No Values

Fields that do not have a value SHOULD be removed from the encoding, if possible. Otherwise, the field MUST be recorded without a field value.

A CEE XML field having no field value and no field type indicates that the field has a nil value, or that there is no value associated with the field. Nil values have no associated type. In XML, a nil value MUST be encoded as field having no field value or field type.

For core fields (Section 4.3 (Core Fields)), an empty or nil value is indicated by a single hypen ('-', ABNF %x2D) character.

4.1.4.  Fields with More Than One Value

For fields having more than one value, the values MUST be encoded as a sequence of CEE XML field values. Each value MUST be properly encoded and enclosed within an XML element that indicates the value type.

A CEE field MUST NOT have more than 255 field values.

4.2.  Value Types

The XML encoding supports all eleven (11) CEE value types: string, binary, integer, float, boolean, timestamp, duration, ipv4Address, ipv6Address, macAddress, and tag.

All CEE value types can be supported in XML. While some value types are already natively supported in XML, the remainder can be defined within an XML Schema ([W3C.REC‑xmlschema‑1] (Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, “XML Schema Part 1: Structures,” May 2001.), [W3C.REC‑xmlschema‑2] (Biron, P. and A. Malhotra, “XML Schema Part 2: Datatypes,” May 2001.)). The XML Schema representations are provided for each CEE field type.

All CEE XML values MUST be encoded based on the type-specific rules and then formatted to be compliant with the string value encoding rules (see Section 4.2.1 (string)).

4.2.1.  string

All CEE string values MUST be a sequence of valid Unicode characters and encoded as specified in the XML header. If no XML header is present, the string values SHOULD be encoded in UTF-8.

Each string value MUST be encoded into a proper XML string value and enclosed within a CEE string ("<str>") XML element. The string encoding rules are defined in the following sections.

The XML Schema definition for the CEE string value XML element is:

<xs:element name="str">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:maxLength value="2048"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.1.1.  Encoding Rules

In XML, all values MUST be encoded as a sequence of characters according to the XML text encoding rules defined in the XML 1.0 Specification, [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.). These characters are specified in XML as being either supported, reserved, or illegal.

Illegal characters MUST NOT be specified in any form (native or escaped). Reserved characters MUST be escaped or otherwise encoded, and MUST NOT appear in their native form. All other characters are supported and can appear in either their native or XML escaped form.

4.2.1.2.  Illegal Characters

Illegal characters MUST NOT appear in CEE value or XML encoding.

XML 1.0 defines only one illegal character: NIL (ABNF %x00). A NIL character MUST NOT appear in any character encoding format (e.g., UTF-8, UTF-16) or in the XML character escape format: "&#00;".

4.2.1.3.  Reserved Characters

There are several characters that MUST only appear in an escaped form and MUST NOT appear in their native form within a XML-encoded string value. This set of disallowed string characters include the less-than sign ('<', ABNF %x3C), ampersand ('&', ABNF %x26), and ASCII control (ABNF %x01-%x1F) characters. The greater-than sign ('>', ABNF %x3E) MAY be encoded, but is not mandatory.

[W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.) defines two valid escape sequences: a character entity and a numeric character reference. Each escape sequence MUST begin when an ampersand and end with a semicolon (';', ABNF %x3B). Valid character entity references are defined in [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.), but only for a few of the more commonly escaped characters; not every XML reserved character has a character entity reference.

However, the more generic, numeric reference character reference can be used to represent any character except illegal characters. The numeric reference escape sequences MUST begin with an ampersand; followed by a pound sign ('#', ABNF %x23); the Unicode character value as a decimal, or an 'x' (ABNF %x78) and a hexadecimal value; and a final semicolon. A list of valid XML escape sequences for reserved XML characters is provided in Table 1 (XML Character Escape Sequences). Additional valid XML escape sequences are defined in [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.).

   XML-STRING  = *XML-CHAR
   XML-CHAR    = ESCAPE-SEQ / NATIVE-CHAR
   NATIVE-CHAR = *OCTET   ; except reserved or illegal characters
   ESCAPE-SEQ  = "&" ( ESCAPE-STR / ESCAPE-NUM ) ";"
   ESCAPE-STR  = 1*ALPHA  ; defined by W3C XML 1.0 Specification
   ESCAPE-NUM  = "#" ( 1*DIGIT / "x" 1*HEXDIG )

4.2.1.4.  Whitespace

CEE field values SHOULD be encoded with no leading or trailing whitespace. Whitespace characters in XML encodings are defined as a space (' ', ABNF %x20), horizontal tab (ABNF %x09), line feed (ABNF %x0A), or carriage return (ABNF %x0D).

When processing CEE XML field values, leading and trailing whitespace SHOULD be ignored. Any whitespace characters appearing within the middle of a value MUST NOT be collapsed and MUST be handled exactly as provided by the value.

4.2.2.  binary

A binary value is a series of zero or more octet values and is intended to hold binary data such as files or byte streams. It can be used to hold values that contain non-Unicode sequences or illegal XML characters.

In XML, all binary values MUST be encoded using Base64 as described in [RFC4648] (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) and by the XML Schema "base64Binary" simpleType.

To minimize the encoded message length, a Base64 encoded binary value SHOULD NOT contain any optional whitespace: space, tab, carriage return, or line feeds, as permitted by [RFC4648] (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.).

The entire CEE binary Base64 value MUST be encoded into XML as a string value, following the string encoding rules in Section 4.2.1 (string). Each binary value MUST be placed as the value of the CEE XML "binary" element and placed as a child value for the associated XML field.

The XML Schema definition for the CEE binary value XML element is:

<xs:element name="binary">
  <xs:simpleType>
    <xs:restriction base="xs:base64Binary">
      <xs:maxLength value="2048"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.3.  tag

The tag field type is a special field type within the CEE that is used to include references to event tags, or keywords. A set of standardized tag names are defined in the CEE Event Taxonomy as defined in the CEE Profile specification [CEE.Profile] (CEE Board, “CEE Profile Specification,” June 2011.).

All CEE tag values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded tag value MUST be placed as the value of the CEE XML "tag" element as the value for the XML field element.

The XML Schema definition for the CEE tag value XML element is:

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

4.2.4.  integer

Integer values are a sequence of decimal integers (ABNF DIGIT) of values %x30 through %x39 ("0" through "9"). The value of a CEE integer MUST be representable within a 64-bit signed integer, in the range [-(2^63), 2^63-1].

In XML, a CEE integer value is represented as a sequence of digits with no fractional or exponential parts. If the CEE value contains a fraction or exponent, then the number MUST be represented as a CEE float type in XML. For example, the CEE value "-100" SHOULD be a CEE integer, while "3.14159", "+12E3", and ".5" are CEE float values.

All CEE integer values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded integer value MUST be placed as the value of the CEE XML "int" element as the value for the XML field element.

The XML Schema definition for the CEE integer value "int" XML element is:

<xs:element name="int">
  <xs:simpleType>
    <xs:restriction base="xs:long"/>
  </xs:simpleType>
</xs:element>

4.2.5.  float

A float value is a representation of an arbitrary precision, finite, real number that can be represented within an IEEE 754 (Institute of Electrical and Electronics Engineers, “Standard for Binary Floating-Point Arithmetic,” August 1985.) [IEEE.754.1985] 64-bit ("double") floating point format.

A CEE float value are natively supported in XML and MUST encoded as a XML number value that has a fraction or an exponential component.

If the CEE float value has a fractional component of "0" (e.g., "-12.0"), then the value SHOULD NOT be interpreted as a CEE integer value ("-12"). That is, the precision of a numeric value SHOULD NOT be lost when encoding or decoding a CEE float value into or out of XML.

All CEE float values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded float value MUST be placed as the value of the CEE XML "float" element as the value for the XML field element.

The XML Schema definition for the CEE float value XML element is:

<xs:element name="float">
  <xs:simpleType>
    <xs:restriction base="xs:double"/>
  </xs:simpleType>
</xs:element>

4.2.6.  boolean

A boolean value supports Boolean, or binary-valued, logic and can only represent the values of "true" and "false".

Boolean is another native XML type. To encode a CEE boolean value into XML, a true value MUST be encoded as the value "true" (ABNF %x74.72.75.65). A false value MUST be encoded as the value "false" (ABNF %x66.61.6C.73.65).

The XML "true" and "false" values MUST NOT be enclosed in quotes ('"', ABNF %x22). Otherwise, the values will be interpreted as a string and not a Boolean value.

All CEE boolean values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded boolean value MUST be placed as the value of the CEE XML "bool" element as the value for the XML field element.

The XML Schema definition for the CEE boolean value "bool" XML element is:

<xs:element name="bool">
  <xs:simpleType>
    <xs:restriction base="xs:boolean">
      <xs:pattern value="true|false"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.7.  timestamp

The CEE timestamp value type allows for the specification of a date, time, and timezone information as defined in [ISO.8601.1988] (International Organization for Standardization, “Data elements and interchange formats - Information interchange - Representation of dates and times,” June 1988.). CEE timestamp values MAY be rounded to nanosecond (1E-9 second) precision.

To encode a CEE timestamp value into XML, the value MUST be formatted according to the CEE timestamp lexical representation format. All CEE timestamp values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded timestamp value MUST be placed as the value of the CEE XML "time" element as the value for the XML field element.

The XML Schema definition for the CEE timestamp value "time" XML element is:

<xs:element name="time">
  <xs:simpleType>
    <xs:restriction base="xs:dateTime">
      <xs:maxLength value="36"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.8.  duration

CEE duration value type supports values that represent a consecutive period of time in a format compliant with [ISO.8601.1988] (International Organization for Standardization, “Data elements and interchange formats - Information interchange - Representation of dates and times,” June 1988.). CEE duration values MAY be rounded to nanosecond (1E-9 second) precision.

CEE duration values are encoding into XML by encoding the duration value into the CEE duration lexical representation format. All CEE duration values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded duration value MUST be placed as the value of the CEE XML "dur" element as the value for the XML field element.

The XML Schema definition for the CEE duration value "dur" XML element is:

<xs:element name="dur">
  <xs:simpleType>
    <xs:restriction base="xs:duration">
      <xs:pattern value="[^YM]*[DT][^\.]*(\.[0-9]+)?[^\.]*"/>
      <xs:maxLength value="36"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.9.  ipv4Address

The ipv4Address field type holds a single network address within an IPv4 network.

To encode a CEE ipv4Address value into XML, the IPv4 address MUST be represented using the CEE ipv4Address lexical representation, or IPv4 dotted-decimal, format. All CEE ipv4Address values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded ipv4Address value MUST be placed as the value of the CEE XML "ipv4" element as the value for the XML field element.

The XML Schema definition for the CEE ipv4Address value "ipv4" XML element is:

<xs:element name="ipv4">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <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}))"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.10.  ipv6Address

The ipv6Address field type holds a single network address within an IPv6 network.

For a CEE ipv6Address value to be encoded into XML, the IPv6 address MUST be represented using a valid IPv6 notation. Valid CEE ipv6Address lexical representations as defined in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.) and [RFC4291] (Hinden, R. and S. Deering, “IP Version 6 Addressing Architecture,” February 2006.). Once the ipv6Address value is in a valid format, it MUST encoded as an XML-compatible string (Section 4.2.1 (string)) and placed as the value of the CEE XML "ipv6" element as the value for the XML field element.

The XML Schema definition for the CEE ipv6Address value "ipv6" XML element follows. Note that the XML pattern values are only split over multiple lines for readability.

<xs:element name="ipv6">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <!-- Normal IPv6 -->
      <xs:pattern value="([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}
             (%[^%\s]+)?"/>
      <!-- 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})*)?)(%[^%\s]+)?"/>
      <!-- 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}(%[^%\s]+)?"/>
      <!-- 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}(%[^%\s]+)?"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

4.2.11.  macAddress

The CEE macAddress field type represents Media Access Control (MAC) address values that are the physical network address of a network interface ([IEEE.802.1990] (Institute of Electrical and Electronics Engineers, “Local and Metropolitan Area Networks: Overview and Architecture,” 1990.)).

The CEE macAddress value MUST be represented according to the CEE macAddress lexical representation format defined in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.). All CEE macAddress values MUST be encoded according to the XML string encoding rules, Section 4.2.1 (string). Each encoded macAddress value MUST be placed as the value of the CEE XML "mac" element as the value for the XML field element.

The XML Schema definition for the CEE macAddress value "mac" XML element is:

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

4.3.  Core Fields

The core field names, field types, and descriptions are defined in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.).

Each encoded CEE event record MUST have a field whose name and type matches one defined in [CEE.CLS] (CEE Board, “CEE Event Record and CLS Encoding Specification,” April 2011.). A core field value MUST NOT be represented in XML using a field type other than its defined field type. A type designator MAY be used for the core fields and MUST indicate the core field's defined type.

If no value is present for a mandatory core field, then the value MUST be a single hyphen character ('-', ABNF %x2D), which represents the nil value (see Section 4.1.3 (Fields with No Values)).

When encoding the CEE record in XML, the core fields MUST appear and MUST be in the following order:

The XML Schema definition for each of these core fields can be found in Appendix A (CEE XML Schema).

5.  Event Extensions

The XML CLS Encoding allows for event extensions and supports the following extensions:

• Event Augmentation (Section 5.1 (Event Augmentation))

5.1.  Event Augmentation

The event augmentation extension allows for non-destructive modification to XML CLS Encoded event records.

Event augmentation extension sections are enclosed within an "Augmentation" element and MUST after the "Event" body element. Each augmentation section MUST have an "order" attribute that contains a unique, positive integer value. The augmentations SHOULD be processed after the "Event" body and in the ordering indicated by the "order" value.

An "Augmentation" elements first children MUST include "time", "p_sys_id", and "p_prod_id" and MUST appear in that order. The format for each of these fields is defined in the CEE core fields Section 4.3 (Core Fields).

The remainder of the augmentation section MUST consist of zero or more fields that indicate the added fields and field values. Each field MUST be of the form described in Section 4.1 (Field).

6.  Event Logs

This CLS Encoding can encode an event log of CEE event records.

A group of zero or more XML encoded event records MUST be encoded by placing each CEE XML Event "CEE" element as a child of a single XML "Log" element. That is, each CEE event record MUST be encoded as defined in Section 4 (XML Syntax Encoding).

7.  Event Identification

For devices and protocols that use MIME or Internet media types [RFC4288] (Freed, N. and J. Klensin, “Media Type Specifications and Registration Procedures,” December 2005.), the Internet media type "application/cee+xml" SHOULD be used to indicate an XML-encoded CEE event record.

8.  XML Encoded CEE Event Record Examples

Example 1—Valid

<CEE xmlns="http://cee.mitre.org">
  <Event>
    <id>example-event-1</id>
    <time>2011-04-01T12:00:00-05:00</time>
    <action>login</action>
    <status>success</status>
    <p_sys_id>10.10.1.1</p_sys_id>
    <p_prod_id>product</p_prod_id>
  </Event>
</CEE>

A small XML encoded CEE event record that contains only the core fields. The type of each value is clearly indicated using a type designator. Note how the p_sys_id value is of the form of an IPv4 address, but is a CEE string type.

Example 2—Valid

<CEE xmlns="http://cee.mitre.org">
  <Event>
    <id>example-event-2</id>
    <time>2011-04-01T12:01:00-05:00</time>
    <action>download</action>
    <status>-</status>
    <p_sys_id>host.example.com</p_sys_id>
    <p_prod_id>product</p_prod_id>
    <Field name="tags"><tag>web</tag></Field>
    <Field name="file_name"><str>example.txt</str></Field>
    <Field name="file_data">
      <binary>RmlsZSBDb250ZW50Li4uAAo=</binary>
    </Field>
  </Event>
  <Augmentation order="1">
    <time>2011-04-01T14:11:53-04:00</time>
    <status>success</status>
    <p_sys_id>relay.example.com</p_sys_id>
    <p_prod_id>cee-relay</p_prod_id>
    <Field name="tags"><tag>hipaa</tag></Field>
  </Augmentation>
</CEE>

This example adds two additional event fields to the event body, as well as an augmentation section. The augmentation section indicates that the nil "status" value is replaced by "success" and a new tag value was added to the original "tags" field by an intermediate system. The binary field type on the "file_data" field identifies that the value is a Base64 encoded binary value.

Example 3—Valid

<Log xmlns="http://cee.mitre.org">
  <CEE>
    <Event>
      <id>example-event-3</id>
      <time>2011-04-02T08:10:40-05:00</time>
      <action>login</action>
      <status>failed</status>
      <p_sys_id>host2.example.com</p_sys_id>
      <p_prod_id>product</p_prod_id>
      <Field name="acct_id"><str>bob</str></Field>
      <Field name="event_text">
        <str>Invalid username or password</str>
      </Field>
    </Event>
  </CEE>
  <CEE>
    <Event>
      <id>example-event-3</id>
      <time>2011-04-02T08:11:22-05:00</time>
      <action>login</action>
      <status>success</status>
      <p_sys_id>host2.example.com</p_sys_id>
      <p_prod_id>product</p_prod_id>
      <Field name="acct_id"><str>bob</str></Field>
    </Event>
  </CEE>
</Log>

Here is a XML encoding of an event log containing two CEE event records.

Example 4—Invalid

<CEE xmlns="http://cee.mitre.org">
  <Event>
    <time>Apr 01 12:00:00</time>
    <id>invalid-event-4</id>
    <action>login</action>
    <status>success</status>
  </Event>
  <Augmentation order="1">
    <Field name="tags"><tag>audit</tag></Field>
  </Augmentation>
</CEE>

This XML record is invalid for multiple reasons. First, the value of the time field is not presented as a valid CEE timestamp value, as required by the core time field definition. Also, the event record core fields are not in the proper order and two mandatory core fields are missing: p_sys_id and p_prod_id. Finally, the augmentation section is missing the required time, p_sys_id, and p_prod_id fields.

Example 5—Invalid

<CEE xmlns="http://cee.mitre.org">
  <Event>
    <id>invalid-event-5</id>
    <time>2011-04-01T12:00:00-05:00</time>
    <action><tag>login</tag></action>
    <status><tag>success</tag></status>
    <p_sys_id>10.0.0.1</p_sys_id>
    <Field name="p_prod_id">product</Field>
    <Field name="event_text">
      <str>Accessing file \\<share>\foo.txt</str>
    </Field>
  </Event>
</CEE>

This record not conform to the XML 1.0 Specification, [W3C.REC‑xml] (Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, “Extensible Markup Language (XML) 1.0 (2nd ed),” October 2000.)—the less than sign ('<') in the event_text field value is not properly escaped as either "&lt;", "&#x3C;", or "&#60;". Furthermore, the action, status and p_prod_id field are provided, but do not conform to the core field representations defined in Section 4.3 (Core Fields).

9.  Acknowledgments

This specification is the product of the CEE Board and community. The CEE Board would like to thank their colleagues who reviewed drafts of this and previous documents. The CEE Board also gratefully acknowledges and appreciates the many contributions from individual representing public and private section, especially Rainer Gerhards, Eric Fitzgerald, Raffael Marty, Steve Grubb, Dr. Anton Chuvakin, Dominique Karg, Peter Czanik, and George Saylor.

10.  References

10.1. Normative References

10.2. Informative References

Appendix A.  CEE XML Schema

[NOTE: Several of the XML Schema elements were split over several lines for readability. There should be no whitespace contained in any of the following XML Schema xs:pattern value attributes.]

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

  <xs:element name="CEE">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Event">
          <xs:complexType>
            <xs:sequence>
              <xs:sequence>
                <xs:element name="id">
                  <xs:simpleType>
                    <xs:union memberTypes="CEEString nil"/>
                  </xs:simpleType>
                </xs:element>
                <xs:element name="time" type="CEETimestamp"/>
                <xs:element name="action">
                  <xs:simpleType>
                    <xs:union memberTypes="CEETag nil"/>
                  </xs:simpleType>
                </xs:element>
                <xs:element name="status">
                  <xs:simpleType>
                    <xs:union memberTypes="CEETag nil"/>
                  </xs:simpleType>
                </xs:element>
                <xs:element name="p_sys_id">
                  <xs:simpleType>
                    <xs:union memberTypes="CEEString nil"/>
                  </xs:simpleType>
                </xs:element>
                <xs:element name="p_prod_id">
                  <xs:simpleType>
                    <xs:union memberTypes="CEEString nil"/>
                  </xs:simpleType>
                </xs:element>
              </xs:sequence>
              <xs:element name="Field" type="fieldType"
                          maxOccurs="249" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:group maxOccurs="unbounded" minOccurs="0"
                  ref="EventExtension"/>
      </xs:sequence>
      <xs:attribute name="profileURI" type="xs:anyURI"/>
    </xs:complexType>
  </xs:element>

  <xs:element name="Log">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" minOccurs="0" ref="CEE"/>
      </xs:sequence>
      <xs:attribute name="profileURI" type="xs:anyURI"/>
    </xs:complexType>
  </xs:element>

  <xs:group name="ceeFields">
    <xs:sequence>
      <xs:element name="id" type="CEEString"/>
      <xs:element name="time" type="CEETimestamp"/>
      <xs:element name="action" type="CEETag"/>
      <xs:element name="status" type="CEETag"/>
      <xs:element name="p_sys_id" type="CEEString"/>
      <xs:element name="p_prod_id" type="CEEString"/>
    </xs:sequence>
  </xs:group>
  <xs:complexType name="fieldType">
    <xs:group maxOccurs="255" minOccurs="0" ref="ceeFieldType"/>
    <xs:attribute name="name" use="required"/>
  </xs:complexType>
  <xs:complexType name="fieldType">
    <xs:group maxOccurs="unbounded" minOccurs="0"
        ref="ceeFieldType"/>
    <xs:attribute name="name" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:pattern value="[A-Za-z_][A-Za-z0-9_]{1,31}"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
  </xs:complexType>
  <xs:group name="ceeFieldType">
    <xs:choice>
      <xs:element ref="string"/>
      <xs:element ref="int"/>
      <xs:element ref="bool"/>
      <xs:element ref="tag"/>
      <xs:element ref="float"/>
      <xs:element ref="time"/>
      <xs:element ref="dur"/>
      <xs:element ref="ipv4"/>
      <xs:element ref="ipv6"/>
      <xs:element ref="mac"/>
      <xs:element ref="binary"/>
    </xs:choice>
  </xs:group>
  <xs:simpleType name="CEEBoolean">
    <xs:restriction base="xs:boolean">
      <xs:pattern value="true|false"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEIpv4Address">
    <xs:restriction base="CEEString">
      <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}))"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEIpv6Address">
    <xs:restriction base="CEEString">
      <!-- Normal IPv6 -->
      <xs:pattern value="([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}
        (%[^%\s]+)?"/>
      <!-- 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})*)?)(%[^%\s]+)?"/>
      <!-- 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}(%[^%\s]+)?"/>
      <!-- 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}(%[^%\s]+)?"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEMacAddress">
    <xs:restriction base="CEEString">
      <xs:pattern value="([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEETag">
    <xs:restriction base="CEEString">
      <xs:pattern value="[A-Za-z_][A-Za-z0-9_]{1,31}"/>
      <xs:maxLength value="32"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEDuration">
    <xs:restriction base="xs:duration">
      <xs:pattern value="[^YM]*[DT][^\.]*(\.[0-9]+)?[^\.]*"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEString">
    <xs:restriction base="xs:string">
      <xs:maxLength value="2048"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CEEInteger">
    <xs:restriction base="xs:long"/>
  </xs:simpleType>
  <xs:simpleType name="CEEFloat">
    <xs:restriction base="xs:double"/>
  </xs:simpleType>
  <xs:simpleType name="CEETimestamp">
    <xs:restriction base="xs:dateTime"/>
  </xs:simpleType>
  <xs:simpleType name="CEEBinary">
    <xs:restriction base="xs:base64Binary">
      <xs:maxLength value="2048"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:enumeration value="-"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="str" type="CEEString"/>
  <xs:element name="int" type="CEEInteger"/>
  <xs:element name="bool" type="CEEBoolean"/>
  <xs:element name="tag" type="CEETag"/>
  <xs:element name="float" type="CEEFloat"/>
  <xs:element name="time" type="CEETimestamp"/>
  <xs:element name="dur" type="CEEDuration"/>
  <xs:element name="ipv4" type="CEEIpv4Address"/>
  <xs:element name="ipv6" type="CEEIpv6Address"/>
  <xs:element name="mac" type="CEEMacAddress"/>
  <xs:element name="binary" type="CEEBinary"/>
  <xs:group name="EventExtension">
    <xs:choice>
      <xs:element maxOccurs="unbounded" minOccurs="0"
                  name="Augmentation">
        <xs:complexType>
          <xs:sequence>
            <xs:sequence>
              <xs:element name="id" type="CEEString" minOccurs="0"/>
              <xs:element name="time" type="CEETimestamp"/>
              <xs:element name="action" type="CEETag" minOccurs="0"/>
              <xs:element name="status" type="CEETag" minOccurs="0"/>
              <xs:element name="p_sys_id" type="CEEString"/>
              <xs:element name="p_prod_id" type="CEEString"/>
            </xs:sequence>
            <xs:element name="Field" type="fieldType"
                        maxOccurs="249" minOccurs="0"/>
          </xs:sequence>
          <xs:attribute name="order" type="xs:unsignedByte"
                        use="required"/>
        </xs:complexType>
      </xs:element>
    </xs:choice>
  </xs:group>
</xs:schema>

Author's Address