Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs]Adds timeline schema and API #50

Merged
merged 6 commits into from
Jul 6, 2020
+726 −19
Merged

[Docs]Adds timeline schema and API #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5aba25a
adds timeline schema
Jul 5, 2020
b0997e7
starts create timeline endpoint
Jul 5, 2020
e0c70c2
create timeline cont
Jul 6, 2020
ccce481
finishes api
Jul 6, 2020
0922a7d
corrections after review
Jul 6, 2020
7b2060a
UUID for template ID
Jul 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 0 additions & 14 deletions docs/siem/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,3 @@
// :doctype: book
// :siem-soln: Elastic Security
// :siem-app: Elastic Security app
// :siem-ui: Elastic Security UI
// :ml-dir: {stack-docs-root}/docs/en/stack/ml
// :sn: ServiceNow

// Removed for merging with unified security docs
// = SIEM Guide

include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]

include::{docs-root}/shared/attributes.asciidoc[]
Expand All @@ -23,7 +13,3 @@ include::detections/machine-learning/ml-index.asciidoc[]
include::detections/detections-index.asciidoc[]

include::cases/cases-index.asciidoc[]

// include::siem-apis.asciidoc[]

// include::reference/ref-index.asciidoc[]
252 changes: 252 additions & 0 deletions docs/siem/reference/timeline-schema.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,255 @@
[role="xpack"]
== Timeline schema

The Timeline schema lists all the JSON fields and objects required to create a
Timeline or a Timeline template using the Create timeline API.

IMPORTANT: All column, dropzone, and filter fields must be
{ecs-ref}[ECS fields].

This screenshot maps the Timeline UI components to their JSON objects:

[role="screenshot"]
image::images/timeline-object-ui.png[]

. <<timeline-object-title, Title>> (`title`)
. <<timeline-object-desc, Description>> (`description`)
. <<timeline-object-global-notes, Global notes>> (`globalNotes`)
. <<timeline-object-daterange, Time filter>> (`dateRange`)
. <<timeline-object-dropzone, Dropzone>> (each clause is contained in
its own `dataProviders` object)
. <<timeline-object-kqlmode, KQL bar mode>> (`kqlMode`)
. <<timeline-object-kqlquery, KQL bar query>> (`kqlQuery`)
. <<timeline-object-eventtype, Event types included in Timeline results>>
(`eventType`)
. <<timeline-object-filters, Additional filters>> (`filters`)
. <<timeline-object-columns, Column headers>> (`columns`)
. <<timeline-object-event-notes, Event-specific notes>> (`eventNotes`)

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|[[timeline-object-columns]]`columns` |<<col-obj, columns[]>> |The timeline's
columns.
|`created` |Float |The time the timeline was created, using a 13-digit Epoch
timestamp.
|`createdBy` |String |The user who created the timeline.
|[[timeline-object-dropzone]]`dataProviders`
|<<dataProvider-obj, dataProviders[]>> |Object containing dropzone query
clauses.
|[[timeline-object-daterange]]`dateRange` |dateRange a|The timeline's search
period:

* `end`: The time up to which events are searched, using a 13-digit Epoch
timestamp.
* `start`: The time from which events are searched, using a 13-digit Epoch
timestamp.

|[[timeline-object-desc]]`description` |String |The timeline's description.
|[[timeline-object-event-notes]]`eventNotes` |<<eventNotes-obj, eventNotes[]>>
|Notes added to specific events in the timeline.
|[[timeline-object-eventtype]]`eventType` |String a|Event types displayed in
the timeline, which can be:

* `all`: all events
* `raw`: raw events only
* `signal`: signals only

|`favorite` |<<favorite-obj, favorite[]>> |Indicates when and who marked a
timeline as a favorite.
|[[timeline-object-filters]]`filters` |<<filters-obj, filters[]>> |Filters used
in addition to the dropzone query.
|[[timeline-object-global-notes]]`globalNotes`
|<<globalNotes-obj, globalNotes[]>> |Global notes added to the timeline.
|[[timeline-object-kqlmode]]`kqlMode` |String a|Indicates whether the KQL bar
filters the dropzone query results or searches for additional results, where:

* `filter`: filters dropzone query results
* `search`: displays additional search results

|[[timeline-object-kqlquery]]`kqlQuery` |<<kqlQuery-obj, kqlQuery>> |KQL bar
query.
|`pinnedEventIds` |pinnedEventIds[] |IDs of events pinned to the timeline's
search results.
|`savedObjectId` |String |The timeline's saved object ID.
|`savedQueryId` |String |If used, the saved query ID used to filter or search
dropzone query results.
|`sort` |sort a|Object indicating how rows are sorted in the timeline's grid:

* `columnId` (string): The ID of the column used to sort results.
* `sortDirection` (string): The sort direction, which can be either `desc` or
`asc`.

|`templateTimelineId` |String a| A unique ID (UUID) for Timeline templates. For
timelines, the value is `null`.
|`templateTimelineVersion` |Integer |Timeline template version number. For
timelines, the value is `null`.
// When creating timeline template via import, can just specify it to 1.
// We use this version to avoid template timeline to be overwrite when updating
// via import.
// We take every positive int given from user as long as it is grater than
// current value.
|[[timeline-object-typeField]]`timelineType` |String a|Indicates whether the
timeline is a template or not, where:

* `default`: Indicates a timeline used to actively investigate events.
* `template`: Indicates a timeline template used when detection rule alerts are
investigated in Timeline.

|[[timeline-object-title]]`title` |String |The timeline's title.
|`updated` |Float |The last time the timeline was updated, using a
13-digit Epoch timestamp.
|`updatedBy` |String |The user who last updated the timeline.
|`version` |String |The timeline's version.
|==============================================

[[col-obj]]
[discrete]
==== columns object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`aggregatable` |Boolean |Indicates whether the field can be aggregated across
all indices (used to sort columns in the UI).
|`category` |String |The ECS field set to which the field belongs.
|`description` |String |UI column field description tooltip.
|`example` |String |UI column field example tooltip.
|`indexes` |String |Security indices in which the field exists and has the same
{es} type. `null` when all the security indices have the field with the same
type.
|`id` |String |ECS field name, displayed as the column header in the UI.
// |`searchable` |Boolean |Indicates whether the field is indexed for search on
// all indices.
|`type` |String |The field's type.
|==============================================

[[dataProvider-obj]]
[discrete]
==== dataProviders object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`and` |dataProviders[] |Array containing dropzone query clauses using `AND`
logic.
|`enabled` |Boolean |Indicates if the dropzone query clause is enabled.
|`excluded` |Boolean |Indicates if the dropzone query clause uses `NOT` logic.
|`id` |String |The dropzone query clause's unique ID.
|`name` |String |The dropzone query clause's name (the clause's value
when timelines are exported from the UI).
|`queryMatch` |queryMatch a|The dropzone query clause:

* `field` (string): The field used to search SIEM indices.
* `operator` (string): The clause's operator, which can be:
** `:` - The `field` has the specified `value`.
** `:*` - The field exists.

* `value` (string): The field's value used to match results.

|==============================================

[[eventNotes-obj]]
[discrete]
==== eventNotes object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`created` |Float |The time the note was created, using a 13-digit Epoch
timestamp.
|`createdBy` |String |The user who added the note.
|`eventId` |String |The ID of the event to which the note was added.
|`note` |String |The note's text.
|`noteId` |String |The note's ID
|`timelineId` |String |The ID of the timeline to which the note was added.
|`updated` |Float |The last time the note was updated, using a
13-digit Epoch timestamp.
|`updatedBy` |String |The user who last updated the note.
|`version` |String |The note's version.
|==============================================

[[favorite-obj]]
[discrete]
==== favorite object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`favoriteDate` |Float |The time the timeline was marked as a favorite, using a
13-digit Epoch timestamp.
|`fullName` |String |The full name of the user who marked the timeline as
a favorite.
|`keySearch` |String |`userName` encoded in Base64.
|`userName` |String |The {kib} username of the user who marked the
timeline as a favorite.
|==============================================

[[filters-obj]]
[discrete]
==== filters object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`exists` |String |{ref}/query-dsl-exists-query.html[Exists term query] for the
specified field (`null` when undefined). For example, `{"field":"user.name"}`.
|`meta` |meta a|Filter details:

* `alias` (string): UI filter name.
* `disabled` (boolean): Indicates if the filter is disabled.
* `key`(string): Field name or unique string ID.
* `negate` (boolean): Indicates if the filter query clause uses `NOT` logic.
* `params` (string): Value of `phrase` filter types.
* `type` (string): Type of filter. For example, `exists` and `range`. For more
information about filtering, see {ref}/query-dsl.html[Query DSL].

|`match_all` |String |{ref}/query-dsl-match-all-query.html[Match all term query]
for the specified field (`null` when undefined).
|`query` |String |{ref}/query-dsl.html[DSL query] (`null` when undefined). For
example, `{"match_phrase":{"ecs.version":"1.4.0"}}`.
|`range` |String |{ref}/query-dsl-range-query.html[Range query] (`null` when
undefined). For example, `{"@timestamp":{"gte":"now-1d","lt":"now"}}"`.
|==============================================

[[globalNotes-obj]]
[discrete]
==== globalNotes object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`created` |Float |The time the note was created, using a 13-digit Epoch
timestamp.
|`createdBy` |String |The user who added the note.
|`note` |String |The note's text.
|`noteId` |String |The note's ID
|`timelineId` |String |The ID of the timeline to which the note was added.
|`updated` |Float |The last time the note was updated, using a
13-digit Epoch timestamp.
|`updatedBy` |String |The user who last updated the note.
|`version` |String |The note's version.
|==============================================

[[kqlQuery-obj]]
[discrete]
==== kqlQuery object

[width="100%",options="header"]
|==============================================
|Name |Type |Description

|`filterQuery` |filterQuery a|Object containing query details:

* `kuery`: Object containing the query's clauses and type:
** `expression`(string): The query's clauses.
** `kind` (string): The type of query, which can be `kuery` or `lucene`.
* `serializedQuery` (string): The query represented in JSON format.
|==============================================
Loading