Base Event, metadata description updates

events/base_event.json

@@ -12,6 +12,7 @@
       "profiles/security_control.json"
     ],
     "activity_id": {
+      "description": "The normalized identifier of the activity that triggered the event. Each event class defines its own set of activity values. Use <code>0</code> (Unknown) when the activity cannot be determined, and <code>99</code> (Other) when the activity does not match any defined value &mdash; in that case, populate <code>activity_name</code> with the source-specific label.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -24,14 +25,17 @@
       }
     },
     "activity_name": {
+      "description": "The event activity name, as defined by the <code>activity_id</code>. When <code>activity_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific activity label. For all other <code>activity_id</code> values, this should match the caption defined for that <code>activity_id</code> enum value.",
       "group": "classification",
       "requirement": "optional"
     },
     "category_name": {
+      "description": "The event category name, as defined by the <code>category_uid</code> value. The value should match the caption defined for the corresponding <code>category_uid</code> enum value (e.g., <code>\"Findings\"</code> for <code>category_uid: 2</code>).",
       "group": "classification",
       "requirement": "optional"
     },
     "category_uid": {
+      "description": "The category unique identifier of the event. Each event class belongs to exactly one category. Producers must set this to the category defined by the event class being used. Use <code>0</code> (Uncategorized) only for the base event class.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -41,10 +45,12 @@
       }
     },
     "class_name": {
+      "description": "The event class name, as defined by the <code>class_uid</code> value. The value should match the caption defined for the corresponding <code>class_uid</code> (e.g., <code>\"Detection Finding\"</code> for <code>class_uid: 2004</code>).",
       "group": "classification",
       "requirement": "optional"
     },
     "class_uid": {
+      "description": "The unique identifier of the event class. A class describes the attributes available in an event. Producers must set this to the <code>uid</code> defined in the event class definition. For example, <code>Detection Finding</code> is <code>2004</code>.",
       "group": "classification",
       "requirement": "required",
       "enum": {
@@ -54,93 +60,112 @@
       }
     },
     "count": {
+      "description": "The number of events aggregated into this single record. Only populate for aggregate events; when set, <code>start_time</code> and <code>end_time</code> should also be provided to define the aggregation window.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "duration": {
-      "description": "The event duration or aggregate time, the amount of time the event covers from <code>start_time</code> to <code>end_time</code> in milliseconds.",
+      "description": "The elapsed time of the aggregation window in milliseconds, from <code>start_time</code> to <code>end_time</code>. Only populate for aggregate events (<code>count</code> &gt; 1). The value should equal <code>end_time - start_time</code>.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "end_time": {
-      "description": "The end time of a time period, or the time of the most recent event included in the aggregate event.",
+      "description": "The time of the most recent event in an aggregate (<code>count</code> &gt; 1). Do not populate for discrete, point-in-time events &mdash; use <code>time</code> alone. Subclasses such as findings may redefine this for their own time-range semantics.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "enrichments": {
+      "description": "Additional information from an external data source associated with the event. Use this to attach contextual data that was not part of the original event, such as geo-location for an IP address, threat intelligence tags, or asset ownership details. Each enrichment should reference the attribute it enriches by name.",
       "group": "context",
       "requirement": "optional"
     },
     "message": {
+      "description": "A human-readable description of the event, as defined by the source. This should be a concise, meaningful summary suitable for display in a UI or alert notification &mdash; not a raw log line. For example: <code>\"User john_doe logged in from 10.0.0.1\"</code> rather than a raw syslog string.",
       "group": "primary",
       "requirement": "recommended"
     },
     "metadata": {
+      "description": "The metadata object describes the event producer, schema version, and processing information. Producers <b>must</b> populate <code>metadata.product</code> to identify the data source, and <code>metadata.version</code> to indicate the OCSF schema version used. Consumers rely on this to interpret the event correctly.",
       "group": "context",
       "requirement": "required"
     },
     "observables": {
+      "description": "The observables array surfaces key indicators and entities from the event in a single, consistent location for downstream correlation and detection. Each entry references an attribute path within the event (e.g., <code>src_endpoint.ip</code>) along with its type and value, enabling consumers to extract IOCs without parsing the full event structure.",
       "group": "primary",
       "requirement": "recommended"
     },
     "raw_data": {
+      "description": "The original event data as received from the source, before normalization into OCSF. Populate this with the verbatim log line, JSON payload, or other native format for forensic and debugging purposes. This field is not intended for structured querying &mdash; use the normalized OCSF attributes instead.",
       "group": "context",
       "requirement": "optional"
     },
     "raw_data_hash": {
+      "description": "A fingerprint (hash) of the <code>raw_data</code> content. Use this to verify the integrity of the original event data or to deduplicate events.</br>Only populate when <code>raw_data</code> is also set.",
       "group": "context",
       "requirement": "optional"
     },
     "raw_data_size": {
+      "description": "The size of the original event data (as captured in <code>raw_data</code>) in bytes, before OCSF normalization. Useful for metering and capacity planning.</br>Only populate when <code>raw_data</code> is also set.",
       "group": "context",
       "requirement": "optional"
     },
     "severity": {
+      "description": "The event severity label, normalized to the caption of the <code>severity_id</code> value. When <code>severity_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific severity label. For all other values, this should match the caption defined for that <code>severity_id</code> enum value (e.g., <code>\"High\"</code> for <code>severity_id: 4</code>).",
       "group": "classification",
       "requirement": "optional"
     },
     "severity_id": {
+      "description": "The normalized severity of the event. Producers must map their source severity to one of the defined values: <code>1</code> (Informational), <code>2</code> (Low), <code>3</code> (Medium), <code>4</code> (High), <code>5</code> (Critical), or <code>6</code> (Fatal). Use <code>0</code> (Unknown) when severity cannot be determined, and <code>99</code> (Other) with a populated <code>severity</code> string when the source value does not map to a defined level.",
       "group": "classification",
       "requirement": "required"
     },
     "start_time": {
-      "description": "The start time of a time period, or the time of the least recent event included in the aggregate event.",
+      "description": "The time of the earliest event in an aggregate (<code>count</code> &gt; 1). Do not populate for discrete, point-in-time events &mdash; use <code>time</code> alone. Subclasses such as findings may redefine this for their own time-range semantics.",
       "group": "occurrence",
       "requirement": "optional"
     },
     "status": {
+      "description": "The event status label, normalized to the caption of the <code>status_id</code> value. When <code>status_id</code> is <code>99</code> (Other), this attribute <b>must</b> contain the source-specific status label. For all other values, this should match the caption defined for that <code>status_id</code> enum value (e.g., <code>\"Success\"</code> for <code>status_id: 1</code>). Use this family of attributes to convey the outcome of the activity described by the event.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_code": {
+      "description": "The source-specific status or error code as reported by the event source. For example, a Windows logon failure code (<code>0x18</code>), an HTTP response code (<code>403</code>), or an AWS API error code. This preserves the original code for detailed troubleshooting beyond what <code>status_id</code> conveys.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_detail": {
+      "description": "A human-readable description providing additional context about the event outcome. Use this to convey details that go beyond the normalized <code>status_id</code> and source-specific <code>status_code</code>, such as a failure reason or error message. For example: <code>\"Account locked after 5 failed attempts\"</code>.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_id": {
+      "description": "The normalized status of the event outcome. Producers should map their source outcome to <code>1</code> (Success) or <code>2</code> (Failure). Use <code>0</code> (Unknown) when the outcome cannot be determined, and <code>99</code> (Other) with a populated <code>status</code> string when the source value does not map cleanly.",
       "group": "primary",
       "requirement": "recommended"
     },
     "time": {
+      "description": "The primary timestamp of the event &mdash; when the activity actually occurred at the source. For aggregate events (<code>count</code> &gt; 1), set this to <code>start_time</code> (the earliest event in the aggregate) to preserve causal ordering and consistent timeline alignment. This is the most important temporal attribute and <b>must</b> be a UTC epoch value in milliseconds (e.g., <code>1618524549901</code>). Mappers should use the most precise and authoritative timestamp available from the source. Do not confuse with <code>metadata.logged_time</code> (when the event was ingested) or <code>metadata.processed_time</code> (when it was normalized).",
       "group": "occurrence",
       "requirement": "required"
     },
     "timezone_offset": {
+      "description": "The number of minutes that the reported event <code>time</code> is ahead or behind UTC, in the range -1,080 to +1,080. This allows consumers to reconstruct the local time at the event source. For example, US Eastern Standard Time is <code>-300</code>. Populate this when the source provides local time zone information.",
       "group": "occurrence",
       "requirement": "recommended"
     },
     "type_name": {
+      "description": "The event type name, combining the class and activity (e.g., <code>\"Detection Finding: Create\"</code>). The value should match the <code>class_name</code> and <code>activity_name</code> joined by <code>\": \"</code>.",
       "group": "classification",
       "requirement": "optional"
     },
     "type_uid": {
+      "description": "The event type identifier. Producers <b>must</b> compute this as <code>class_uid * 100 + activity_id</code>. It uniquely identifies the combination of event class and activity across the entire schema. For example, <code>Detection Finding: Create</code> is <code>200401</code>.",
       "group": "classification",
       "requirement": "required"
     },
     "unmapped": {
+      "description": "A container for source-specific attributes that do not map to any defined OCSF attribute. Use this to preserve valuable source data that would otherwise be lost during normalization. The keys and values are specific to the event source. Consumers should not rely on a stable structure within this field.",
       "group": "context",
       "requirement": "optional"
     }

events/findings/finding.json

@@ -9,7 +9,7 @@
       "profiles/incident.json"
     ],
     "activity_id": {
-      "description": "The normalized identifier of the finding activity.",
+      "description": "The normalized identifier of the finding activity. Use <code>1</code> (Create) when a finding is first generated, <code>2</code> (Update) when an existing finding is modified (e.g., severity change, new evidence), and <code>3</code> (Close) when a finding is resolved or dismissed.",
       "enum": {
         "1": {
           "caption": "Create",
@@ -26,7 +26,7 @@
       }
     },
     "activity_name": {
-      "description": "The finding activity name, as defined by the <code>activity_id</code>."
+      "description": "The finding activity name, as defined by the <code>activity_id</code>. When <code>activity_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific activity label."
     },
     "comment": {
       "description": "A user provided comment about the finding.",
@@ -55,24 +55,24 @@
       "profile": null
     },
     "end_time": {
-      "description": "The time of the most recent event included in the finding.",
+      "description": "The time of the most recent event or finding that contributed to this finding.",
       "requirement": "optional"
     },
     "finding_info": {
       "group": "primary",
       "requirement": "required"
     },
     "start_time": {
-      "description": "The time of the least recent event included in the finding.",
+      "description": "The time of the earliest event or finding that contributed to this finding.",
       "requirement": "optional"
     },
     "status": {
-      "description": "The normalized status of the Finding set by the consumer normalized to the caption of the status_id value. In the case of 'Other', it is defined by the source.",
+      "description": "The finding lifecycle status label, normalized to the caption of the <code>status_id</code> value. Unlike event-level status (which indicates success/failure of an activity), finding status tracks the review workflow: whether the finding is new, being investigated, suppressed, or resolved. When <code>status_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific status label.",
       "group": "context",
       "requirement": "optional"
     },
     "status_id": {
-      "description": "The normalized status identifier of the Finding, set by the consumer.",
+      "description": "The normalized finding lifecycle status identifier. This tracks the review and triage workflow of the finding, not the outcome of the underlying activity. Producers should set this to reflect the current state of the finding in their system (e.g., <code>1</code> for newly created findings, <code>4</code> when remediated).",
       "group": "context",
       "requirement": "recommended",
       "enum": {

events/findings/incident_finding.json

@@ -7,7 +7,7 @@
   "name": "incident_finding",
   "attributes": {
     "activity_id": {
-      "description": "The normalized identifier of the Incident activity.",
+      "description": "The normalized identifier of the incident activity. Use <code>1</code> (Create) when an incident is first opened, <code>2</code> (Update) when an existing incident is modified (e.g., new findings added, priority changed, assignee updated), and <code>3</code> (Close) when the incident is resolved.",
       "requirement": "required",
       "enum": {
         "1": {
@@ -25,7 +25,7 @@
       }
     },
     "activity_name": {
-      "description": "The Incident activity name, as defined by the <code>activity_id</code>.",
+      "description": "The incident activity name, as defined by the <code>activity_id</code>. When <code>activity_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific activity label.",
       "requirement": "optional"
     },
     "assignee": {
@@ -68,7 +68,7 @@
       "requirement": "recommended"
     },
     "end_time": {
-      "description": "The time of the most recent event included in the incident.",
+      "description": "The time of the most recent event or finding that contributed to this incident.",
       "requirement": "optional"
     },
     "finding_info_list": {
@@ -105,16 +105,16 @@
       "requirement": "recommended"
     },
     "start_time": {
-      "description": "The time of the least recent event included in the incident.",
+      "description": "The time of the earliest event or finding that contributed to this incident.",
       "requirement": "optional"
     },
     "status": {
-      "description": "The normalized status of the Incident normalized to the caption of the status_id value. In the case of 'Other', it is defined by the source.",
+      "description": "The incident lifecycle status label, normalized to the caption of the <code>status_id</code> value. This tracks the incident management workflow from initial triage through resolution. When <code>status_id</code> is <code>99</code> (Other), this <b>must</b> contain the source-specific status label.",
       "group": "primary",
       "requirement": "recommended"
     },
     "status_id": {
-      "description": "The normalized status identifier of the Incident.",
+      "description": "The normalized incident lifecycle status identifier. This tracks the incident management workflow. Producers should set this to reflect the current state in their incident management system.",
       "group": "primary",
       "requirement": "required",
       "enum": {

extensions/windows/objects/query_evidence.json

@@ -9,7 +9,7 @@
       "requirement": "recommended"
     },
     "reg_value": {
-      "description": "The registry key object describes a Windows registry value.",
+      "description": "The registry value object describes a Windows registry value.",
       "group": "primary",
       "requirement": "recommended"
     }

profiles/datetime.json

@@ -1,7 +1,7 @@
 {
   "caption": "Date/Time",
-  "description": "This profile defines date/time attributes as defined in RFC-3339. For example 1985-04-12T23:20:50.52Z.",
+  "description": "When applied, this profile adds a sibling attribute of data type <code>datetime_t</code> (RFC-3339 string) wherever a <code>timestamp_t</code> attribute appears in the event class. This provides human-readable date/time representations alongside the epoch-millisecond timestamps. For example, <code>time</code> (<code>timestamp_t</code>) would gain a <code>time_dt</code> (<code>datetime_t</code>) sibling such as <code>\"1985-04-12T23:20:50.52Z\"</code>. See <a target='_blank' href='https://www.rfc-editor.org/rfc/rfc3339.html'>RFC-3339</a>.",
   "meta": "profile",
   "name": "datetime",
   "attributes": {}
-}
+}

profiles/host.json

@@ -1,16 +1,18 @@
 {
   "caption": "Host",
-  "description": "The attributes that identify host/device attributes.",
+  "description": "Adds host and actor context to event classes. Apply this profile when the event originates from or is observed on a specific host or device, and when the initiating user, process, or service is known. All event classes include this profile by default through the base event.",
   "meta": "profile",
   "name": "host",
   "annotations": {
     "group": "primary"
   },
   "attributes": {
     "actor": {
+      "description": "The user, process, or service that initiated the activity on the host. For system-level events this is typically a process; for IAM events it is typically a user or role.",
       "requirement": "optional"
     },
     "device": {
+      "description": "The host or device where the activity was observed. Populate with details such as hostname, IP address, OS, and hardware identifiers when available from the source.",
       "requirement": "recommended"
     }
   }