Add event.reference field

[MikePaquette]

ECS already has a rule.reference field to contain a reference URL to additional information about a rule used to generate an event/alert. The URL can point to the vendor’s documentation about the rule, or if that’s not available, it can also be a link to a more general page describing this type of alert.

However some systems provide not only a reference to the rule that created the event, but also to the specific instance of the event or alert itself.

This URL can link to another system where additional or in-depth investigation the specific occurrence of this event can take place. Alert events, indicated by event.kind:alert, are a common use case for this field.

example: https://mysystem.mydomain.com/alert/5271dedb-f5b0-4218-87f0-4ac4870a38fe

This new field event.reference is for storing such URL's.

• Add event.reference field
• Add event.url field

[webmat]

Please add a changelog :-)

In all other places where we have URLs pointing to reference docs, the fields are called .reference. However, since this field is specifically not made to point to reference docs, I wonder if we should name this one .reference?

To give an example, if someone wants to add reference URLs to their Windows events, event.reference would sound like the field to put the link to the Microsoft docs, when in fact it's not. And this example also demonstrates that we could have a conflict, if someone wants to add a link to the event itself in AD (the intended use for this field), as well as the reference URL to their events.

WDYT?

[MikePaquette]

@webmat good observations.

In all other places where we have URLs pointing to reference docs, the fields are called .reference. However, since this field is specifically not made to point to reference docs, I wonder if we should name this one .reference?

Yes, this will be the first use of *.reference that potentially links to an "active" resource that goes beyond static documentation. However, on its own, I'm not sure this is a consistency problem, as it's still a reference, just happens to be active.

To give an example, if someone wants to add reference URLs to their Windows events, event.reference would sound like the field to put the link to the Microsoft docs, when in fact it's not. And this example also demonstrates that we could have a conflict, if someone wants to add a link to the event itself in AD (the intended use for this field), as well as the reference URL to their events.

I had been thinking that this field could be used for either a static link to docs or an active link. However, you raise the point of what to do if both are desired.

One idea is to recommend ECS rule.reference as the field where the reference URL to their events would be populated. However, after thinking of it more, I can see that it might be a stretch to think of a Windows event being created by a rule.

Can we leverage (and more carefully document) the distinction between event.id and event.code to guide the reference fields?

For now, I've enhanced the definition of this new field event.reference to highlight the either/or nature of the URL, and updated the changelog. We can discuss further.

[webmat]

@MikePaquette Any time we give a dual purpose to a field, the two purposes should be mutually exclusive (e.g. similar concepts on Linux and Windows), where both definitions couldn't be applicable at the same time.

This is not the case here. We need two fields, for situations where both a link to generic reference documentation and a link to a specific instance of an event/alert are applicable.

Perhaps we can simply achieve this with an additional field called event.url (open to naming suggestions, as usual), where:

• event.reference: link to reference documentation (in line with meaning of other .reference fields)
• event.url: URL where more details about this specific instance of the event or alert are available.

I believe the current pressing need is not for the reference-type URL, but for the link to a specific instance, correct? If that's the case, I'm ok with either adjusting this PR to address only event.url, or of course we can introduce both in this PR.

We need to home in on a name quickly, if we want this in ECS 1.5.0.

[webmat]

Quoting @MikePaquette from elsewhere

I had convinced myself that this was not a dual purpose, but rather two levels of detail for the same purpose, but I see your point, and I like the elegance of simply adding the second field event.url. Can we actually use event.url given that we have a url.* field set? I'll take this back to the PR, but yes, this is for 1.5

I know in general we avoid creating fields with the same name as existing field sets. However I don't think this is a case we need to be worried about. My thinking is that a full url breakdown is only necessary in cases where we want to analyze its different parts (e.g. stats on file extensions, threat hunt on domains, etc). In the case of event.url there is no need to break this down, as it's simply meant for someone's pipeline to give them back a useful URL to click on. No analysis of these URLs are necessary.

So if you like the name event.url, I also like its simplicity and I think we can move forward with that :-)

[MikePaquette]

thanks @webmat I added new field event.url and adjusted the description of event.reference.

[webmat]

LGTM, thanks for the addition of event.url.

I'll make the two small typo fixes noted below and merge.

[webmat]

Suggested change

	This URL links to a static definition of the this event
	This URL links to a static definition of the this event.

[webmat]

Suggested change

	URL linking to an external system to continue investigtion of this event.
	URL linking to an external system to continue investigation of this event.