Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Doc][SIEM]General corrections #1001

Merged
merged 9 commits into from
Apr 22, 2020
Merged

[Doc][SIEM]General corrections #1001

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0da1165
adds license requirements
Apr 20, 2020
40f9bdd
adds timeline field subs
Apr 20, 2020
b5a8833
wording
Apr 20, 2020
9c22afc
typo
Apr 21, 2020
fb234dd
expands example
Apr 21, 2020
c0cbac4
corrects api urls
Apr 22, 2020
f771355
finalises licensing text
Apr 22, 2020
40dfa5a
fixes list formatting
Apr 22, 2020
28ecd18
corrections after review
Apr 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/en/siem/case-api-update-connector.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-add-comment.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-assign-connector.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-associate-sn.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Creates a new case.

==== Request URL

`POST <kibana host>/<port>/api/cases`
`POST <kibana host>:<port>/api/cases`

==== Request body

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-delete-all-comments.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-delete-case.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-delete-comment.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-find-cases.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ parameters.

==== Request URL

`GET <kibana host>/<port>/api/cases/_find`
`GET <kibana host>:<port>/api/cases/_find`

===== URL query parameters

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-find-connectors.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-case-activity.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-case-comments.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-case.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-comment.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-connector.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-reporters.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-status.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-get-tags.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-update-comment.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/en/siem/cases-api-update.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Updates existing cases.

==== Request URL

`PATCH <kibana host>/<port>/api/cases`
`PATCH <kibana host>:<port>/api/cases`

==== Request body

Expand Down
6 changes: 3 additions & 3 deletions docs/en/siem/cases-api.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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>
--------------------------------------------------
6 changes: 3 additions & 3 deletions docs/en/siem/cases-kbn-actions-api.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
7 changes: 5 additions & 2 deletions docs/en/siem/cases-overview.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions docs/en/siem/cases-ui-integrations.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
35 changes: 34 additions & 1 deletion docs/en/siem/detection-engine-intro.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -93,9 +96,39 @@ To open and close signals, either:
*Close/Open selected*.

[float]
[[signals-to-timelines]]
=== Send signals to the Timeline
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we use "Investigate signals in Timeline" rather than "Send". (Send implies that you might be moving it to the timeline, but it will actually stay in the signals table).


To investigate a signal in the Timeline, click the *View in timeline* icon.
To investigate a signal in the Timeline, click the *Investigate in timeline*
icon.

If the rule that generated the signal uses a timeline template, when you send
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change "when you send" to "when you investigate"

the signal to the Timeline, the following dropzone query values are replaced
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change "to the Timeline" to "in the Timeline"

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 query:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

replace "query" with "dropzone query". (I know it seems overly detailed, but to avoid confusion with Saved Queries or KQL queries, I think we should repeat "dropzone" each time.)

`host.name: "Linux-LiverpoolFC"`. When signals generated by the rule are sent
to the 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 query is `host.name: "Windows-ArsenalFC"`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

again "dropzone query"


NOTE: For information on how to add timeline templates to rules, see
<<create-rule-ui>>.

[float]
[[detections-permissions]]
Expand Down
20 changes: 10 additions & 10 deletions docs/en/siem/machine-learning.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
8 changes: 4 additions & 4 deletions docs/en/siem/prebuilt-rules-reference.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
|==============================================
Expand Down
11 changes: 5 additions & 6 deletions docs/en/siem/rules-api-create.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Loading