Skip to content

Commit 60c8652

Browse files
benskelkerbenskelker
authored
[Docs]Adds timeline schema and API (elastic#50)
* adds timeline schema * starts create timeline endpoint * create timeline cont * finishes api * corrections after review * UUID for template ID
1 parent 9d5eefc commit 60c8652

File tree

6 files changed

+726
-19
lines changed

6 files changed

+726
-19
lines changed

‎docs/siem/index.asciidoc‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,3 @@
1-
// :doctype: book
2-
// :siem-soln: Elastic Security
3-
// :siem-app: Elastic Security app
4-
// :siem-ui: Elastic Security UI
5-
// :ml-dir: {stack-docs-root}/docs/en/stack/ml
6-
// :sn: ServiceNow
7-
8-
// Removed for merging with unified security docs
9-
// = SIEM Guide
10-
111
include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
122

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

2515
include::cases/cases-index.asciidoc[]
26-
27-
// include::siem-apis.asciidoc[]
28-
29-
// include::reference/ref-index.asciidoc[]

‎docs/siem/reference/timeline-schema.asciidoc‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,255 @@
22
[role="xpack"]
33
== Timeline schema
44

5+
The Timeline schema lists all the JSON fields and objects required to create a
6+
Timeline or a Timeline template using the Create timeline API.
7+
8+
IMPORTANT: All column, dropzone, and filter fields must be
9+
{ecs-ref}[ECS fields].
10+
11+
This screenshot maps the Timeline UI components to their JSON objects:
12+
13+
[role="screenshot"]
14+
image::images/timeline-object-ui.png[]
15+
16+
. <<timeline-object-title, Title>> (`title`)
17+
. <<timeline-object-desc, Description>> (`description`)
18+
. <<timeline-object-global-notes, Global notes>> (`globalNotes`)
19+
. <<timeline-object-daterange, Time filter>> (`dateRange`)
20+
. <<timeline-object-dropzone, Dropzone>> (each clause is contained in
21+
its own `dataProviders` object)
22+
. <<timeline-object-kqlmode, KQL bar mode>> (`kqlMode`)
23+
. <<timeline-object-kqlquery, KQL bar query>> (`kqlQuery`)
24+
. <<timeline-object-eventtype, Event types included in Timeline results>>
25+
(`eventType`)
26+
. <<timeline-object-filters, Additional filters>> (`filters`)
27+
. <<timeline-object-columns, Column headers>> (`columns`)
28+
. <<timeline-object-event-notes, Event-specific notes>> (`eventNotes`)
29+
30+
[width="100%",options="header"]
31+
|==============================================
32+
|Name |Type |Description
33+
34+
|[[timeline-object-columns]]`columns` |<<col-obj, columns[]>> |The timeline's
35+
columns.
36+
|`created` |Float |The time the timeline was created, using a 13-digit Epoch
37+
timestamp.
38+
|`createdBy` |String |The user who created the timeline.
39+
|[[timeline-object-dropzone]]`dataProviders`
40+
|<<dataProvider-obj, dataProviders[]>> |Object containing dropzone query
41+
clauses.
42+
|[[timeline-object-daterange]]`dateRange` |dateRange a|The timeline's search
43+
period:
44+
45+
* `end`: The time up to which events are searched, using a 13-digit Epoch
46+
timestamp.
47+
* `start`: The time from which events are searched, using a 13-digit Epoch
48+
timestamp.
49+
50+
|[[timeline-object-desc]]`description` |String |The timeline's description.
51+
|[[timeline-object-event-notes]]`eventNotes` |<<eventNotes-obj, eventNotes[]>>
52+
|Notes added to specific events in the timeline.
53+
|[[timeline-object-eventtype]]`eventType` |String a|Event types displayed in
54+
the timeline, which can be:
55+
56+
* `all`: all events
57+
* `raw`: raw events only
58+
* `signal`: signals only
59+
60+
|`favorite` |<<favorite-obj, favorite[]>> |Indicates when and who marked a
61+
timeline as a favorite.
62+
|[[timeline-object-filters]]`filters` |<<filters-obj, filters[]>> |Filters used
63+
in addition to the dropzone query.
64+
|[[timeline-object-global-notes]]`globalNotes`
65+
|<<globalNotes-obj, globalNotes[]>> |Global notes added to the timeline.
66+
|[[timeline-object-kqlmode]]`kqlMode` |String a|Indicates whether the KQL bar
67+
filters the dropzone query results or searches for additional results, where:
68+
69+
* `filter`: filters dropzone query results
70+
* `search`: displays additional search results
71+
72+
|[[timeline-object-kqlquery]]`kqlQuery` |<<kqlQuery-obj, kqlQuery>> |KQL bar
73+
query.
74+
|`pinnedEventIds` |pinnedEventIds[] |IDs of events pinned to the timeline's
75+
search results.
76+
|`savedObjectId` |String |The timeline's saved object ID.
77+
|`savedQueryId` |String |If used, the saved query ID used to filter or search
78+
dropzone query results.
79+
|`sort` |sort a|Object indicating how rows are sorted in the timeline's grid:
80+
81+
* `columnId` (string): The ID of the column used to sort results.
82+
* `sortDirection` (string): The sort direction, which can be either `desc` or
83+
`asc`.
84+
85+
|`templateTimelineId` |String a| A unique ID (UUID) for Timeline templates. For
86+
timelines, the value is `null`.
87+
|`templateTimelineVersion` |Integer |Timeline template version number. For
88+
timelines, the value is `null`.
89+
// When creating timeline template via import, can just specify it to 1.
90+
// We use this version to avoid template timeline to be overwrite when updating
91+
// via import.
92+
// We take every positive int given from user as long as it is grater than
93+
// current value.
94+
|[[timeline-object-typeField]]`timelineType` |String a|Indicates whether the
95+
timeline is a template or not, where:
96+
97+
* `default`: Indicates a timeline used to actively investigate events.
98+
* `template`: Indicates a timeline template used when detection rule alerts are
99+
investigated in Timeline.
100+
101+
|[[timeline-object-title]]`title` |String |The timeline's title.
102+
|`updated` |Float |The last time the timeline was updated, using a
103+
13-digit Epoch timestamp.
104+
|`updatedBy` |String |The user who last updated the timeline.
105+
|`version` |String |The timeline's version.
106+
|==============================================
107+
108+
[[col-obj]]
109+
[discrete]
110+
==== columns object
111+
112+
[width="100%",options="header"]
113+
|==============================================
114+
|Name |Type |Description
115+
116+
|`aggregatable` |Boolean |Indicates whether the field can be aggregated across
117+
all indices (used to sort columns in the UI).
118+
|`category` |String |The ECS field set to which the field belongs.
119+
|`description` |String |UI column field description tooltip.
120+
|`example` |String |UI column field example tooltip.
121+
|`indexes` |String |Security indices in which the field exists and has the same
122+
{es} type. `null` when all the security indices have the field with the same
123+
type.
124+
|`id` |String |ECS field name, displayed as the column header in the UI.
125+
// |`searchable` |Boolean |Indicates whether the field is indexed for search on
126+
// all indices.
127+
|`type` |String |The field's type.
128+
|==============================================
129+
130+
[[dataProvider-obj]]
131+
[discrete]
132+
==== dataProviders object
133+
134+
[width="100%",options="header"]
135+
|==============================================
136+
|Name |Type |Description
137+
138+
|`and` |dataProviders[] |Array containing dropzone query clauses using `AND`
139+
logic.
140+
|`enabled` |Boolean |Indicates if the dropzone query clause is enabled.
141+
|`excluded` |Boolean |Indicates if the dropzone query clause uses `NOT` logic.
142+
|`id` |String |The dropzone query clause's unique ID.
143+
|`name` |String |The dropzone query clause's name (the clause's value
144+
when timelines are exported from the UI).
145+
|`queryMatch` |queryMatch a|The dropzone query clause:
146+
147+
* `field` (string): The field used to search SIEM indices.
148+
* `operator` (string): The clause's operator, which can be:
149+
** `:` - The `field` has the specified `value`.
150+
** `:*` - The field exists.
151+
152+
* `value` (string): The field's value used to match results.
153+
154+
|==============================================
155+
156+
[[eventNotes-obj]]
157+
[discrete]
158+
==== eventNotes object
159+
160+
[width="100%",options="header"]
161+
|==============================================
162+
|Name |Type |Description
163+
164+
|`created` |Float |The time the note was created, using a 13-digit Epoch
165+
timestamp.
166+
|`createdBy` |String |The user who added the note.
167+
|`eventId` |String |The ID of the event to which the note was added.
168+
|`note` |String |The note's text.
169+
|`noteId` |String |The note's ID
170+
|`timelineId` |String |The ID of the timeline to which the note was added.
171+
|`updated` |Float |The last time the note was updated, using a
172+
13-digit Epoch timestamp.
173+
|`updatedBy` |String |The user who last updated the note.
174+
|`version` |String |The note's version.
175+
|==============================================
176+
177+
[[favorite-obj]]
178+
[discrete]
179+
==== favorite object
180+
181+
[width="100%",options="header"]
182+
|==============================================
183+
|Name |Type |Description
184+
185+
|`favoriteDate` |Float |The time the timeline was marked as a favorite, using a
186+
13-digit Epoch timestamp.
187+
|`fullName` |String |The full name of the user who marked the timeline as
188+
a favorite.
189+
|`keySearch` |String |`userName` encoded in Base64.
190+
|`userName` |String |The {kib} username of the user who marked the
191+
timeline as a favorite.
192+
|==============================================
193+
194+
[[filters-obj]]
195+
[discrete]
196+
==== filters object
197+
198+
[width="100%",options="header"]
199+
|==============================================
200+
|Name |Type |Description
201+
202+
|`exists` |String |{ref}/query-dsl-exists-query.html[Exists term query] for the
203+
specified field (`null` when undefined). For example, `{"field":"user.name"}`.
204+
|`meta` |meta a|Filter details:
205+
206+
* `alias` (string): UI filter name.
207+
* `disabled` (boolean): Indicates if the filter is disabled.
208+
* `key`(string): Field name or unique string ID.
209+
* `negate` (boolean): Indicates if the filter query clause uses `NOT` logic.
210+
* `params` (string): Value of `phrase` filter types.
211+
* `type` (string): Type of filter. For example, `exists` and `range`. For more
212+
information about filtering, see {ref}/query-dsl.html[Query DSL].
213+
214+
|`match_all` |String |{ref}/query-dsl-match-all-query.html[Match all term query]
215+
for the specified field (`null` when undefined).
216+
|`query` |String |{ref}/query-dsl.html[DSL query] (`null` when undefined). For
217+
example, `{"match_phrase":{"ecs.version":"1.4.0"}}`.
218+
|`range` |String |{ref}/query-dsl-range-query.html[Range query] (`null` when
219+
undefined). For example, `{"@timestamp":{"gte":"now-1d","lt":"now"}}"`.
220+
|==============================================
221+
222+
[[globalNotes-obj]]
223+
[discrete]
224+
==== globalNotes object
225+
226+
[width="100%",options="header"]
227+
|==============================================
228+
|Name |Type |Description
229+
230+
|`created` |Float |The time the note was created, using a 13-digit Epoch
231+
timestamp.
232+
|`createdBy` |String |The user who added the note.
233+
|`note` |String |The note's text.
234+
|`noteId` |String |The note's ID
235+
|`timelineId` |String |The ID of the timeline to which the note was added.
236+
|`updated` |Float |The last time the note was updated, using a
237+
13-digit Epoch timestamp.
238+
|`updatedBy` |String |The user who last updated the note.
239+
|`version` |String |The note's version.
240+
|==============================================
241+
242+
[[kqlQuery-obj]]
243+
[discrete]
244+
==== kqlQuery object
245+
246+
[width="100%",options="header"]
247+
|==============================================
248+
|Name |Type |Description
249+
250+
|`filterQuery` |filterQuery a|Object containing query details:
251+
252+
* `kuery`: Object containing the query's clauses and type:
253+
** `expression`(string): The query's clauses.
254+
** `kind` (string): The type of query, which can be `kuery` or `lucene`.
255+
* `serializedQuery` (string): The query represented in JSON format.
256+
|==============================================

0 commit comments

Comments
 (0)