How to write smart descriptions

An event can be hard to read as a raw data. To make the visualization and the understanding of events easier, smart descriptions help displaying 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 components

A smart description consists of:

The value (mandatory):

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 a 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"
    }
}
```
This condition will match
```
{
    "field": "event.kind",
    "value": "alert"
}
```
while the condition will not match
```
{
    "field": "event.kind",
    "value": "event"
}
```
To test the existence of a field in the structured event, define the field in the condition only.

e.g:

This condition will test the existence of event.kind:
```
{
    "field": "event.kind"
}
```
A list of relationships (optional): The relationships help connect information from the structured event.

A relationship is a 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"
    }
}
```
This relationship will connect 1.2.3.4 to 5.6.7.8 as a was connected to relation:
```
{
    "source": "source.ip",
    "target": "destination.ip",
    "type": "was connected to"
}
```

Example

See Windows smart-descriptions.