[Doc][SIEM]General corrections (#1001) (#1010)

* adds license requirements * adds timeline field subs * wording * typo * expands example * corrects api urls * finalises licensing text * fixes list formatting * corrections after review
elastic · Apr 22, 2020 · 2def05e · 2def05e
1 parent 2a9a7fc
commit 2def05e
Show file tree

Hide file tree

Showing 29 changed files with 102 additions and 57 deletions.
diff --git a/docs/en/siem/case-api-update-connector.asciidoc b/docs/en/siem/case-api-update-connector.asciidoc
@@ -10,7 +10,7 @@ send cases to the external system.
 
 ==== Request URL
 
-`PATCH <kibana host>/<port>/api/cases/configure`
+`PATCH <kibana host>:<port>/api/cases/configure`
 
 ==== Request body
 

diff --git a/docs/en/siem/cases-api-add-comment.asciidoc b/docs/en/siem/cases-api-add-comment.asciidoc
@@ -5,7 +5,7 @@ Adds a comment to an existing case.
 
 ==== Request URL
 
-`POST <kibana host>/<port>/api/cases/<case ID>/comments`
+`POST <kibana host>:<port>/api/cases/<case ID>/comments`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-assign-connector.asciidoc b/docs/en/siem/cases-api-assign-connector.asciidoc
@@ -10,7 +10,7 @@ send cases to the external system.
 
 ==== Request URL
 
-`POST <kibana host>/<port>/api/cases/configure`
+`POST <kibana host>:<port>/api/cases/configure`
 
 ==== Request body
 

diff --git a/docs/en/siem/cases-api-associate-sn.asciidoc b/docs/en/siem/cases-api-associate-sn.asciidoc
@@ -8,7 +8,7 @@ After sending a new or updated case to {sn}, you must associate the returned
 
 ==== Request URL
 
-`POST <kibana host>/<port>/api/cases/<case ID>/_push`
+`POST <kibana host>:<port>/api/cases/<case ID>/_push`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-create.asciidoc b/docs/en/siem/cases-api-create.asciidoc
@@ -5,7 +5,7 @@ Creates a new case.
 
 ==== Request URL
 
-`POST <kibana host>/<port>/api/cases`
+`POST <kibana host>:<port>/api/cases`
 
 ==== Request body
 

diff --git a/docs/en/siem/cases-api-delete-all-comments.asciidoc b/docs/en/siem/cases-api-delete-all-comments.asciidoc
@@ -5,7 +5,7 @@ Deletes all comments from the specified case.
 
 ==== Request URL
 
-`DELETE <kibana host>/<port>/api/cases/<case ID>/comments`
+`DELETE <kibana host>:<port>/api/cases/<case ID>/comments`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-delete-case.asciidoc b/docs/en/siem/cases-api-delete-case.asciidoc
@@ -5,7 +5,7 @@ Deletes the specified cases and all associated comments.
 
 ==== Request URL
 
-`DELETE <kibana host>/<port>/api/cases?ids=["<case ID1>","<case ID2>"]`
+`DELETE <kibana host>:<port>/api/cases?ids=["<case ID1>","<case ID2>"]`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-delete-comment.asciidoc b/docs/en/siem/cases-api-delete-comment.asciidoc
@@ -5,7 +5,7 @@ Deletes the specified comment.
 
 ==== Request URL
 
-`DELETE <kibana host>/<port>/api/cases/<case ID>/comments/<comment ID>`
+`DELETE <kibana host>:<port>/api/cases/<case ID>/comments/<comment ID>`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-find-cases.asciidoc b/docs/en/siem/cases-api-find-cases.asciidoc
@@ -10,7 +10,7 @@ parameters.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/_find`
+`GET <kibana host>:<port>/api/cases/_find`
 
 ===== URL query parameters
 

diff --git a/docs/en/siem/cases-api-find-connectors.asciidoc b/docs/en/siem/cases-api-find-connectors.asciidoc
@@ -8,7 +8,7 @@ see <<cases-actions-api-connectors>>.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/configure/connectors/_find`
+`GET <kibana host>:<port>/api/cases/configure/connectors/_find`
 
 ===== Example request
 

diff --git a/docs/en/siem/cases-api-get-case-activity.asciidoc b/docs/en/siem/cases-api-get-case-activity.asciidoc
@@ -5,7 +5,7 @@ Returns all user activity for the specified case.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/<case ID>/user_actions`
+`GET <kibana host>:<port>/api/cases/<case ID>/user_actions`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-get-case-comments.asciidoc b/docs/en/siem/cases-api-get-case-comments.asciidoc
@@ -5,7 +5,7 @@ Returns all comments for the specified case.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/<case ID>/comments`
+`GET <kibana host>:<port>/api/cases/<case ID>/comments`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-get-case.asciidoc b/docs/en/siem/cases-api-get-case.asciidoc
@@ -5,7 +5,7 @@ Returns the specified case.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/<case ID>`
+`GET <kibana host>:<port>/api/cases/<case ID>`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-get-comment.asciidoc b/docs/en/siem/cases-api-get-comment.asciidoc
@@ -5,7 +5,7 @@ Gets the specified comment.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/<case ID>/comments/<comment ID>`
+`GET <kibana host>:<port>/api/cases/<case ID>/comments/<comment ID>`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-get-connector.asciidoc b/docs/en/siem/cases-api-get-connector.asciidoc
@@ -7,7 +7,7 @@ NOTE: For more information on connectors, see <<cases-actions-api-connectors>>.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/configure`
+`GET <kibana host>:<port>/api/cases/configure`
 
 ===== Example request
 

diff --git a/docs/en/siem/cases-api-get-reporters.asciidoc b/docs/en/siem/cases-api-get-reporters.asciidoc
@@ -5,7 +5,7 @@ Returns all case reporters (users who opened cases).
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/reporters`
+`GET <kibana host>:<port>/api/cases/reporters`
 
 ===== Example request
 

diff --git a/docs/en/siem/cases-api-get-status.asciidoc b/docs/en/siem/cases-api-get-status.asciidoc
@@ -5,7 +5,7 @@ Returns the number of open and closed cases.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/status`
+`GET <kibana host>:<port>/api/cases/status`
 
 ===== Example request
 

diff --git a/docs/en/siem/cases-api-get-tags.asciidoc b/docs/en/siem/cases-api-get-tags.asciidoc
@@ -5,7 +5,7 @@ Aggregates and returns all unique tags from all cases.
 
 ==== Request URL
 
-`GET <kibana host>/<port>/api/cases/tags`
+`GET <kibana host>:<port>/api/cases/tags`
 
 ===== Example request
 

diff --git a/docs/en/siem/cases-api-update-comment.asciidoc b/docs/en/siem/cases-api-update-comment.asciidoc
@@ -5,7 +5,7 @@ Updates an existing comment.
 
 ==== Request URL
 
-`PATCH <kibana host>/<port>/api/cases/<case ID>/comments`
+`PATCH <kibana host>:<port>/api/cases/<case ID>/comments`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-api-update.asciidoc b/docs/en/siem/cases-api-update.asciidoc
@@ -5,7 +5,7 @@ Updates existing cases.
 
 ==== Request URL
 
-`PATCH <kibana host>/<port>/api/cases`
+`PATCH <kibana host>:<port>/api/cases`
 
 ==== Request body
 

diff --git a/docs/en/siem/cases-api.asciidoc b/docs/en/siem/cases-api.asciidoc
@@ -6,11 +6,11 @@ You can create, manage, configure, and send cases to external systems with
 these APIs:
 
 * Cases API: Used to open and manage security action items. The API endpoint is
-`<kibana host>/<port>/api/cases`, where `<kibana URL>` is the host name and
+`<kibana host>:<port>/api/cases`, where `<kibana URL>` is the host name and
 `<port>` is the port number of your Kibana instance.
 
 * Actions API: Used to send cases to external systems. The API endpoint
-is `<kibana host>/<port>/api/actions`. <<cases-actions-api-connectors>>
+is `<kibana host>:<port>/api/actions`. <<cases-actions-api-connectors>>
 describes how to set up integrations with third-party systems, and
 <<cases-actions-api-execute>> describes how to push {siem-app} cases to third
 party systems (currently, ServiceNow).
@@ -58,6 +58,6 @@ For example, the following call retrieves the first 20 cases:
 
 [source,sh]
 --------------------------------------------------
-curl -X GET "<kibana host>/<port>/api/cases"
+curl -X GET "<kibana host>:<port>/api/cases"
 -H 'kbn-xsrf: kibana' -u <username>:<password>
 --------------------------------------------------
diff --git a/docs/en/siem/cases-kbn-actions-api.asciidoc b/docs/en/siem/cases-kbn-actions-api.asciidoc
@@ -31,7 +31,7 @@ Creates a {sn} connector, which can then be used to open {sn} incidents from
 
 ===== Request URL
 
-`POST <kibana host>/<port>/api/action`
+`POST <kibana host>:<port>/api/action`
 
 ===== Request body
 
@@ -175,7 +175,7 @@ Updates a {sn} connector.
 
 ===== Request URL
 
-`PUT <kibana host>/<port>/api/action/<connector ID>`
+`PUT <kibana host>:<port>/api/action/<connector ID>`
 
 ===== URL parts
 
@@ -318,7 +318,7 @@ NOTE: You can only send cases to external system after you have
 
 ===== Request URL
 
-`POST <kibana host>/<port>/api/action/<connector ID>/_execute`
+`POST <kibana host>:<port>/api/action/<connector ID>/_execute`
 
 ===== URL parts
 

diff --git a/docs/en/siem/cases-overview.asciidoc b/docs/en/siem/cases-overview.asciidoc
@@ -7,13 +7,16 @@ beta[]
 
 Cases are used to open and track security issues directly in the {siem-app}. 
 They list the original reporter and all users who contribute to a case
-(`participants`). Comments support markdown syntax, and allow linking to saved
+(`participants`). Comments support Markdown syntax, and allow linking to saved
 <<timelines-overview, Timelines>>. Additionally, you can send cases to external
 systems from within the {siem-app} (currently {sn}). <<cases-ui-integrations>>
 describes how to set this up.
 
 You can create and manage cases via the UI or the <<cases-api-overview>>.
 
+NOTE: To send cases to {sn}, you need the
+https://www.elastic.co/subscriptions[appropriate license].
+
 IMPORTANT: To make sure you can view and open cases, see <<case-permisions>>.
 
 [role="screenshot"]
@@ -29,7 +32,7 @@ Open a new case to keep track of security issues and share their details with co
 . Give the case a name, and add a description and any relevant tags.
 +
 TIP: In the `Description` area, you can use
-https://www.markdownguide.org/cheat-sheet[markdown] syntax and insert a
+https://www.markdownguide.org/cheat-sheet[Markdown] syntax and insert a
 timeline link (click the icon in the top right corner of the area).
 
 . When ready, create the case.

diff --git a/docs/en/siem/cases-ui-integrations.asciidoc b/docs/en/siem/cases-ui-integrations.asciidoc
@@ -8,6 +8,9 @@ a connector, which stores the information required to push cases to {sn} via
 After you have created a connector, you can set {siem-soln} cases to close
 automatically when they are sent to {sn}.
 
+NOTE: To create a {sn} connector and send cases to {sn}, you need the
+https://www.elastic.co/subscriptions[appropriate license].
+
 [float]
 === Create a new connector
 

diff --git a/docs/en/siem/detection-engine-intro.asciidoc b/docs/en/siem/detection-engine-intro.asciidoc
@@ -12,6 +12,9 @@ for creating signals. Additionally, you can use the {kib}
 framework to send notifications via other systems, such as email and Slack,
 when signals are generated.
 
+NOTE: To use {kib} Alerting for signal notifications, you need the
+https://www.elastic.co/subscriptions[appropriate license].
+
 The {siem-app} comes with <<prebuilt-rules, prebuilt rules>> that search for
 suspicious activity on your network and hosts. For information on how to
 optimize the prebuilt rules, see <<tuning-detection-signals>>. You can also
@@ -93,9 +96,39 @@ To open and close signals, either:
 *Close/Open selected*.
 
 [float]
-=== Send signals to the Timeline
-
-To investigate a signal in the Timeline, click the *View in timeline* icon.
+[[signals-to-timelines]]
+=== Investigate signals in Timeline
+
+To investigate a signal in Timeline, click the *Investigate in timeline*
+icon.
+
+If the rule that generated the signal uses a timeline template, when you
+investigate the signal in Timeline, the following dropzone query values are
+replaced with their corresponding signal values:
+
+* `host.name`
+* `host.hostname`
+* `host.domain`
+* `host.id`
+* `host.ip`
+* `client.ip`
+* `destination.ip`
+* `server.ip`
+* `source.ip`
+* `network.community_id`
+* `user.name`
+* `process.name`
+
+*Example*
+
+The timeline template used in the rule has this dropzone query:
+`host.name: "Linux-LiverpoolFC"`. When signals generated by the rule are
+investigated in Timeline, the `host.name` value is replaced with the signal's
+`host.name` value. If the signal's `host.name` value is `Windows-ArsenalFC`,
+the timeline dropzone query is `host.name: "Windows-ArsenalFC"`.
+
+NOTE: For information on how to add timeline templates to rules, see
+<<create-rule-ui>>.
 
 [float]
 [[detections-permissions]]

diff --git a/docs/en/siem/machine-learning.asciidoc b/docs/en/siem/machine-learning.asciidoc
@@ -2,16 +2,16 @@
 [role="xpack"]
 == Anomaly Detection with Machine Learning
 
-For *Free Trial*, *{ess-trial}[Cloud]*
-and *https://www.elastic.co/subscriptions[Platinum License]* deployments,
-{kibana-ref}/xpack-ml.html[Machine Learning] functionality is available 
-on the *Detections* page. You can view the details of detected anomalies
-within the `Anomalies` table widget shown on the Hosts, Network and associated
-Details pages, or even narrow to the specific date range of an anomaly from the
-`Max Anomaly Score` details in the overview of the Host and IP Details pages.
-Each of these interfaces also offer the ability to drag and drop details of the 
-anomaly to Timeline, such as the `Entity` itself, or any of the associated 
-`Influencers`.
+{kibana-ref}/xpack-ml.html[{ml-cap}] functionality is available when
+you have the *https://www.elastic.co/subscriptions[appropriate license]*, are
+using a *{ess-trial}[cloud deployment]*, or are testing out a *Free Trial*.
+
+You can view the details of detected anomalies within the `Anomalies` table
+widget shown on the Hosts, Network and associated Details pages, or even narrow
+to the specific date range of an anomaly from the `Max Anomaly Score` details
+in the overview of the Host and IP Details pages. Each of these interfaces also
+offer the ability to drag and drop details of the anomaly to Timeline, such as
+the `Entity` itself, or any of the associated `Influencers`.
 
 [role="screenshot"]
 image::ml-ui.png[]

diff --git a/docs/en/siem/prebuilt-rules-reference.asciidoc b/docs/en/siem/prebuilt-rules-reference.asciidoc
@@ -6,10 +6,10 @@ beta[]
 
 This section lists all available prebuilt rules.
 
-IMPORTANT: You can only run {ml} prebuilt rules when you have a
-https://www.elastic.co/subscriptions[Platinum License] or you are using a
-{ess-trial}[Cloud] deployment. All {ml} prebuilt rules are tagged with `ML`,
-and their rule type is `machine_learning`.
+IMPORTANT: To run {ml} prebuilt rules, you must have the
+https://www.elastic.co/subscriptions[appropriate license] or use a
+{ess-trial}[cloud deployment]. All machine learning prebuilt rules are tagged
+with `ML`, and their rule type is `machine_learning`.
 
 [width="100%",options="header"]
 |==============================================

diff --git a/docs/en/siem/rules-api-create.asciidoc b/docs/en/siem/rules-api-create.asciidoc
@@ -9,11 +9,10 @@ You can create two types of rules:
 a document matches the rule's query.
 * {ml-cap} rules, which create a signal when a {ml} job discovers an anomaly above the defined threshold (see <<machine-learning>>).
 
-IMPORTANT: You can only create {ml} jobs when you have a
-https://www.elastic.co/subscriptions[Platinum License], are using a
-{ess-trial}[Cloud] deployment, or are testing out a *Free Trial*. Additionally,
-for the {ml} rule to function correctly, the associated {ml} job must be
-running.
+IMPORTANT: To create {ml} rules, you must have the
+https://www.elastic.co/subscriptions[appropriate license] or use a
+{ess-trial}[cloud deployment]. Additionally, for the {ml} rule to function
+correctly, the associated {ml} job must be running.
 
 To retrieve {ml} job IDs, which are required to create {ml} jobs, call the
 {ref}/ml-get-job.html[{es} Get jobs API]. {ml-cap} jobs that contain `siem` in
@@ -47,7 +46,7 @@ notifications:
 NOTE: For more information on PagerDuty fields, see https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2[PagerDuty Send a v2 Event API]. 
 
 To retrieve connector IDs, which are required to configure rule notifications,
-call `GET <kibana host>/<port>/api/action/_find`.
+call `GET <kibana host>:<port>/api/action/_find`.
 
 For detailed information on {kib} actions and alerting, and additional API
 calls, see: