CEE Board W. Heinbockel CEE Specification The MITRE Corporation July 8, 2011 CEE Log Syntax (CLS) Encoding: JSON (application/cee+json) draft-cls-json-06-7 Abstract This document defines a Common Event Expression (CEE) Log Syntax (CLS) encoding that is compatible with the RFC4627 JavaScript Object Notation format. This syntax encoding specifies how to encode a CEE event record using JSON, as well as how to extract the CEE event record data from a JSON 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. Heinbockel [Page 1] CEE Specification CLS Encoding: JSON July 2011 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. JSON Event Record Encoding Process . . . . . . . . . . . . . . 3 4. JSON Syntax Encoding . . . . . . . . . . . . . . . . . . . . . 4 4.1. Field . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1.1. Field Name . . . . . . . . . . . . . . . . . . . . . . 6 4.1.2. Field Value . . . . . . . . . . . . . . . . . . . . . 6 4.1.3. Fields with No Values . . . . . . . . . . . . . . . . 6 4.1.4. Fields with More Than One Value . . . . . . . . . . . 6 4.2. CEE Value Type Designator . . . . . . . . . . . . . . . . 7 4.3. Value Types . . . . . . . . . . . . . . . . . . . . . . . 7 4.3.1. string . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3.2. binary . . . . . . . . . . . . . . . . . . . . . . . . 9 4.3.3. tag . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.3.4. integer . . . . . . . . . . . . . . . . . . . . . . . 10 4.3.5. float . . . . . . . . . . . . . . . . . . . . . . . . 10 4.3.6. boolean . . . . . . . . . . . . . . . . . . . . . . . 10 4.3.7. timestamp . . . . . . . . . . . . . . . . . . . . . . 10 4.3.8. duration . . . . . . . . . . . . . . . . . . . . . . . 11 4.3.9. ipv4Address . . . . . . . . . . . . . . . . . . . . . 11 4.3.10. ipv6Address . . . . . . . . . . . . . . . . . . . . . 11 4.3.11. macAddress . . . . . . . . . . . . . . . . . . . . . . 11 4.4. Core Fields . . . . . . . . . . . . . . . . . . . . . . . 12 5. Event Extensions . . . . . . . . . . . . . . . . . . . . . . . 12 5.1. Event Augmentation . . . . . . . . . . . . . . . . . . . . 13 6. Event Logs . . . . . . . . . . . . . . . . . . . . . . . . . . 13 7. Event Identification . . . . . . . . . . . . . . . . . . . . . 13 8. JSON Encoded CEE Event Record Examples . . . . . . . . . . . . 14 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 10.1. Normative References . . . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . . 17 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 Heinbockel [Page 2] CEE Specification CLS Encoding: JSON July 2011 1. Introduction The JavaScript Object Notation (JSON) 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 JSON makes it ideal for encoding event record data. This document describes a method for encoding a CEE event record into a JSON compatible format. The JSON format is documented in [RFC4627]. The CEE event record format and CLS syntax encoding requirements are defined in [CEE.CLS]. An overview of the CEE Architecture, including the CEE event format and CLS encodings is provided in [CEE.ARCH]. 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 [RFC2119]. 3. JSON 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. JSON encoded event records MUST be processed in a manner that meets the event record processing instructions detailed in [CEE.CLS]. +---------+ +----------+ encode +-----------+ | | data | CEE | =======> | JSON | | Event | =====> | Event | | Encoded | | | | Record | <======= | Record | +---------+ +----------+ decode +-----------+ JSON Encoding Process Heinbockel [Page 3] CEE Specification CLS Encoding: JSON July 2011 4. JSON Syntax Encoding A JSON encoding of a CEE Event MUST be encoded using UTF-8 and MUST conform to [RFC3629]. Each JSON-encoded event SHOULD NOT include insignificant whitespace between JSON structures. All insignificant whitespace that is present MUST be ignored. A JSON-encoded CEE event record MUST NOT exceed 64 KB (65535 octets) in size. Examples of JSON encoded CEE event records can be found in Section 8. A valid JSON syntax encoding of a CEE event record MUST match the following ABNF [RFC5234] definition: CLS-JSON = JSON-RECORD / JSON-LOG JSON-LOG = arr-s JSON-RECORD *( nv-sep JSON-RECORD ) arr-e JSON-RECORD = obj-s EVENT-BODY *EVENT-EXT obj-e EVENT-BODY = "Event" n-sep obj-s JSON-CORE *249( nv-sep JSON-FIELD ) obj-e JSON-CORE = EVT-ID nv-sep EVT-TIME nv-sep EVT-ACTION nv-sep EVT-STATUS nv-sep EVT-SYS nv-sep EVT-PROD ; CEE Event Extensions EVENT-EXT = EVENT-AUG EVENT-AUG = "Augmentation" n-sep AUG-ARRAY AUG-ARRAY = arr-s [ AUG-OBJ *( nv-sep AUG-OBJ ) ] arr-e AUG-OBJ = obj-s AUG-CORE *249( nv-sep JSON-FIELD ) obj-e AUG-CORE = EVT-TIME nv-sep EVT-SYS nv-sep EVT-PROD ; JSON structures nv-sep = ws "," ws ; JSON name-value separator n-sep = ws ":" ws ; JSON name separator arr-s = ws "[" ws ; JSON array begin arr-e = ws "]" ws ; JSON array end obj-s = ws "{" ws ; JSON object begin obj-e = ws "}" ws ; JSON object end ws = *( %x20 / %x09 / %x0A / %x0D ) ; Space, HTab, CR, or LF EVT-ID = %x22 "id" %x22 n-sep ( json-string / JSON-NIL ) EVT-TIME = %x22 "time" %x22 n-sep json-timestamp EVT-ACTION = %x22 "action" %x22 n-sep ( json-tag / JSON-NIL ) EVT-STATUS = %x22 "status" %x22 n-sep ( json-tag / JSON-NIL ) EVT-SYS = %x22 "p_sys_id" %x22 n-sep ( json-string / JSON-NIL ) EVT-PROD = %x22 "p_prod_id" %x22 n-sep ( json-string / JSON-NIL ) Heinbockel [Page 4] CEE Specification CLS Encoding: JSON July 2011 JSON-FIELD = %x22 FIELD-NAME %x22 n-sep JSON-FIELD-VALUE JSON-FIELD-VALUE = JSON-DATATYPE / arr-s [JSON-DATA-ARRAY] arr-e JSON-DATA-ARRAY = JSON-DATATYPE *254( nv-sep JSON-DATATYPE ) JSON-DATATYPE = JSON-NATIVE-TYPE / JSON-STRING-TYPE / JSON-NIL ; string values cannot contain unescaped " \ ; or ASCII control characters (%x00-1F) JSON-STRING-TYPE = json-string / json-binary / json-tag / json-timestamp / json-ipv4Address / json-ipv6Address / json-macAddress / json-duration JSON-NATIVE-TYPE = json-boolean / json-integer / json-float JSON-NIL = arr-s arr-e ; [] json-string = %x22 ["s|"] string %x22 json-binary = %x22 ["b|"] BASE64-DATA %x22 json-tag = %x22 ["g|"] tag %x22 json-timestamp = %x22 ["t|"] timestamp %x22 json-ipv4Address = %x22 ["4|"] ipv4Address %x22 json-ipv6Address = %x22 ["6|"] ipv6Address %x22 json-macAddress = %x22 ["m|"] macAddress %x22 json-duration = %x22 ["d|"] duration %x22 json-boolean = boolean json-integer = integer json-float = float ; From the CEE Event Record and CLS Encoding Specification: FIELD-NAME = CEE-NAME CEE-NAME = CEE-STARTCHAR *31CEE-CHAR CEE-STARTCHAR = ALPHA / %x5F CEE-CHAR = CEE-STARTCHAR / DIGIT ws = %x20 / %x09 / %x0A / %x0D NONZERO-DIGIT = %x31-39 DIGIT = %x30 / NONZERO-DIGIT 4.1. Field In the CLS JSON encoding, every CEE event record field is represented as a JSON name:value pair. The field name MUST be enclosed in quotes, followed by a colon (':', ABNF %x3A), followed by a single value or a JSON array containing zero or more values. The predefined, core event fields are encoded in JSON in the same manner as other CEE fields. Core fields SHOULD appear as the first fields in an "Event" body. Heinbockel [Page 5] CEE Specification CLS Encoding: JSON July 2011 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 JSON string and contained within double quote ('"', ABNF %x22) characters. Each JSON field name MUST also meet the restrictions for a valid CEE Field Name from [CEE.CLS]: o A CEE field name MUST contain between 1 and 32 characters o Each field name MUST start with an ASCII letter (ABNF ALPHA) or underscore ('_', ABNF %x5F) characters o A field name MUST contain only number (ABNF DIGIT), ASCII letter, and underscore characters 4.1.2. Field Value Each field value MUST be encoded based on its CEE value type and per the JSON specification ([RFC4627]). The encoding for each value type is defined in Section 4.3. An 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 value MUST be recorded as a nil value. A nil value indicates that there is no value associated with the field. Nil values have no associated type. In JSON, a nil value MUST be encoded as field whose value is an empty array ('[]'). 4.1.4. Fields with More Than One Value For fields having more than one value, the values MUST be encoded into a JSON array. Values MUST be properly encoded with each value being separated by a single comma (',', ABNF %x2C) character. The sequence of comma-delimited, encoded values MUST be enclosed by a leading left bracket ('[', ABNF %x5B) and trailing right bracket (']', ABNF %x5D) character. A CEE field MUST NOT have more than 255 field values. Heinbockel [Page 6] CEE Specification CLS Encoding: JSON July 2011 4.2. CEE Value Type Designator Since JSON cannot disambiguate between the various string derived CEE value types, the JSON CEE encoding defines a value type designator that MAY be used to designate the value type for unsupported CEE value types. The value type designator is a single character followed by a pipe ('|', ABNF %x7C) character. If used, this designator MUST appear as the first two characters of the field value. A listing of all JSON type designators are shown in Table 1. +------------+------+----------------+ | Designator | ABNF | CEE Value Type | +------------+------+----------------+ | b | %x62 | binary | | d | %x64 | duration | | 4 | %x34 | ipv4Address | | 6 | %x36 | ipv6Address | | m | %x6D | macAddress | | s | %x73 | string | | g | %x67 | tag | | t | %x74 | timestamp | +------------+------+----------------+ Table 1: CEE Value Type Designators If a value type designator is provided, it MUST be honored by the decoding implementation. If the value type designator is not provided, the value MAY be treated as a CEE string type. This does not apply to core fields, defined in Section 4.4. Each value of a core field MUST be of the type specified for that core field. 4.3. Value Types The JSON CLS encoding supports all eleven (11) CEE value types: string, binary, integer, float, boolean, timestamp, duration, ipv4Address, ipv6Address, macAddress, and tag. JSON offers native support for only CEE string, integer, float, and boolean value types. All other CEE value types MUST be treated as derivations of the CEE string type. The CEE string, binary, id, timestamp, duration, ipv4Address, ipv6Address, macAddress, and tag value types MUST be encoded based on the type-specific rules and then formatted to be compliant with the string value encoding rules (see Section 4.3.1). Heinbockel [Page 7] CEE Specification CLS Encoding: JSON July 2011 Values corresponding to the integer, float, or boolean type are natively supported in JSON and MUST NOT appear within quote characters. Otherwise, these values will be treated as string types. 4.3.1. string All CEE string values MUST be a sequence of valid Unicode characters. Following from [CEE.CLS], NUL characters (ABNF %x00) MUST NOT appear in a JSON encoded string, even if escaped ("\u0000"). The CEE string value designator, "s|", MAY be prepended to the value to indicate the value type is that of a CEE string. The string value and designator MUST be encoded into a proper JSON string value. These encoding rules are defined in the following sections. 4.3.1.1. Encoding Rules In JSON, a string MUST be encoded as sequence of valid Unicode characters enclosed by a leading and trailing quote ('"', ABNF %x22) character. Reserved characters MUST be escaped or otherwise encoded, and MUST NOT appear in their native form. 4.3.1.2. Reserved Characters There are several Unicode characters that MUST only appear in an escaped form and MUST NOT appear in their native form within a JSON- encoded string value. This set of disallowed string characters include the quote, backslash ('\', ABNF %x5C), and ASCII control (ABNF %x00-%x1F) characters. The slash ('/', ABNF %x5C) character MAY be escaped. JSON uses a leading slash character for escaping. Other characters MAY appear in an escaped form. A list of JSON encoding escape sequences is provided in Table 2. Heinbockel [Page 8] CEE Specification CLS Encoding: JSON July 2011 +-----------------------------+-----------------+ | Character | Escape Sequence | +-----------------------------+-----------------+ | Quote ('"', ABNF %x22) | \" | | Slash ('/', ABNF %x2F) | \/ | | Backslash ('\', ABNF %x5C) | \\ | | Backspace (ABNF %x08) | \b | | Form Feed (ABNF %x0C) | \f | | Line Feed (ABNF %x0A) | \n | | Carriage Return (ABNF %x0D) | \r | | Tab (ABNF %x09) | \t | | Any Unicode Character | \u 4HEXDIG | +-----------------------------+-----------------+ Table 2: JSON Character Escape Sequences 4.3.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 hold values that may contain non-Unicode data or NUL characters. In JSON, all binary values MUST be encoded using Base64 as described in [RFC4648]. The Base64 encoded value SHOULD be denoted as such by adding the binary value designator ("b|") before the Base64 value. The designator informs any decoding process that the following value MUST be treated as a Base64 encoded CEE binary value. 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]. The entire CEE binary Base64 value and optional designator MUST be encoded into JSON as a string value, following the string encoding rules in Section 4.3.1. 4.3.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]. All CEE tag values and optional designator ("g|") MUST be encoded using the string encoding rules, Section 4.3.1. Heinbockel [Page 9] CEE Specification CLS Encoding: JSON July 2011 4.3.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 JSON, a CEE integer value is represented as a native JSON number as a sequence of digits with no fractional or exponential parts. If the CEE value does contain a fraction or exponent, then the number MUST be interpreted as a CEE float type. For example, the CEE value "100" SHOULD be represented as a CEE integer, while "3.14159", "12E3", and ".5" are CEE float values. 4.3.5. float A float value is a representation of an arbitrary precision, finite, real number that can be represented within an IEEE 754 [IEEE.754.1985] 64-bit floating point format. A CEE float value are natively supported in JSON and MUST encoded as a JSON 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 JSON. 4.3.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 JSON type. To encode a CEE boolean value into JSON, 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 JSON "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. 4.3.7. timestamp The CEE timestamp value type allows for the specification of a date, time, and timezone information as defined in [ISO.8601.1988]. CEE timestamp values MAY be rounded to nanosecond (1E-9 second) Heinbockel [Page 10] CEE Specification CLS Encoding: JSON July 2011 precision. To encode a CEE timestamp value into JSON, the value MUST be formatted according to the CEE timestamp lexical representation format. The timestamp value and optional designator ("t|") MUST be encoded in the same manner as a string, Section 4.3.1. 4.3.8. duration CEE duration value type supports values that represent a consecutive period of time in a format compliant with [ISO.8601.1988]. CEE duration values MAY be rounded to nanosecond (1E-9 second) precision. CEE duration values are encoding into JSON by encoding the duration value into the CEE duration lexical representation format. The duration value and optional designator ("d|") MUST be encoded as a string, as defined in Section 4.3.1. 4.3.9. ipv4Address The ipv4Address field type holds a single network address within an IPv4 network. To encode a CEE ipv4Address value into JSON, the IPv4 address MUST be represented using the CEE ipv4Address lexical representation, or IPv4 dotted-decimal, format. This value, along with the optional value type designator ("4|"), MUST be encoded as a string, Section 4.3.1. 4.3.10. ipv6Address The ipv6Address field type holds a single network address within an IPv6 network. For a CEE ipv6Address value to be encoded into JSON, the IPv6 address MUST be represented using a valid IPv6 notation. Valid CEE ipv6Address lexical representations as defined in [CEE.CLS] and [RFC4291]. Once the ipv6Address value is in a valid format, it and the ipv6Address designator ("6|") are encoded as a JSON-compatible string (Section 4.3.1). 4.3.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]). The CEE macAddress value MUST be represented according to the CEE macAddress lexical representation format defined in [CEE.CLS]. This Heinbockel [Page 11] CEE Specification CLS Encoding: JSON July 2011 value MAY then be appended to the proper type designator ("m|") and MUST be encoded as a string value (Section 4.3.1). 4.4. Core Fields The core field names, field types, and descriptions are defined in [CEE.CLS]. A CEE event record and its JSON encoding MUST have a field whose name and type matches one defined in [CEE.CLS]. A core field value MUST NOT be represented in JSON 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 an empty JSON array ('[]'), which represents the nil value (see Section 4.1.3). A list of CEE core event fields and default field types is provided here for reference. The core fields SHOULD be the first fields within an "Event" JSON object and SHOULD appear in the order listed below. +-----------+--------------+ | Field | Defined Type | +-----------+--------------+ | id | string | | time | timestamp | | action | tag | | status | tag | | p_sys_id | string | | p_prod_id | string | +-----------+--------------+ Table 3: Core Fields 5. Event Extensions The JSON CLS Encoding allows for event extensions and supports the following extensions: o Event Augmentation (Section 5.1) Heinbockel [Page 12] CEE Specification CLS Encoding: JSON July 2011 5.1. Event Augmentation The event augmentation extension allows for non-destructive modification to JSON CLS Encoded event records. Event augmentation sections MUST be placed within a single "Augmentation" array within a JSON encoded event record. The ordering of the augmentation sections is determined by their position in the Augmentation array. This array SHOULD be treated as an ordered array and the position of augmentations MUST NOT be altered. New augmentation sections MUST be appended to the end of the Augmentation JSON array. If no previous augmentations exist, the new augmentation MUST be placed as the first item in a new Augmentation JSON array and MUST NOT appear as a singleton JSON object. The augmentations SHOULD be processed after the "Event" object and using the ordering found in the Augmentation array. Each "Augmentation" object MUST include "time", "p_sys_id", and "p_prod_id". They SHOULD appear as the first fields and SHOULD be in that order. The format for each of these fields is defined in the CEE core fields Section 4.4. 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. 6. Event Logs This JSON encoding can encode an event log of CEE event records. A group of zero or more JSON encoded event records MUST be encoded by placing each JSON encoded record into a JSON array. That is, each CEE event record MUST be encoded as defined in Section 4 with each encoded record separated by a comma (',', ABNF %x2C). This sequence of JSON records MUST be inserted into an array with a leading left square bracket ('[', ABNF %x5B) and trailing right square bracket (']', ABNF %x5D) character. 7. Event Identification For devices and protocols that use MIME or Internet media types [RFC4288], the Internet media type "application/cee+json" SHOULD be used to indicate a JSON encoded CEE event record. Heinbockel [Page 13] CEE Specification CLS Encoding: JSON July 2011 8. JSON Encoded CEE Event Record Examples Example 1--Valid {"Event":{"id":"s|example-event-1", "time":"t|2011-04-01T12:00:00-05:00", "action":"g|login","status":"g|success", "p_sys_id":"s|10.10.1.1","p_prod_id":"s|product"}} A small JSON-encoded CEE event record that contains only 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 marked as being a CEE string type. Example 2--Valid {"Event":{"id":"example-event-2", "time":"2011-04-01T12:01:00-05:00","action":"download", "status":[],"p_sys_id":"10.10.0.1", "p_prod_id":"process","file_name":"example.txt", "tags":"web","file_data":"RmlsZSBDb250ZW50Li4uAAo="}, "Augmentation":[{"time":"2011-04-01T14:11:53-04:00", "status":"success","p_sys_id":"relay.example.com", "p_prod_id":"cee-relay","tags":"g|hipaa"}]} While this is a valid JSON-encoded CEE event record, the event consumer is given all JSON string values with no designators. In order to decode the event, the consumer should use the default types for the core fields and may have to guess as how to handle any other field value. For example, it is unclear how the value of file_data should be treated, as a string or a Base64 encoding. The little space that is saved by dropping the type designators results in less efficient validation and handling by the consumer. Additionally, this example shows an augmentation section that 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. Example 3--Valid Heinbockel [Page 14] CEE Specification CLS Encoding: JSON July 2011 [{"Event": {"id": "example-event-3", "time" : "t|2011-04-02T08:10:40-05:00", "action" : "g|login", "status" : "g|failed", "p_sys_id" : "host2.example.com", "p_prod_id" : "proc1", "acct_id" : "bob", "event_text" : "Invalid username or password" }}, {"Event": {"id": "example-event-3", "time" : "t|2011-04-02T08:11:22-05:00", "action" : "g|login", "status" : "g|success", "p_sys_id" : "host2.example.com", "p_prod_id" : "proc1", "acct_id" : "bob" }} ] Here is a JSON encoding of an event log containing two CEE event records. Additional whitespace has been included between the JSON structures to enhance readability. This whitespace is insignificant and SHOULD NOT appear on JSON Encoded CEE Events. Example 4--Invalid {"Event":{"time":"s|Apr 01 12:00:00", "id":"invalid-event-4","action":"login", "status":"success"},"Augmentation":{"tags":"g|audit"}} This JSON record is invalid as the value of time is indicated to be a CEE string value. For the core time field, the value type is required to be a CEE timestamp value. In addition, time is not in a valid CEE timestamp format. Finally, the event record is missing two mandatory core fields: p_sys_id and p_prod_id. Example 5--Invalid { time : "2011-04-01T12:00:00-05:00", id : "invalid-event-5", p_sys_id : "10.0.0.1", p_prod_id : "process", event_text: "Accessing file \\share\foo.txt", action : "g|login", status : "g|success" } This record is not in proper JSON, as defined in [RFC4627]. Heinbockel [Page 15] CEE Specification CLS Encoding: JSON July 2011 Additionally, the record is missing the mandatory "Event" JSON object. The field name strings are not contained in quotes and the event_text value has an unescaped backslash ('\', ABNF %x5C). 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 [CEE.CLS] CEE Board, "CEE Event Record and CLS Encoding Specification", April 2011. [IEEE.754.1985] Institute of Electrical and Electronics Engineers, "Standard for Binary Floating-Point Arithmetic", IEEE Standard 754, August 1985. [IEEE.802.1990] Institute of Electrical and Electronics Engineers, "Local and Metropolitan Area Networks: Overview and Architecture", IEEE Standard 802, 1990. [ISO.8601.1988] International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, February 2006. Heinbockel [Page 16] CEE Specification CLS Encoding: JSON July 2011 [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. 10.2. Informative References [CEE.ARCH] CEE Board, "CEE Architecture Overview", May 2010. [CEE.Profile] CEE Board, "CEE Profile Specification", June 2011. [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and Registration Procedures", BCP 13, RFC 4288, December 2005. Author's Address William Heinbockel The MITRE Corporation 202 Burlington Rd Bedford, MA 01730 United States Phone: +1 781-271-2615 Email: heinbockel@mitre.org Heinbockel [Page 17]