From 73796a6956bb7035534098910f06a11a6b6d7a97 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Thu, 7 Mar 2024 15:13:42 +0000 Subject: [PATCH 1/3] Get Timeline API docs enhancements --- docs/events/api/timeline-api-get.asciidoc | 614 +++++++++++++++++++++- 1 file changed, 594 insertions(+), 20 deletions(-) diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc index 48aaa4582e..8f6a02bc84 100644 --- a/docs/events/api/timeline-api-get.asciidoc +++ b/docs/events/api/timeline-api-get.asciidoc @@ -1,43 +1,58 @@ [[timeline-api-get]] === Get Timelines or Timeline templates -Get Timelines or Timeline templates. +Retrieves a list of all Timelines or Timeline templates. ==== Request URL `GET :/api/timelines` -==== Request params +==== URL query parameters [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` +|`only_user_favorite` |Boolean a|If set to `true`, returns only favorite Timelines / Timeline templates. Defaults to `false`. |No -|`page_index` |Number |Page number of the result +|`page_index` |Number |The page number to return. Defaults to TBD. |No -|`page_size` |Number |Items per page in result +|`page_size` |Number |The number of items to return per page. Defaults to TBD. |No -|`search` |String |The key word of the Timelines / Timeline templates you are searching for +|`search` |String |The keyword in the Timeline / Timeline template title or description to filter the results by. |No -|`sort_field` |String |The order you want the result to be arranged. Can be `title`, `description`, `updated`, `created` +|`sort_field` |String a|The field to sort the results by. Valid values are: + +* `title` +* `description` +* `updated` +* `created` + |No -|`sort_order` |String |`asc` or `desc` +|`sort_order` |String a|The order to sort the results in. Valid values are: + +* `asc` +* `desc` + |No -|`status` |String |Can be `active` or `immutable`. `active` returns all the custom Timelines / Timeline templates, whereas `immutable` returns Elastic prebuilt templates +|`status` |String a|Defines whether to return custom Timeline / Timeline templates or Elastic prebuilt templates. Valid values are: + +* `active`: Returns custom Timelines / Timeline templates +* `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: +|`timeline_type` |String a|Defines whether to return Timelines or Timeline templates. Valid values are: + +* `default`: Returns Timelines +* `template`: Returns Timeline templates -`default` returns Timelines, `template` returns Timeline templates |No |============================================== ===== Example requests -Get Timelines: +Retrieves a list of all Timelines, sorted by the `updated` field in descending order: [source,console] -------------------------------------------------- @@ -45,42 +60,601 @@ GET api/timelines?page_size=10&page_index=1&sort_field=updated&sort_order=desc&t -------------------------------------------------- +==== Response code -=== Get Timeline / Timeline template by savedObjectId +`200`:: + Indicates a successful call. + +==== Example response + +[source,json] +-------------------------------------------------- +{ + "totalCount": 2, + "timeline": [ + { + "savedObjectId": "a3f145ed-262f-488d-b550-334fb16fc4d5", + "version": "WzEyMTQzLDFd", + "columns": [ + { + "columnHeaderType": "not-filtered", + "id": "@timestamp", + "type": "date" + }, + { + "columnHeaderType": "not-filtered", + "id": "message" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.category" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.action" + }, + { + "columnHeaderType": "not-filtered", + "id": "host.name" + }, + { + "columnHeaderType": "not-filtered", + "id": "source.ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "destination.ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "user.name" + } + ], + "dataProviders": [], + "dataViewId": "security-solution-default", + "description": "", + "eqlOptions": { + "eventCategoryField": "event.category", + "tiebreakerField": "", + "timestampField": "@timestamp", + "query": "", + "size": 100 + }, + "eventType": "all", + "excludedRowRendererIds": [], + "favorite": [], + "filters": [], + "indexNames": [ + ".alerts-security.alerts-default", + "logs-*" + ], + "kqlMode": "filter", + "kqlQuery": { + "filterQuery": null + }, + "title": "Another timeline", + "templateTimelineId": null, + "templateTimelineVersion": null, + "dateRange": { + "start": "2023-12-08T00:00:00.000Z", + "end": "2024-03-07T11:10:21.475Z" + }, + "savedQueryId": null, + "created": 1709810442736, + "createdBy": "docsuser", + "updated": 1709810443384, + "updatedBy": "docsuser", + "timelineType": "default", + "status": "active", + "sort": [ + { + "columnId": "@timestamp", + "columnType": "date", + "esTypes": [ + "date" + ], + "sortDirection": "desc" + } + ], + "savedSearchId": null, + "eventIdToNoteIds": [], + "noteIds": [], + "notes": [], + "pinnedEventIds": [], + "pinnedEventsSaveObject": [] + }, + { + "savedObjectId": "cbe6c180-7ef9-414b-b362-748ff7d96b1b", + "version": "WzEyMTQxLDFd", + "columns": [ + { + "columnHeaderType": "not-filtered", + "id": "@timestamp", + "type": "date" + }, + { + "columnHeaderType": "not-filtered", + "id": "message" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.category" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.action" + }, + { + "columnHeaderType": "not-filtered", + "id": "host.name" + }, + { + "columnHeaderType": "not-filtered", + "id": "source.ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "destination.ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "user.name" + } + ], + "dataProviders": [ + { + "and": [], + "id": "send-alert-to-timeline-action-default-draggable-event-details-value-formatted-field-value-timeline-1-alert-id-493f15b2301c94720720fb670a22092f1cc3fd42b0600c6f179f714b1a5b2584", + "name": "493f15b2301c94720720fb670a22092f1cc3fd42b0600c6f179f714b1a5b2584", + "enabled": true, + "excluded": false, + "kqlQuery": "", + "queryMatch": { + "field": "_id", + "value": "493f15b2301c94720720fb670a22092f1cc3fd42b0600c6f179f714b1a5b2584", + "operator": ":" + } + } + ], + "dataViewId": null, + "description": "", + "eqlOptions": { + "eventCategoryField": "event.category", + "tiebreakerField": "", + "timestampField": "@timestamp", + "query": "", + "size": 100 + }, + "eventType": "all", + "excludedRowRendererIds": [], + "favorite": [], + "filters": [], + "indexNames": [], + "kqlMode": "filter", + "kqlQuery": { + "filterQuery": { + "kuery": { + "kind": "kuery", + "expression": "" + }, + "serializedQuery": "" + } + }, + "title": "Test timeline", + "templateTimelineId": null, + "templateTimelineVersion": null, + "dateRange": { + "start": "2024-02-20T15:36:41.196Z", + "end": "2024-02-20T15:46:41.196Z" + }, + "savedQueryId": null, + "created": 1709809866827, + "createdBy": "docsuser", + "updated": 1709809868011, + "updatedBy": "docsuser", + "timelineType": "default", + "status": "active", + "sort": [ + { + "columnId": "@timestamp", + "columnType": "date", + "esTypes": [ + "date" + ], + "sortDirection": "desc" + } + ], + "savedSearchId": null, + "eventIdToNoteIds": [], + "noteIds": [], + "notes": [], + "pinnedEventIds": [], + "pinnedEventsSaveObject": [] + } + ], + "defaultTimelineCount": 2, + "templateTimelineCount": 10, + "elasticTemplateTimelineCount": 10, + "customTemplateTimelineCount": 0, + "favoriteCount": 0 +} +-------------------------------------------------- -Get single Timeline or Timeline template by savedObjectId. +=== Get Timeline / Timeline template by savedObjectId +Retrieves details of a single Timeline or Timeline template using `savedObjectId`. ==== Request URL `GET :/api/timeline?id=` +==== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`id` |String |The `savedObjectId` of an existing Timeline or Timeline template. |Yes + +|============================================== + ===== Example requests -Get Timeline by savedObjectId: +Retrieves details of a Timeline template with the `savedObjectId` value of `9115e3bc-444c-4c91-b844-c62717253c4e`: [source,console] -------------------------------------------------- -GET /api/timeline?id= +GET /api/timeline?id=9115e3bc-444c-4c91-b844-c62717253c4e -------------------------------------------------- +==== Response code + +`200`:: + Indicates a successful call. + +==== Example response + +[source,json] +-------------------------------------------------- +{ + "data": { + "getOneTimeline": { + "savedObjectId": "9115e3bc-444c-4c91-b844-c62717253c4e", + "version": "WzQwMjYsMV0=", + "columns": [ + { + "columnHeaderType": "not-filtered", + "id": "@timestamp", + "type": "date" + }, + { + "columnHeaderType": "not-filtered", + "id": "signal.rule.name" + }, + { + "columnHeaderType": "not-filtered", + "id": "message" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.category" + }, + { + "columnHeaderType": "not-filtered", + "id": "event.action" + }, + { + "columnHeaderType": "not-filtered", + "id": "host.name" + }, + { + "columnHeaderType": "not-filtered", + "id": "user.name" + } + ], + "dataProviders": [ + { + "excluded": false, + "and": [ + { + "excluded": false, + "kqlQuery": "", + "name": "user.name", + "queryMatch": { + "displayValue": "{user.name}", + "field": "user.name", + "displayField": "user.name", + "value": "{user.name}", + "operator": ":" + }, + "id": "timeline-1-6a1ffe5f-6188-4cf3-915d-e53c2563a1bf", + "type": "template", + "enabled": true + } + ], + "kqlQuery": "", + "name": "signal", + "queryMatch": { + "field": "event.kind", + "value": "signal", + "operator": ":" + }, + "id": "timeline-1-ac9b7ab7-0fea-4724-864c-19122139b08f", + "type": "default", + "enabled": true + } + ], + "dataViewId": null, + "description": "", + "eventType": "all", + "excludedRowRendererIds": [], + "favorite": [], + "filters": [], + "indexNames": [ + ".alerts-*" + ], + "kqlMode": "filter", + "title": "Alerts Involving a Single User Timeline", + "templateTimelineId": "3e827bab-838a-469f-bd1e-5e19a2bff2fd", + "templateTimelineVersion": 1, + "dateRange": { + "start": "2024-02-19T15:42:52.325Z", + "end": "2024-02-20T15:42:52.325Z" + }, + "savedQueryId": null, + "created": 1708443772325, + "createdBy": "Elastic", + "updated": 1708443772325, + "updatedBy": "Elastic", + "timelineType": "template", + "status": "immutable", + "sort": [ + { + "esTypes": [ + "date" + ], + "columnType": "date", + "sortDirection": "desc", + "columnId": "@timestamp" + } + ], + "eventIdToNoteIds": [], + "noteIds": [], + "notes": [], + "pinnedEventIds": [], + "pinnedEventsSaveObject": [] + } + } +} +-------------------------------------------------- + === Get Timeline template by templateTimelineId -Get a single Timeline template by templateTimelineId. +Retrieves details of a single Timeline template using `templateTimelineId`. ==== Request URL `GET :/api/timeline?template_timeline_id=` +==== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`template_timeline_id` |String |The `templateTimelineId` of an existing Timeline template. |Yes + +|============================================== + ===== Example requests -Get Timeline by templateTimelineId: +Retrieves details of a Timeline template with the `templateTimelineId` value of `300afc76-072d-4261-864d-4149714bf3f1`: + [source,console] -------------------------------------------------- -GET /api/timeline?template_timeline_id= +GET /api/timeline?template_timeline_id=300afc76-072d-4261-864d-4149714bf3f1 + +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + +==== Example response +[source,json] -------------------------------------------------- +{ + "data": { + "getOneTimeline": { + "savedObjectId": "f9ae2a43-823d-4abe-964f-084591607930", + "version": "WzQwMjQsMV0=", + "columns": [ + { + "columnHeaderType": "not-filtered", + "id": "@timestamp", + "type": "number" + }, + { + "aggregatable": false, + "description": "For log events the message field contains the log message, optimized for viewing in a log viewer. For structured logs without an original message field, other fields can be concatenated to form a human-readable summary of the event. If multiple messages exist, they can be combined into one message.", + "columnHeaderType": "not-filtered", + "id": "message", + "category": "base", + "type": "string", + "example": "Hello World" + }, + { + "aggregatable": true, + "description": "The action captured by the event. This describes the information in the event. It is more specific than `event.category`. Examples are `group-add`, `process-started`, `file-created`. The value is normally defined by the implementer.", + "columnHeaderType": "not-filtered", + "id": "event.action", + "category": "event", + "type": "string", + "example": "user-password-change" + }, + { + "aggregatable": true, + "description": "In the OSI Model this would be the Network Layer. ipv4, ipv6, ipsec, pim, etc The field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", + "columnHeaderType": "not-filtered", + "id": "network.type", + "category": "network", + "type": "string", + "example": "ipv4" + }, + { + "aggregatable": true, + "description": "Same as network.iana_number, but instead using the Keyword name of the transport layer (udp, tcp, ipv6-icmp, etc.) The field value must be normalized to lowercase for querying. See the documentation section \"Implementing ECS\".", + "columnHeaderType": "not-filtered", + "id": "network.transport", + "category": "network", + "type": "string", + "example": "tcp" + }, + { + "aggregatable": true, + "description": "Direction of the network traffic. Recommended values are: * inbound * outbound * internal * external * unknown When mapping events from a host-based monitoring context, populate this field from the host's point of view. When mapping events from a network or perimeter-based monitoring context, populate this field from the point of view of your network perimeter.", + "columnHeaderType": "not-filtered", + "id": "network.direction", + "category": "network", + "type": "string", + "example": "inbound" + }, + { + "aggregatable": true, + "description": "IP address of the source. Can be one or multiple IPv4 or IPv6 addresses.", + "columnHeaderType": "not-filtered", + "id": "source.ip", + "category": "source", + "type": "ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "source.port" + }, + { + "aggregatable": true, + "description": "IP address of the destination. Can be one or multiple IPv4 or IPv6 addresses.", + "columnHeaderType": "not-filtered", + "id": "destination.ip", + "category": "destination", + "type": "ip" + }, + { + "columnHeaderType": "not-filtered", + "id": "destination.port" + }, + { + "aggregatable": true, + "description": "Name of the host. It can contain what `hostname` returns on Unix systems, the fully qualified domain name, or a name specified by the user. The sender decides which value to use.", + "columnHeaderType": "not-filtered", + "id": "host.name", + "category": "host", + "type": "string" + }, + { + "columnHeaderType": "not-filtered", + "id": "user.name" + } + ], + "dataProviders": [ + { + "excluded": false, + "and": [], + "kqlQuery": "", + "name": "network", + "queryMatch": { + "displayValue": null, + "field": "event.category", + "displayField": null, + "value": "network", + "operator": ":" + }, + "id": "timeline-1-dbab0164-2150-47a1-a66f-75ebafe24d5c", + "type": "default", + "enabled": true + }, + { + "excluded": false, + "and": [], + "kqlQuery": "", + "name": "{signal.group.id}", + "queryMatch": { + "displayValue": null, + "field": "signal.group.id", + "displayField": null, + "value": "{signal.group.id}", + "operator": ":" + }, + "id": "timeline-1-15b52ead-4956-4ed0-bd12-e137eaf4467e", + "type": "template", + "enabled": true + }, + { + "excluded": false, + "and": [], + "kqlQuery": "", + "name": "{signal.original_event.id}", + "queryMatch": { + "field": "signal.original_event.id", + "value": "{signal.original_event.id}", + "operator": ":" + }, + "id": "timeline-1-2164774f-6409-4ac4-b73c-907914baf058", + "type": "template", + "enabled": true + } + ], + "dataViewId": null, + "description": "", + "eqlOptions": { + "tiebreakerField": "", + "size": 100, + "query": "", + "eventCategoryField": "event.category", + "timestampField": "@timestamp" + }, + "eventType": "all", + "excludedRowRendererIds": [], + "favorite": [], + "filters": [], + "indexNames": [], + "kqlMode": "filter", + "kqlQuery": { + "filterQuery": null + }, + "title": "Comprehensive Network Timeline", + "templateTimelineId": "300afc76-072d-4261-864d-4149714bf3f1", + "templateTimelineVersion": 2, + "dateRange": { + "start": "2024-02-19T15:42:52.321Z", + "end": "2024-02-20T15:42:52.322Z" + }, + "savedQueryId": null, + "created": 1708443772322, + "createdBy": "Elastic", + "updated": 1708443772322, + "updatedBy": "Elastic", + "timelineType": "template", + "status": "immutable", + "sort": [ + { + "columnType": "number", + "sortDirection": "desc", + "columnId": "@timestamp" + } + ], + "eventIdToNoteIds": [], + "noteIds": [], + "notes": [], + "pinnedEventIds": [], + "pinnedEventsSaveObject": [] + } + } +} +-------------------------------------------------- \ No newline at end of file From 89318150031ce083d97f730531bd02d2c859c5be Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Thu, 7 Mar 2024 15:39:13 +0000 Subject: [PATCH 2/3] Replaces slash --- docs/events/api/timeline-api-get.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc index 8f6a02bc84..83baf8ef50 100644 --- a/docs/events/api/timeline-api-get.asciidoc +++ b/docs/events/api/timeline-api-get.asciidoc @@ -280,7 +280,7 @@ GET api/timelines?page_size=10&page_index=1&sort_field=updated&sort_order=desc&t } -------------------------------------------------- -=== Get Timeline / Timeline template by savedObjectId +=== Get Timeline or Timeline template by savedObjectId Retrieves details of a single Timeline or Timeline template using `savedObjectId`. From 35bffcfcbf32a6958ca22f4579530dadc85cbbf7 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Mon, 11 Mar 2024 10:40:48 +0000 Subject: [PATCH 3/3] Adds default values --- docs/events/api/timeline-api-get.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc index 83baf8ef50..acdcef7cc3 100644 --- a/docs/events/api/timeline-api-get.asciidoc +++ b/docs/events/api/timeline-api-get.asciidoc @@ -15,9 +15,9 @@ Retrieves a list of all Timelines or Timeline templates. |`only_user_favorite` |Boolean a|If set to `true`, returns only favorite Timelines / Timeline templates. Defaults to `false`. |No -|`page_index` |Number |The page number to return. Defaults to TBD. +|`page_index` |Number |The page number to return. Defaults to `1`. |No -|`page_size` |Number |The number of items to return per page. Defaults to TBD. +|`page_size` |Number |The number of items to return per page. Defaults to `10`. |No |`search` |String |The keyword in the Timeline / Timeline template title or description to filter the results by. |No