Skip to content

Latest commit

 

History

History
118 lines (83 loc) · 2.82 KB

smart-descriptions.md

File metadata and controls

118 lines (83 loc) · 2.82 KB

Smart-descriptions

An event can be hard to read as a raw data. To make the visualization and the understand of events easier, smart-descriptions help to display important information to the user.

Organization

Smart-descriptions are defined in the directory _meta/smart-descriptions.json in the format. The document is written in JSON dialect.

The root element of the document is a JSON-array. This array contains a set of smart-descriptions.

Smart-description

A smart description consists of:

  • The value (manatory): a sentence that will display information from the structured event.

    This sentence contains placeholders (delimited with curly-braces). Each placeholder encompasses a path (dot-notation); the path indicates the location of the value in the structured event that is used to replace the placeholder in the description.

    e.g: With a structured event containing:

    {
  "source": {
    "ip": "1.2.3.4"
  }
}

    The description Connection from {source.ip} will result in Connection from 1.2.3.4.

  • A list of conditions (optional): These conditions define when the description should be displayed. For a same event, the description, with the largest number of matching conditions, will succeed.

    a condition is compound of a path (dot-notation) to the field to test, and the expected value of the field (equal operation).

    e.g: With a structured event containing:

    {
  "event": {
    "kind": "alert"
  }
}

    The condition

    {
  "field": "event.kind",
  "value": "alert"
}

    will match

    while the condition

    {
  "field": "event.kind",
  "value": "event"
}

    will not match

    To test the existence of a field in the structured event, only define the field in the condition.

    e.g: The condition

    {
  "field": "event.kind"
}

    will test the existence of event.kind

  • A list of relationships (optional): The relationships help to connect information from the structured event.

    A relationship is compound of:

    • the source: the path to the field, in the structured data, to consider as the source of the relationship
    • the target: the path to the field, in the structured data, to consider as the target of the relationship
    • the type: a sentence that describes the nature of the relationship

    e.g: With a structured event containing:

    {
  "source": {
    "ip": "1.2.3.4"
  },
  "destination": {
    "ip": "5.6.7.8"
  }
}

    The relationship

    {
  "source": "source.ip",
  "target": "destination.ip",
  "type": "was connected to"
}

    will connect 1.2.3.4 to 5.6.7.8 as a was connected to relation

Example

see Windows smart-descriptions