I apologize for the formatting on this. The text can also be seen in non-mangled form here:
Timestamp:
https://docs.google.com/document/d/1HJqhvzO35h62gQGPvghVRIAtQrZn3_J__0UcDAj-NXY/edit#heading=h.de8ah59mobqf Timestamp Precision:
https://docs.google.com/document/d/1HJqhvzO35h62gQGPvghVRIAtQrZn3_J__0UcDAj-NXY/edit#heading=h.sp8ake5xbk8j Custom Properties:
https://docs.google.com/document/d/1HJqhvzO35h62gQGPvghVRIAtQrZn3_J__0UcDAj-NXY/edit#heading=h.8072zpptza86 From: <
cti-stix@lists.oasis-open.org > on behalf of "Wunder, John A." <
jwunder@mitre.org >
Date: Thursday, May 5, 2016 at 2:39 PM
To: "
cti-stix@lists.oasis-open.org " <
cti-stix@lists.oasis-open.org >
Subject: [cti-stix] Motion to move timestamp, timestamp precision, and custom properties to draft status
Hi everyone,
Thanks to some suggestions by Allan Thompson we have some good language nailed down for timestamp, timestamp precision, and custom properties. Given that, the recent agreement on the working call, and a lack of further comments I’d like to make a motion:
I motion that the STIX SC accept by unanimous consent the timestamp, timestamp precision, and custom properties text contained in the STIX pre-draft specifications and duplicated below, and that the SC allow the STIX editors to move these sections to DRAFT
status. If after a period of 5 business days we don’t hear any substantive (non-editorial) objections we will move it from REVIEW to DRAFT.
Thanks!
John
---
?4.8.? Timestamp
Type
Name: timestamp
Status: Review
MVP :
Yes
This
section defines the timestamp
type. Most discrete timestamps (i.e. not time ranges or relative times) in STIX have a corresponding optional field that indicates the precision of the timestamp, of type
timestamp-precision .
In cases where the timestamp is metadata about the STIX construct, such as creation and modification times for STIX top-level objects, the timestamp will not have the corresponding precision field. In these cases, the precision is "full".
?4.8.1.? Format
YYYY-MM-DDTHH:mm:ss.ssssssZ
The
timestamp field MUST
be a valid RFC 3339-formatted timestamp.
The
timestamp MUST
be represented in the UTC timezone and MUST
use the 'Z' designation to indicate this.
The
optional precision field, if present, MUST
a value from the timestamp-precision
enumeration.
The
default value for the precision field is "full", so omitting the field is equivalent to explicitly specifying "full".
A
value of "full" indicates that the value in the timestamp field is precise to the full number of digits in the timestamp value (including any fractional seconds, such as milliseconds or microseconds).
A
value of “minute”, “hour”, “day”, “month”, or “year” indicates that the timestamp value is precise to that as a lower bound (the precision window is the timestamp value plus one unit of the precision value). For example, if the timestamp value is 2016-04-25T13:00:00Z
and the precision value is "hour", the time is greater than or equal to 2016-04-25T13:00:00Z and less than 2016-04-25T14:00:00Z.
When
specifying a precision other than "full", the time portion of the timestamp field
MUST
contain zeroes for all fields beyond the specified precision while the date portion MUST contain "01" for all fields beyond the specified precision.
For
example, if the precision field is "month", the timestamp field must contain "01" for the day field and "00" for the hour, minute, and second fields such as 2016-12-01T00:00:00Z.
The
timestamp precision field is always nested at the same level as the timestamp field.
The
property name for the precision field is [timestamp_field_name]_precision .
For
example, if the key of the timestamp field is “created_at”, the key of the precision field is “created_at_precision”.
?4.8.2.? Examples
A
timestamp known only to a year would look like:
{
"timestamp":
"2016-01-01T00:00:00Z",
"timestamp_precision":
"year"
}
A
timestamp known only to an hour would look like:
{
"timestamp":
"2016-01-20T12:00:00Z",
"timestamp_precision":
"hour"
}
A
timestamp known to a second would look like:
{
"timestamp":
"2016-01-20T12:31:12Z"
}
A
timestamp known to 5 digit sub second precision would look like:
{
"timestamp":
"2016-01-20T12:31:12.12345Z"
}
?4.9.? Timestamp
Precision
Type
Name: timestamp-precision
Status: Review
MVP :
Yes
A
timestamp-precision
represents the precision options for a given timestamp. Its value MUST
be
one of "year", "month", "day", "hour", "minute", or "full”.
<<<<<<<<<SNIP>>>>>>>>>
?5.1.? Custom
Properties
Status: Review
MVP :
Yes
The
authors of this specification recognize that there will be cases where certain information exchanges can be improved by adding fields that are not specified nor reserved in this document; these fields are called
Custom
Properties .
This section provides guidance and requirements for how producers can use Custom Properties and how consumers should interpret them in order to extend STIX in an interoperable manner.
?5.1.1.? Requirements
Producers
MAY
create any number of Custom Properties in a STIX TLO.
Custom
Properties SHOULD
start with “x_” followed by a source unique identifier (like a domain name), an underscore and then the name. For example:
x_examplecom_customfield .
Custom
Property keys SHOULD
have a minimum length of 3 characters (including the prefix) and a maximum length of 30 characters.
Custom
Property keys MUST
not be longer than 256 characters.
Custom
Properties that are not prefixed with “x_” may be used in a future version of the specification for a different meaning. If compatibility with future versions of this specification is required, the “x_” prefix
MUST
be used.
Custom
Properties SHOULD
be uniquely named when produced by the same source and SHOULD
use a consistent namespace prefix (e.g., a domain name).
Custom
Properties SHOULD
only
be used when there is no existing field defined by the STIX specification that fulfills that need.
Any
consumer that receives a STIX document with one or more Custom Properties
MAY :
process
the properties in the manner intended by the producer, if known
refuse
to process the document further
silently
ignore non-understood properties and continue processing the document
The
reporting and logging of errors originating from the processing of Custom Properties depends heavily on the technology used to transport the STIX document and is therefore not covered in this specification.
Consumers
that receive a STIX TLO that contains one or more Custom Properties that are understood
MUST
process the Custom Properties according to the rules for that Custom Property.
Non-Normative:
Producers
of STIX documents that contain Custom Properties should be well aware of the variability of consumer behavior depending on whether or not the consumer understands the Custom Properties present in a STIX TLO. Rules for processing Custom Properties should be
well defined and accessible to any consumer that would be reasonably expected to parse them.
?5.1.2.? Examples
{
...,
"x_acmeinc_scoring":
{
"impact":
"high",
"probability":
"low"
},
...
}