From 90fe910c04b8e0c68d65dee27de46a835ce92bdb Mon Sep 17 00:00:00 2001 From: Janeen Mikell-Straughn <57149392+jmikell821@users.noreply.github.com> Date: Thu, 20 May 2021 12:22:01 -0400 Subject: [PATCH] Update timeline docs (#678) (#691) Co-authored-by: jmikell821 Co-authored-by: Janeen Mikell-Straughn <57149392+jmikell821@users.noreply.github.com> Co-authored-by: Angela Chuang <6295984+angorayc@users.noreply.github.com> --- docs/events/api/timeline-api-create.asciidoc | 50 +++++--- docs/events/api/timeline-api-delete.asciidoc | 30 +++++ docs/events/api/timeline-api-export.asciidoc | 10 +- docs/events/api/timeline-api-get.asciidoc | 86 ++++++++++++++ docs/events/api/timeline-api-index.asciidoc | 6 + .../events/api/timeline-api-overview.asciidoc | 5 +- docs/events/api/timeline-api-update.asciidoc | 108 ++++++++++++++++++ 7 files changed, 270 insertions(+), 25 deletions(-) create mode 100644 docs/events/api/timeline-api-delete.asciidoc create mode 100644 docs/events/api/timeline-api-get.asciidoc create mode 100644 docs/events/api/timeline-api-update.asciidoc diff --git a/docs/events/api/timeline-api-create.asciidoc b/docs/events/api/timeline-api-create.asciidoc index 716e713a9c..d4df50547e 100644 --- a/docs/events/api/timeline-api-create.asciidoc +++ b/docs/events/api/timeline-api-create.asciidoc @@ -1,13 +1,13 @@ [[timeline-api-create]] -=== Create timeline or timeline template +=== Create Timeline or Timeline template -Creates a new 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"`) +* `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. @@ -17,7 +17,7 @@ NOTE: If you do not specify the `timelineType` field, a new timeline is created. ==== Request body -A JSON object defining the timeline or timeline template query and time filter. +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 <>. @@ -29,18 +29,18 @@ corresponding UI components, see <>. |`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 +When you are creating a Timeline template, provide these fields to so you can easily <> updates: -* `templateTimelineId`: Unique identifier (UUID, for timeline templates only) -* `templateTimelineVersion`: Template version number (for timeline templates +* `templateTimelineId`: Unique identifier (UUID, 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 +|`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. +|`version` |String |If provided, must be `null` for a new Timeline or template. |No |============================================== @@ -48,7 +48,7 @@ template. *Example 1* -Creates a new timeline: +Creates a new Timeline. [source,console] -------------------------------------------------- @@ -79,6 +79,7 @@ POST api/timeline "name": "event.category", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d11", "queryMatch": { "field": "event.category", "value": "process", @@ -89,6 +90,7 @@ POST api/timeline "name": "user.name", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d12", "queryMatch": { "field": "user.name", "value": "SYSTEM", @@ -98,6 +100,7 @@ POST api/timeline ], "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d13", "name": "host.os.platform", "queryMatch": { "field": "host.os.platform", @@ -117,13 +120,14 @@ POST api/timeline -------------------------------------------------- // KIBANA -<1> To ensure the timeline is displayed correctly in the UI, specify these +<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` +* `id` * `queryMatch` ** `field` ** `value` @@ -131,7 +135,7 @@ fields in all `dataProviders` objects: *Example 2* -Creates a new timeline template: +Creates a new Timeline template: [source,console] -------------------------------------------------- @@ -162,6 +166,7 @@ POST api/timeline "name": "event.category", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d21", "queryMatch": { "field": "event.category", "operator": ":", @@ -172,6 +177,7 @@ POST api/timeline "name": "user.name", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d22", "queryMatch": { "field": "user.name", "operator": ":", @@ -181,6 +187,7 @@ POST api/timeline ], "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d23", "name": "host.os.platform", "queryMatch": { "field": "host.os.platform", @@ -203,7 +210,7 @@ POST api/timeline -------------------------------------------------- // KIBANA -<1> To ensure the timeline template is displayed correctly in the UI, specify +<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> Template UUID. @@ -212,7 +219,7 @@ Timeline. *Example 3* -Creates the a timeline template that uses the `kqlQuery` object (KQL bar in the +Creates the 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: @@ -244,6 +251,7 @@ POST api/timeline { "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d31", "name": "user.name", "queryMatch": { "field": "user.name", @@ -254,6 +262,7 @@ POST api/timeline ], "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d32", "name": "event.category", "queryMatch": { "field": "event.category", @@ -287,12 +296,12 @@ POST api/timeline ==== Response code -`200`:: +`200`:: Indicates a successful call. - + ==== 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* @@ -332,6 +341,7 @@ Timeline response payload: "name": "event.category", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d41", "queryMatch": { "field": "event.category", "value": "process", @@ -342,6 +352,7 @@ Timeline response payload: "name": "user.name", "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d42", "queryMatch": { "field": "user.name", "value": "SYSTEM", @@ -351,6 +362,7 @@ Timeline response payload: ], "enabled": true, "excluded": false, + "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d43", "name": "host.os.platform", "queryMatch": { "field": "host.os.platform", @@ -414,6 +426,7 @@ Timeline template response payload: { "enabled": true, "excluded": false, + "id": "timeline-1-43112bd4-3081-491c-b973-605cce4c5f14", "name": "user.name", "queryMatch": { "field": "user.name", @@ -424,6 +437,7 @@ Timeline template response payload: ], "enabled": true, "excluded": false, + "id": "timeline-1-43112bd4-3081-491c-b973-605cce4c5f15", "name": "event.category", "queryMatch": { "field": "event.category", diff --git a/docs/events/api/timeline-api-delete.asciidoc b/docs/events/api/timeline-api-delete.asciidoc new file mode 100644 index 0000000000..66530a76d1 --- /dev/null +++ b/docs/events/api/timeline-api-delete.asciidoc @@ -0,0 +1,30 @@ +[[timeline-api-delete]] +=== Delete Timelines or Timeline templates + +Delete multiple Timelines or Timeline templates. + +==== Request URL + +`DELETE :/api/timeline` + +==== Request body + +A JSON object defining the savedObjectIds of Timelines or Timeline templates to be deleted. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required +|`savedObjectIds` | Array | `savedObjectIds` of Timelines or Timeline templates +|Yes + +|============================================== + +===== Example requests + +[source,console] +-------------------------------------------------- +DELETE api/timeline +{ + "savedObjectIds": ["56efaaf0-b274-11eb-8078-5b983613cc0f"] +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/events/api/timeline-api-export.asciidoc b/docs/events/api/timeline-api-export.asciidoc index 6cc57a9c41..784bd8d16b 100644 --- a/docs/events/api/timeline-api-export.asciidoc +++ b/docs/events/api/timeline-api-export.asciidoc @@ -1,7 +1,7 @@ [[timeline-api-export]] -=== Export timelines +=== Export Timelines -Exports timelines to an ndjson file. +Exports Timelines to an ndjson file. ==== Request URL @@ -18,8 +18,8 @@ Exports timelines to an ndjson file. |`file_name` |String |File name for saving the exported rules. |Yes |============================================== -TIP: When using cURL to export timelines to a file, use the `-O` and `-J` -options to save the timelines to the file name specified in the URL. +TIP: When using cURL to export Timelines to a file, use the `-O` and `-J` +options to save the Timelines to the file name specified in the URL. ==== Request body @@ -35,7 +35,7 @@ A JSON `ids` array containing the `savedObjectId` fields of the rules you want t ===== Example request -Exports two timeline and saves them to the `timelines_export.ndjson` file: +Exports two Timelines and saves them to the `timelines_export.ndjson` file: [source,console] -------------------------------------------------- diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc new file mode 100644 index 0000000000..bc5903292c --- /dev/null +++ b/docs/events/api/timeline-api-get.asciidoc @@ -0,0 +1,86 @@ +[[timeline-api-get]] +=== Get Timelines or Timeline templates + +Get Timelines or Timeline templates. + +==== Request URL + +`GET :/api/timelines` + +==== Request params + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`only_user_favorite` |Boolean a|Returns only favorite Timelines / Timeline templates if set to `true`. Default to `false` +|No +|`page_index` |Number |Page number of the result +|No +|`page_size` |Number |Items per page in result +|No +|`search` |String |The key word of the Timelines / Timeline templates you are searching for +|No +|`sort_field` |String |The order you want the result to be arranged. Can be `title`, `description`, `updated`, `created` +|No +|`sort_order` |String |`asc` or `desc` +|No +|`status` |String |Can be `active` or `immutable`. `active` returns all the custom Timelines / Timeline templates, whereas `immutable` returns Elastic prebuilt templates +|No +|`timeline_type` |String |Use the `timeline` object's <> field +to determine whether a timeline or a Timeline template is created, where: + +`default` returns Timelines, `template` returns Timeline templates +|No + +|============================================== + +===== Example requests + +Get Timelines: + +[source,console] +-------------------------------------------------- +GET api/timelines?page_size=10&page_index=1&sort_field=updated&sort_order=desc&timeline_type=default + +-------------------------------------------------- + + +=== Get Timeline / Timeline template by savedObjectId + +Get single Timeline or Timeline template by savedObjectId. + +==== Request URL + +`GET :/api/timeline?id=` + +===== Example requests + +Get Timeline by savedObjectId: + +[source,console] +-------------------------------------------------- +GET /api/timeline?id= + +-------------------------------------------------- + + +=== Get Timeline template by templateTimelineId + +Get a single Timeline template by templateTimelineId. + +==== Request URL + +`GET :/api/timeline?template_timeline_id=` + +===== Example requests + +Get Timeline by templateTimelineId: + +[source,console] +-------------------------------------------------- +GET /api/timeline?template_timeline_id= + +-------------------------------------------------- + + diff --git a/docs/events/api/timeline-api-index.asciidoc b/docs/events/api/timeline-api-index.asciidoc index e41570b08d..ecb6b148ac 100644 --- a/docs/events/api/timeline-api-index.asciidoc +++ b/docs/events/api/timeline-api-index.asciidoc @@ -1,7 +1,13 @@ include::timeline-api-overview.asciidoc[] +include::timeline-api-get.asciidoc[] + include::timeline-api-create.asciidoc[] +include::timeline-api-update.asciidoc[] + +include::timeline-api-delete.asciidoc[] + // include::timeline-api-export.asciidoc[] include::timeline-api-import.asciidoc[] diff --git a/docs/events/api/timeline-api-overview.asciidoc b/docs/events/api/timeline-api-overview.asciidoc index d8efa84a39..0845268496 100644 --- a/docs/events/api/timeline-api-overview.asciidoc +++ b/docs/events/api/timeline-api-overview.asciidoc @@ -2,5 +2,6 @@ [role="xpack"] == Timeline API -You can create timelines and timeline templates via the API, as well import new -timelines from an `ndjson` file. +You can create Timelines and Timeline templates via the API, as well as import new Timelines from an `ndjson` file. + +NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console]. \ No newline at end of file diff --git a/docs/events/api/timeline-api-update.asciidoc b/docs/events/api/timeline-api-update.asciidoc new file mode 100644 index 0000000000..3e15383eb4 --- /dev/null +++ b/docs/events/api/timeline-api-update.asciidoc @@ -0,0 +1,108 @@ +[[timeline-api-update]] +=== Add a note to an existing Timeline + +Add a note to an existing Timeline or Timeline event. + +==== Request URL + +`PATCH :/api/note` + +==== Request body + +A JSON object defining the note content to be added. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required +|`note` | <> a|A note added to a specific Timeline event + +* `timelineId`: The `savedObjectId` of an existing Timeline the note is linked to +* `eventId`: Required if the note is linked to a specific Timeline event. +* `note`: Note content + +|Yes + + +|============================================== + +===== Example requests + +*Example 1* + +Add a note to an existing Timeline event: + +[source,console] +-------------------------------------------------- +PATCH api/note +{ + "note":{ + "eventId":"dDaPFXkB-qWtr5vqlN9o", + "note":"My note", + "timelineId":"b2c103b0-a79d-11eb-9dce-0f3114099868" + } +} +-------------------------------------------------- + + +*Example 2* + +Add a note to an existing Timeline: + +[source,console] +-------------------------------------------------- +PATCH api/note +{ + "note":{ + "note":"My note", + "timelineId":"b2c103b0-a79d-11eb-9dce-0f3114099868" + } +} +-------------------------------------------------- + +=== Pin an event to an existing Timeline + +==== Request URL + +`PATCH :/api/pinned_event` + +==== Request body + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required +|`eventId` | String |Each document has an `_id` to uniquely identify it |Yes +|`pinnedEventId` | String |A pinned event `savedObjectId` |No +|`timelineId` | String | The `savedObjectId` of an existing Timeline the pinned event is linked to |Yes + + +|============================================== + +===== Example requests + +*Example 1* + +Pin an event to an existing Timeline: + +[source,console] +-------------------------------------------------- +PATCH api/pinned_event +{ + "eventId":"LRuPFXkBVs8glbN0jXtI", + "timelineId":"b2c103b0-a79d-11eb-9dce-0f3114099868" +} +-------------------------------------------------- + + +*Example 2* + +Unpin an event: + +[source,console] +-------------------------------------------------- +PATCH api/pinned_event +{ + "eventId":"LRuPFXkBVs8glbN0jXtI", + "pinnedEventId":"9bc11e40-b312-11eb-8078-5b983613cc0f", + "timelineId":"b2c103b0-a79d-11eb-9dce-0f3114099868" +} +-------------------------------------------------- \ No newline at end of file