From 5aba25ab227897a0cf054d0dbbb757f6e958a0d2 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Sun, 5 Jul 2020 10:50:48 +0300 Subject: [PATCH 1/6] adds timeline schema --- docs/siem/reference/timeline-schema.asciidoc | 252 +++++++++++++++++++ 1 file changed, 252 insertions(+) diff --git a/docs/siem/reference/timeline-schema.asciidoc b/docs/siem/reference/timeline-schema.asciidoc index de2dd3443a..2053e07ec6 100644 --- a/docs/siem/reference/timeline-schema.asciidoc +++ b/docs/siem/reference/timeline-schema.asciidoc @@ -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[] + +. <> (`title`) +. <> (`description`) +. <> (`globalNotes`) +. <> (`dateRange`) +. <> (each clause is contained in +its own `dataProviders` object) +. <> (`kqlMode`) +. <> (`kqlQuery`) +. <> +(`eventType`) +. <> (`filters`) +. <> (`columns`) +. <> (`eventNotes`) + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|[[timeline-object-columns]]`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` +|<> |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` |<> +|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` |<> |Indicates when and who marked a +timeline as a favorite. +|[[timeline-object-filters]]`filters` |<> |Filters used +in addition to the dropzone query. +|[[timeline-object-global-notes]]`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` |<> |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 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. +|`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. +|============================================== From b0997e7f31d3d5722423eea33f59c6154f9e01a6 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Sun, 5 Jul 2020 15:13:11 +0300 Subject: [PATCH 2/6] starts create timeline endpoint --- docs/siem/index.asciidoc | 14 ----- docs/siem/reference/timeline-schema.asciidoc | 4 +- .../timeline/api/timeline-api-create.asciidoc | 59 +++++++++++++++++++ .../timeline/api/timeline-api-index.asciidoc | 2 + .../api/timeline-api-overview.asciidoc | 2 +- 5 files changed, 64 insertions(+), 17 deletions(-) create mode 100644 docs/siem/timeline/api/timeline-api-create.asciidoc diff --git a/docs/siem/index.asciidoc b/docs/siem/index.asciidoc index 0a1c2ad786..2fadfd324d 100644 --- a/docs/siem/index.asciidoc +++ b/docs/siem/index.asciidoc @@ -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[] @@ -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[] diff --git a/docs/siem/reference/timeline-schema.asciidoc b/docs/siem/reference/timeline-schema.asciidoc index 2053e07ec6..c7bb0532d3 100644 --- a/docs/siem/reference/timeline-schema.asciidoc +++ b/docs/siem/reference/timeline-schema.asciidoc @@ -91,8 +91,8 @@ timelines, the value is `null`. // via import. // We take every positive int given from user as long as it is grater than // current value. -|`timelineType` |String a|Indicates whether the timeline is a template or not, -where: +|[[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 diff --git a/docs/siem/timeline/api/timeline-api-create.asciidoc b/docs/siem/timeline/api/timeline-api-create.asciidoc new file mode 100644 index 0000000000..0734547695 --- /dev/null +++ b/docs/siem/timeline/api/timeline-api-create.asciidoc @@ -0,0 +1,59 @@ +[[timeline-api-create]] +=== Create timeline or timeline template + +Creates a new timeline or timeline template. + +Use the `timeline` object's <> field +to determine whether a timeline or a timeline template is created, where: + +* `default` creates a new timeline (`"timelineType": "default"`) +* `template` creates a new timeline template (`"timelineType": "template"`) + +NOTE: If you do not specify the `timelineType` field, a new timeline is created. + +==== Request URL + +`POST :/api/timeline` + +==== Request body + +A JSON object defining the timeline or timeline template query and time filter. + +NOTE: For detailed information about the Timeline object schema and its +corresponding UI components, see <>. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`timeline` |<> |The timeline object, which +defines the search criteria and time range. The only required field is `title`. +|Yes +|`timelineId` |String |If provided, must be `null` for a new timeline or +template. +|No +|`version` |String |If provided, must be `null` for a new timeline or template. +|No +|============================================== + + + + +===== Example request + + + +[source,console] +-------------------------------------------------- + +-------------------------------------------------- +// KIBANA + + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + diff --git a/docs/siem/timeline/api/timeline-api-index.asciidoc b/docs/siem/timeline/api/timeline-api-index.asciidoc index a311366760..a141c35c5f 100644 --- a/docs/siem/timeline/api/timeline-api-index.asciidoc +++ b/docs/siem/timeline/api/timeline-api-index.asciidoc @@ -1,5 +1,7 @@ include::timeline-api-overview.asciidoc[] +include::timeline-api-create.asciidoc[] + include::timeline-api-export.asciidoc[] include::timeline-api-import.asciidoc[] diff --git a/docs/siem/timeline/api/timeline-api-overview.asciidoc b/docs/siem/timeline/api/timeline-api-overview.asciidoc index 9fc366e12a..1d1dbf8808 100644 --- a/docs/siem/timeline/api/timeline-api-overview.asciidoc +++ b/docs/siem/timeline/api/timeline-api-overview.asciidoc @@ -5,4 +5,4 @@ beta[] You can create timelines and timeline templates via the API, as well export -existing timelines and import new timelines from an ndjson file. \ No newline at end of file +existing timelines and import new timelines from an `ndjson` file. \ No newline at end of file From e0c70c2932e55d46148be181988357572634ef8c Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 6 Jul 2020 11:48:34 +0300 Subject: [PATCH 3/6] create timeline cont --- .../timeline/api/timeline-api-create.asciidoc | 305 +++++++++++++++++- 1 file changed, 303 insertions(+), 2 deletions(-) diff --git a/docs/siem/timeline/api/timeline-api-create.asciidoc b/docs/siem/timeline/api/timeline-api-create.asciidoc index 0734547695..0beb0a6ed1 100644 --- a/docs/siem/timeline/api/timeline-api-create.asciidoc +++ b/docs/siem/timeline/api/timeline-api-create.asciidoc @@ -36,19 +36,240 @@ template. |No |============================================== +===== Example requests +*Example 1* +Creates a new timeline: -===== Example request +[source,console] +-------------------------------------------------- +POST api/timeline +{ + "timeline": { + "columns": [ + { + "id": "@timestamp" + }, + { + "id": "user.name" + }, + { + "id": "event.category" + }, + { + "id": "event.action" + }, + { + "id": "host.name" + } + ], + "dataProviders": [ <1> + { + "and": [ + { + "name": "event.category", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "event.category", + "value": "process", + "operator": ":" + } + }, + { + "name": "user.name", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "user.name", + "value": "SYSTEM", + "operator": ":" + } + } + ], + "enabled": true, + "excluded": false, + "name": "host.os.platform", + "queryMatch": { + "field": "host.os.platform", + "value": "windows", + "operator": ":" + } + } + ], + "dateRange": { + "end": 1594005719000, + "start": 1593832919000 + }, + "description": "Gets Windows system processes from all hosts", + "title": "Windows system processes" + } +} +-------------------------------------------------- +// KIBANA + +<1> To ensure the timeline is displayed correctly in the UI, specify these +fields in all `dataProviders` objects: +* `and` (can be empty) +* `name` +* `enabled` +* `excluded` +* `queryMatch` +** `field` +** `value` +** `operator` +*Example 2* + +Creates a new timeline template: [source,console] -------------------------------------------------- - +POST api/timeline +{ + "timeline": { + "columns": [ + { + "id": "@timestamp" + }, + { + "id": "user.name" + }, + { + "id": "event.category" + }, + { + "id": "event.action" + }, + { + "id": "host.name" + } + ], + "dataProviders": [ + { + "and": [ + { + "name": "event.category", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "event.category", + "operator": ":", + "value": "process" <1> + } + }, + { + "name": "user.name", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "user.name", + "operator": ":", + "value": "SYSTEM" + } + } + ], + "enabled": true, + "excluded": false, + "name": "host.os.platform", + "queryMatch": { + "field": "host.os.platform", + "operator": ":", + "value": "windows" + } + } + ], + "dateRange": { + "end": 1594005719000, + "start": 1593832919000 + }, + "description": "Template for investigating host events", + "timelineType": "template", <2> + "title": "Host event template" + } +} -------------------------------------------------- // KIBANA +<1> To ensure the timeline template is displayed correctly in the UI, specify +the `value` field even though it is replaced when alerts are investigated in +Timeline. +<2> To create templates, the `timelineType` field value must be `template`. + +*Example 3* + +Creates the a timeline template that uses the `kqlQuery` object (KQL bar in the +UI) to ensure only Windows alerts are displayed when alerts are investigated in +Timeline: + +[source,console] +-------------------------------------------------- +POST api/timeline +{ + "timeline": { + "columns": [ + { + "id": "@timestamp" + }, + { + "id": "user.name" + }, + { + "id": "event.category" + }, + { + "id": "event.action" + }, + { + "id": "host.name" + } + ], + "dataProviders": [ + { + "and": [ + { + "enabled": true, + "excluded": false, + "name": "user.name", + "queryMatch": { + "field": "user.name", + "operator": ":", + "value": "SYSTEM" + } + } + ], + "enabled": true, + "excluded": false, + "name": "event.category", + "queryMatch": { + "field": "event.category", + "operator": ":", + "value": "process" + } + } + ], + "dateRange": { + "end": 1594005719000, + "start": 1593832919000 + }, + "description": "Template for investigating Windows events", + "kqlMode": "filter", + "kqlQuery": { + "filterQuery": { + "kuery": { + "expression": "host.os.platform : windows", + "kind": "kuery" + } + } + }, + "timelineType": "template", + "title": "Windows event template" + } +} +-------------------------------------------------- +// KIBANA ==== Response code @@ -57,3 +278,83 @@ template. ==== Response payload +A JSON timeline object with a unique `savedObjectId` and its `version`: + +[source,json] +-------------------------------------------------- +{ + "data": { + "persistTimeline": { + "code": 200, + "message": "success", + "timeline": { + "savedObjectId": "7f069820-bf57-11ea-9fcd-ed4e5fd0dcd1", + "version": "WzQwMiwxXQ==", + "columns": [ + { + "id": "@timestamp" + }, + { + "id": "user.name" + }, + { + "id": "event.category" + }, + { + "id": "event.action" + }, + { + "id": "host.name" + } + ], + "dataProviders": [ + { + "and": [ + { + "name": "event.category", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "event.category", + "value": "process", + "operator": ":" + } + }, + { + "name": "user.name", + "enabled": true, + "excluded": false, + "queryMatch": { + "field": "user.name", + "value": "SYSTEM", + "operator": ":" + } + } + ], + "enabled": true, + "excluded": false, + "name": "host.os.platform", + "queryMatch": { + "field": "host.os.platform", + "value": "windows", + "operator": ":" + } + } + ], + "dateRange": { + "end": 1594005719000, + "start": 1593832919000 + }, + "description": "Gets Windows system processes from all hosts", + "title": "Windows system processes", + "created": 1594019310069, + "createdBy": "LiverpoolFC", + "updated": 1594019310069, + "updatedBy": "LiverpoolFC", + "timelineType": "default", + "status": "active" + } + } + } +} +-------------------------------------------------- From ccce4819cceeefdb4345eb1c021af5ca902af297 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 6 Jul 2020 14:03:45 +0300 Subject: [PATCH 4/6] finishes api --- docs/siem/timeline/api/timeline-api-index.asciidoc | 2 +- docs/siem/timeline/api/timeline-api-overview.asciidoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/siem/timeline/api/timeline-api-index.asciidoc b/docs/siem/timeline/api/timeline-api-index.asciidoc index a141c35c5f..e41570b08d 100644 --- a/docs/siem/timeline/api/timeline-api-index.asciidoc +++ b/docs/siem/timeline/api/timeline-api-index.asciidoc @@ -2,6 +2,6 @@ include::timeline-api-overview.asciidoc[] include::timeline-api-create.asciidoc[] -include::timeline-api-export.asciidoc[] +// include::timeline-api-export.asciidoc[] include::timeline-api-import.asciidoc[] diff --git a/docs/siem/timeline/api/timeline-api-overview.asciidoc b/docs/siem/timeline/api/timeline-api-overview.asciidoc index 1d1dbf8808..306ab8f508 100644 --- a/docs/siem/timeline/api/timeline-api-overview.asciidoc +++ b/docs/siem/timeline/api/timeline-api-overview.asciidoc @@ -4,5 +4,5 @@ beta[] -You can create timelines and timeline templates via the API, as well export -existing timelines and import new timelines from an `ndjson` file. \ No newline at end of file +You can create timelines and timeline templates via the API, as well import new +timelines from an `ndjson` file. \ No newline at end of file From 0922a7df822ad1a1a889f215485ae4b329f4d1ea Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 6 Jul 2020 15:30:26 +0300 Subject: [PATCH 5/6] corrections after review --- .../timeline/api/timeline-api-create.asciidoc | 110 +++++++++++++++++- .../timeline/api/timeline-api-import.asciidoc | 7 +- 2 files changed, 112 insertions(+), 5 deletions(-) diff --git a/docs/siem/timeline/api/timeline-api-create.asciidoc b/docs/siem/timeline/api/timeline-api-create.asciidoc index 0beb0a6ed1..03fa5ad6b8 100644 --- a/docs/siem/timeline/api/timeline-api-create.asciidoc +++ b/docs/siem/timeline/api/timeline-api-create.asciidoc @@ -26,8 +26,16 @@ corresponding UI components, see <>. |============================================== |Name |Type |Description |Required -|`timeline` |<> |The timeline object, which +|`timeline` |<> a|The timeline object, which defines the search criteria and time range. The only required field is `title`. + +When you are creating a timeline template, provide these fields to so you can +easily <> updates: + +* `templateTimelineId`: Unique identifier (for timeline templates only) +* `templateTimelineVersion`: Template version number (for timeline templates +only) + |Yes |`timelineId` |String |If provided, must be `null` for a new timeline or template. @@ -186,7 +194,9 @@ POST api/timeline "start": 1593832919000 }, "description": "Template for investigating host events", - "timelineType": "template", <2> + "templateTimelineId": "HostSysProcess", <2> + "templateTimelineVersion": 1, <3> + "timelineType": "template", <4> "title": "Host event template" } } @@ -196,7 +206,9 @@ POST api/timeline <1> To ensure the timeline template is displayed correctly in the UI, specify the `value` field even though it is replaced when alerts are investigated in Timeline. -<2> To create templates, the `timelineType` field value must be `template`. +<2> Unique template ID. +<3> Template version number. +<4> To create templates, the `timelineType` field value must be `template`. *Example 3* @@ -264,6 +276,8 @@ POST api/timeline } } }, + "templateTimelineId": "WinSysProcess", + "templateTimelineVersion": 1, "timelineType": "template", "title": "Windows event template" } @@ -278,7 +292,11 @@ POST api/timeline ==== Response payload -A JSON timeline object with a unique `savedObjectId` and its `version`: +A JSON timeline object with a unique `savedObjectId` and its `version`. + +*Example 1* + +Timeline response payload: [source,json] -------------------------------------------------- @@ -358,3 +376,87 @@ A JSON timeline object with a unique `savedObjectId` and its `version`: } } -------------------------------------------------- + +*Example 2* + +Timeline template response payload: + +[source,json] +-------------------------------------------------- +{ + "data": { + "persistTimeline": { + "code": 200, + "message": "success", + "timeline": { + "savedObjectId": "75b6cf30-bf82-11ea-9fcd-ed4e5fd0dcd1", + "version": "WzQ4MiwxXQ==", + "columns": [ + { + "id": "@timestamp" + }, + { + "id": "user.name" + }, + { + "id": "event.category" + }, + { + "id": "event.action" + }, + { + "id": "host.name" + } + ], + "dataProviders": [ + { + "and": [ + { + "enabled": true, + "excluded": false, + "name": "user.name", + "queryMatch": { + "field": "user.name", + "operator": ":", + "value": "SYSTEM" + } + } + ], + "enabled": true, + "excluded": false, + "name": "event.category", + "queryMatch": { + "field": "event.category", + "operator": ":", + "value": "process" + } + } + ], + "dateRange": { + "end": 1594005719000, + "start": 1593832919000 + }, + "description": "Template for investigating Windows events", + "kqlMode": "filter", + "kqlQuery": { + "filterQuery": { + "kuery": { + "expression": "host.os.platform : windows", + "kind": "kuery" + } + } + }, + "templateTimelineId": "WinSysProcess", + "templateTimelineVersion": 1, + "timelineType": "template", + "title": "Windows event template", + "created": 1594037762797, + "createdBy": "LiverpoolFC", + "updated": 1594037762797, + "updatedBy": "LiverpoolFC", + "status": "active" + } + } + } +} +-------------------------------------------------- diff --git a/docs/siem/timeline/api/timeline-api-import.asciidoc b/docs/siem/timeline/api/timeline-api-import.asciidoc index c7b8618d16..cca6e45828 100644 --- a/docs/siem/timeline/api/timeline-api-import.asciidoc +++ b/docs/siem/timeline/api/timeline-api-import.asciidoc @@ -1,7 +1,12 @@ [[timeline-api-import]] === Import timelines -Imports timelines from an ndjson file. +Imports timelines and timeline templates from an `ndjson` file. + +If you are updating an existing timeline template, make sure: + +* You specify the relevant template's unique ID (`templateTimelineId`). +* You increment the timeline's version number (`templateTimelineVersion`). ==== Request URL From 7b2060a9cc8199e3a408f7b5033444b52a335182 Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Mon, 6 Jul 2020 15:47:08 +0300 Subject: [PATCH 6/6] UUID for template ID --- docs/siem/reference/timeline-schema.asciidoc | 2 +- docs/siem/timeline/api/timeline-api-create.asciidoc | 10 +++++----- docs/siem/timeline/api/timeline-api-import.asciidoc | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/siem/reference/timeline-schema.asciidoc b/docs/siem/reference/timeline-schema.asciidoc index c7bb0532d3..5cfc1a7d6b 100644 --- a/docs/siem/reference/timeline-schema.asciidoc +++ b/docs/siem/reference/timeline-schema.asciidoc @@ -82,7 +82,7 @@ dropzone query results. * `sortDirection` (string): The sort direction, which can be either `desc` or `asc`. -|`templateTimelineId` |String a| A unique ID for Timeline templates. For +|`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`. diff --git a/docs/siem/timeline/api/timeline-api-create.asciidoc b/docs/siem/timeline/api/timeline-api-create.asciidoc index 03fa5ad6b8..716e713a9c 100644 --- a/docs/siem/timeline/api/timeline-api-create.asciidoc +++ b/docs/siem/timeline/api/timeline-api-create.asciidoc @@ -32,7 +32,7 @@ defines the search criteria and time range. The only required field is `title`. When you are creating a timeline template, provide these fields to so you can easily <> updates: -* `templateTimelineId`: Unique identifier (for timeline templates only) +* `templateTimelineId`: Unique identifier (UUID, for timeline templates only) * `templateTimelineVersion`: Template version number (for timeline templates only) @@ -194,7 +194,7 @@ POST api/timeline "start": 1593832919000 }, "description": "Template for investigating host events", - "templateTimelineId": "HostSysProcess", <2> + "templateTimelineId": "6acb2c90-a01c-11ea-8e47-5dc21077d10c", <2> "templateTimelineVersion": 1, <3> "timelineType": "template", <4> "title": "Host event template" @@ -206,7 +206,7 @@ POST api/timeline <1> To ensure the timeline template is displayed correctly in the UI, specify the `value` field even though it is replaced when alerts are investigated in Timeline. -<2> Unique template ID. +<2> Template UUID. <3> Template version number. <4> To create templates, the `timelineType` field value must be `template`. @@ -276,7 +276,7 @@ POST api/timeline } } }, - "templateTimelineId": "WinSysProcess", + "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1", "templateTimelineVersion": 1, "timelineType": "template", "title": "Windows event template" @@ -446,7 +446,7 @@ Timeline template response payload: } } }, - "templateTimelineId": "WinSysProcess", + "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1", "templateTimelineVersion": 1, "timelineType": "template", "title": "Windows event template", diff --git a/docs/siem/timeline/api/timeline-api-import.asciidoc b/docs/siem/timeline/api/timeline-api-import.asciidoc index cca6e45828..df82844415 100644 --- a/docs/siem/timeline/api/timeline-api-import.asciidoc +++ b/docs/siem/timeline/api/timeline-api-import.asciidoc @@ -1,5 +1,5 @@ [[timeline-api-import]] -=== Import timelines +=== Import timelines and timeline templates Imports timelines and timeline templates from an `ndjson` file.