Skip to content

Commit 28b98d3

Browse files
natasha-moore-elasticmergify[bot]
natasha-moore-elastic
authored and
mergify[bot]
committed
[Serverless bug bash] Updates cases API link (#6160)
* Updates cases API link * replaces link (cherry picked from commit 115cbe6) # Conflicts: # docs/serverless/alerts/signals-to-cases.asciidoc # docs/serverless/investigate/cases-open-manage.asciidoc # docs/serverless/investigate/cases-overview.asciidoc
1 parent 1719333 commit 28b98d3

File tree

6 files changed

+384
-3
lines changed

6 files changed

+384
-3
lines changed

‎docs/cases/cases-manage.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
:frontmatter-tags-content-type: [how-to]
66
:frontmatter-tags-user-goals: [analyze]
77

8-
You can create and manage cases using the UI or the <<cases-api-overview>>.
8+
You can create and manage cases using the UI or the {api-kibana}/group/endpoint-cases[cases API].
99

1010
[float]
1111
[[cases-ui-open]]

‎docs/cases/cases-overview.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
:frontmatter-tags-content-type: [overview]
66
:frontmatter-tags-user-goals: [analyze]
77

8-
Collect and share information about security issues by opening a case in {elastic-sec}. Cases allow you to track key investigation details, collect alerts in a central location, and more. The {elastic-sec} UI provides several ways to create and manage cases. Alternatively, you can use the <<cases-api-overview,cases API>> to perform the same tasks.
8+
Collect and share information about security issues by opening a case in {elastic-sec}. Cases allow you to track key investigation details, collect alerts in a central location, and more. The {elastic-sec} UI provides several ways to create and manage cases. Alternatively, you can use the {api-kibana}/group/endpoint-cases[cases API] to perform the same tasks.
99

1010
You can also send cases to these external systems by <<cases-ui-integrations, configuring external connectors>>:
1111

‎docs/detections/alerts-add-to-cases.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ From the Alerts table, you can attach one or more alerts to a <<signals-to-new-c
99

1010
[NOTE]
1111
===============================
12-
* After you add an alert to a case, you can remove it from the case activity under the alert summary or by using the <<cases-api-overview,Elastic Security Cases API>>.
12+
* After you add an alert to a case, you can remove it from the case activity under the alert summary or by using the {api-kibana}/group/endpoint-cases[cases API].
1313
* Each case can have a maximum of 1,000 alerts.
1414
===============================
1515

‎docs/serverless/alerts/signals-to-cases.asciidoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
[[security-signals-to-cases]]
2+
= Add detection alerts to cases
3+
4+
// :description: Add alerts to new or existing cases in {elastic-sec}.
5+
// :keywords: serverless, security, how-to, analyze
6+
7+
++++
8+
<titleabbrev>Add alerts to cases</titleabbrev>
9+
++++
10+
11+
12+
From the Alerts table, you can attach one or more alerts to a <<signals-to-new-cases,new case>> or <<signals-to-existing-cases,an existing one>>. Alerts from any rule type can be added to a case.
13+
14+
[NOTE]
15+
====
16+
* After you add an alert to a case, you can remove it from the case activity under the alert summary or by using the {api-kibana}/group/endpoint-cases[cases API].
17+
* Each case can have a maximum of 1,000 alerts.
18+
19+
// Link to classic docs until serverless API docs are available.
20+
====
21+
22+
[role="screenshot"]
23+
image::images/signals-to-cases/-detections-add-alert-to-case.gif[Animation of adding an alert to a case]
24+
25+
[discrete]
26+
[[signals-to-new-cases]]
27+
== Add alerts to a new case
28+
29+
To add alerts to a new case:
30+
31+
. Do one of the following:
32+
+
33+
** To add a single alert to a case, select the **More actions** menu (_..._) in the Alerts table or **Take action** in the alert details flyout, then select **Add to a new case**.
34+
** To add multiple alerts, select the alerts, then select **Add to a new case** from the **Bulk actions** menu.
35+
. Give the case a name, assign a severity level, and provide a description. You can use
36+
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax[Markdown] syntax in the case description.
37+
+
38+
[NOTE]
39+
====
40+
If you do not assign your case a severity level, it will be assigned **Low** by default.
41+
====
42+
. Optionally, add a category, assignees and relevant tags. You can add users only if they
43+
meet the necessary <<security-cases-requirements,prerequisites>>.
44+
. Specify whether you want to sync the status of associated alerts. It is enabled by default; however, you can toggle this setting on or off at any time. If it remains enabled, the alert's status updates whenever the case's status is modified.
45+
. Select a connector. If you've previously added one, that connector displays as the default selection. Otherwise, the default setting is `No connector selected`.
46+
. Click **Create case** after you've completed all of the required fields. A confirmation message is displayed with an option to view the new case. Click the link in the notification or go to the Cases page to view the case.
47+
+
48+
[role="screenshot"]
49+
image:images/signals-to-cases/-detections-add-alert-to-new-case.png[Create case flyout with sample data filled in]
50+
51+
[discrete]
52+
[[signals-to-existing-cases]]
53+
== Add alerts to an existing case
54+
55+
To add alerts to an existing case:
56+
57+
. Do one of the following:
58+
+
59+
** To add a single alert to a case, select the **More actions** menu (_..._) in the Alerts table or **Take action** in the alert details flyout, then select **Add to existing case**.
60+
** To add multiple alerts, select the alerts, then select **Add to an existing case** from the **Bulk actions** menu.
61+
. From the **Select case** dialog box, select the case to which you want to attach the alert. A confirmation message is displayed with an option to view the updated case. Click the link in the notification or go to the Cases page to view the case's details.
62+
+
63+
[NOTE]
64+
====
65+
If you attach the alert to a case that has been configured to sync its status with associated alerts, the alert's status updates any time the case's status is modified.
66+
====
67+
+
68+
[role="screenshot"]
69+
image::images/signals-to-cases/-detections-add-alert-to-existing-case.png[Select case dialog listing existing cases]

‎docs/serverless/investigate/cases-open-manage.asciidoc‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
[[security-cases-open-manage]]
2+
= Create and manage cases
3+
4+
// :description: Create a case in {elastic-sec}, and add files and visualizations.
5+
// :keywords: serverless, security, how-to, analyze, manage
6+
7+
8+
You can create and manage cases using the UI or the {api-kibana}/group/endpoint-cases[cases API].
9+
10+
// Link to classic docs until serverless API docs are available.
11+
12+
[discrete]
13+
[[cases-ui-open]]
14+
== Open a new case
15+
16+
Open a new case to keep track of security issues and share their details with
17+
colleagues.
18+
19+
. Go to **Cases**, then click **Create case**. If no cases exist, the Cases table will be empty and you'll be prompted to create one by clicking the **Create case** button inside the table.
20+
. (Optional) If you defined <<security-cases-settings-templates,templates>>, select one to use its default field values. . Give the case a name, assign a severity level, and provide a description. You can use
21+
https://www.markdownguide.org/cheat-sheet[Markdown] syntax in the case description.
22+
+
23+
[NOTE]
24+
====
25+
If you do not assign your case a severity level, it will be assigned **Low** by default.
26+
====
27+
+
28+
[TIP]
29+
====
30+
You can insert a Timeline link in the case description by clicking the Timeline icon (image:images/icons/timeline.svg[Timeline]).
31+
====
32+
. Optionally, add a category, assignees and relevant tags. You can add users only if they meet the necessary <<security-cases-requirements,prerequisites>>.
33+
. If you defined <<security-cases-settings-custom-fields,custom fields>>, they appear in the **Additional fields** section.
34+
. Choose if you want alert statuses to sync with the case's status after they are added to the case. This option is enabled by default, but you can turn it off after creating the case.
35+
. From **External incident management**, select a <<security-cases-settings,connector>>. If you've previously added one, that connector displays as the default selection. Otherwise, the default setting is `No connector selected`.
36+
. Click **Create case**.
37+
+
38+
[NOTE]
39+
====
40+
If you've selected a connector for the case, the case is automatically pushed to the third-party system it's connected to.
41+
====
42+
43+
[role="screenshot"]
44+
image::images/cases-open-manage/-cases-cases-ui-open.png[Shows an open case]
45+
46+
// NOTE: This is an autogenerated screenshot. Do not edit it directly.
47+
48+
////
49+
/*
50+
This functionality does not exist yet in serverless.
51+
To be updated: references to Kibana, ESS. Once this section is added back in, edit the frontmatter description back to: Create a case in {elastic-sec}, configure email notifications, and add files and visualizations.
52+
53+
## Add email notifications
54+
55+
You can configure email notifications that occur when users are assigned to cases.
56+
57+
For hosted {kib} on {ess}:
58+
59+
1. Add the email addresses to the monitoring email allowlist. Follow the steps in
60+
[Send alerts by email]({cloud}/ec-watcher.html#ec-watcher-allowlist).
61+
62+
You do not need to take any more steps to configure an email connector or update
63+
{kib} user settings, since the preconfigured Elastic-Cloud-SMTP connector is
64+
used by default.
65+
66+
For self-managed {kib}:
67+
68+
1. Create a preconfigured email connector.
69+
70+
<DocCallOut title="Note">
71+
At this time, email notifications support only [preconfigured email connectors]({kibana-ref}/pre-configured-connectors.html),
72+
which are defined in the `kibana.yml` file.
73+
</DocCallOut>
74+
75+
1. Set the `notifications.connectors.default.email` {kib} setting to the name of
76+
your email connector.
77+
78+
1. If you want the email notifications to contain links back to the case, you
79+
must configure the [server.publicBaseUrl]({kibana-ref}/settings.html#server-publicBaseUrl) setting.
80+
81+
When you subsequently add assignees to cases, they receive an email.
82+
83+
<div id="cases-ui-manage"></div> */
84+
////
85+
86+
[discrete]
87+
[[security-cases-open-manage-manage-existing-cases]]
88+
== Manage existing cases
89+
90+
From the Cases page, you can search existing cases and filter them by attributes such as assignees, categories, severity, status, and tags. You can also select multiple cases and use bulk actions to delete cases or change their attributes. General case metrics, including how long it takes to close cases, are provided above the table.
91+
92+
[role="screenshot"]
93+
image::images/cases-open-manage/-cases-cases-home-page.png[Case UI Home]
94+
95+
// NOTE: This is an autogenerated screenshot. Do not edit it directly.
96+
97+
To explore a case, click on its name. You can then:
98+
99+
* <<cases-summary,Review the case summary>>
100+
* <<cases-manage-comments,Add and manage comments>>
101+
+
102+
[TIP]
103+
====
104+
Comments can contain Markdown. For syntax help, click the Markdown icon (image:images/cases-open-manage/-detections-markdown-icon.png[Click markdown icon,17,17]) in the bottom right of the comment.
105+
====
106+
* Examine <<cases-examine-alerts,alerts>> and <<review-indicator-in-case,indicators>> attached to the case
107+
* <<cases-add-files,Add files>>
108+
* <<cases-lens-visualization,Add a Lens visualization>>
109+
* Modify the case's description, assignees, category, severity, status, and tags.
110+
* Manage connectors and send updates to external systems (if you've added a connector to the case)
111+
* <<cases-copy-case-uuid,Copy the case UUID>>
112+
* Refresh the case to retrieve the latest updates
113+
114+
[discrete]
115+
[[cases-summary]]
116+
=== Review the case summary
117+
118+
Click on an existing case to access its summary. The case summary, located under the case title, contains metrics that summarize alert information and response times. These metrics update when you attach additional unique alerts to the case, add connectors, or modify the case's status:
119+
120+
* **Total alerts**: Total number of unique alerts attached to the case
121+
* **Associated users**: Total number of unique users that are represented in the attached alerts
122+
* **Associated hosts**: Total number of unique hosts that are represented in the attached alerts
123+
* **Total connectors**: Total number of connectors that have been added to the case
124+
* **Case created**: Date and time that the case was created
125+
* **Open duration**: Time elapsed since the case was created
126+
* **In progress duration**: How long the case has been in the `In progress` state
127+
* **Duration from creation to close**: Time elapsed from when the case was created to when it was closed
128+
129+
[role="screenshot"]
130+
image::images/cases-open-manage/-cases-cases-summary.png[Shows you a summary of the case]
131+
132+
[discrete]
133+
[[cases-manage-comments]]
134+
=== Manage case comments
135+
136+
To edit, delete, or quote a comment, select the appropriate option from the **More actions** menu (image:images/icons/boxesHorizontal.svg[More actions]).
137+
138+
[role="screenshot"]
139+
image::images/cases-open-manage/-cases-cases-manage-comments.png[Shows you a summary of the case]
140+
141+
[discrete]
142+
[[cases-examine-alerts]]
143+
=== Examine alerts attached to a case
144+
145+
To explore the alerts attached to a case, click the **Alerts** tab. In the table, alerts are organized from oldest to newest. To <<security-view-alert-details,view alert details>>, click the **View details** button.
146+
147+
[role="screenshot"]
148+
image::images/cases-open-manage/-cases-cases-alert-tab.png[Shows you the Alerts tab]
149+
150+
[NOTE]
151+
====
152+
Each case can have a maximum of 1,000 alerts.
153+
====
154+
155+
[discrete]
156+
[[cases-add-files]]
157+
=== Add files
158+
159+
To upload files to a case, click the **Files** tab:
160+
161+
[role="screenshot"]
162+
image::images/cases-open-manage/-cases-cases-files.png[A list of files attached to a case]
163+
164+
// NOTE: This is an autogenerated screenshot. Do not edit it directly.
165+
166+
You can add images and text, CSV, JSON, PDF, or ZIP files.
167+
For the complete list, check https://github.com/elastic/kibana/blob/main/x-pack/plugins/cases/common/constants/mime_types.ts[mime_types.ts].
168+
169+
[NOTE]
170+
====
171+
There is a 10 MiB size limit for images. For all other MIME types, the limit is 100 MiB.
172+
====
173+
174+
To download or delete the file, or copy the file hash to your clipboard, open the **Actions** menu (**…**).
175+
The available hash functions are MD5, SHA-1, and SHA-256.
176+
177+
When you add a file, a comment is added to the case activity log.
178+
To view an image, click its name in the activity or file list.
179+
180+
[discrete]
181+
[[cases-lens-visualization]]
182+
=== Add a Lens visualization
183+
184+
beta::[]
185+
186+
Add a Lens visualization to your case to portray event and alert data through charts and graphs.
187+
188+
[role="screenshot"]
189+
image::images/cases-open-manage/-cases-add-vis-to-case.gif[Shows how to add a visualization to a case]
190+
191+
To add a Lens visualization to a comment within your case:
192+
193+
. Click the **Visualization** button. The **Add visualization** dialog appears.
194+
. Select an existing visualization from your Visualize Library or create a new visualization.
195+
+
196+
[IMPORTANT]
197+
====
198+
Set an absolute time range for your visualization. This ensures your visualization doesn't change over time after you save it to your case, and provides important context for others managing the case.
199+
====
200+
. Save the visualization to your Visualize Library by clicking the **Save to library** button (optional).
201+
+
202+
.. Enter a title and description for the visualization.
203+
.. Choose if you want to keep the **Update panel on Security** activated. This option is activated by default and automatically adds the visualization to your Visualize Library.
204+
. After you've finished creating your visualization, click **Save and return** to go back to your case.
205+
. Click **Preview** to show how the visualization will appear in the case comment.
206+
. Click **Add Comment** to add the visualization to your case.
207+
208+
Alternatively, while viewing a <<security-dashboards-overview,dashboard>> you can open a panel's menu then click **More actions** (image:images/icons/boxesHorizontal.svg[More actions]​) → **Add to existing case** or **More actions** (image:images/icons/boxesHorizontal.svg[More actions]​) → **Add to new case**.
209+
210+
After a visualization has been added to a case, you can modify or interact with it by clicking the **Open Visualization** option in the case's comment menu.
211+
212+
[role="screenshot"]
213+
image::images/cases-open-manage/-cases-cases-open-vis.png[Shows where the Open Visualization option is]
214+
215+
[discrete]
216+
[[cases-copy-case-uuid]]
217+
=== Copy the case UUID
218+
219+
Each case has a universally unique identifier (UUID) that you can copy and share. To copy a case's UUID to a clipboard, go to the Cases page and select **Actions** → **Copy Case ID** for the case you want to share. Alternatively, go to a case's details page, then from the **More actions** menu (image:images/icons/boxesHorizontal.svg[More actions]), select **Copy Case ID**.
220+
221+
[role="screenshot"]
222+
image::images/cases-open-manage/-cases-cases-copy-case-id.png[Copy Case ID option in More actions menu 40%]
223+
224+
[discrete]
225+
[[cases-export-import]]
226+
== Export and import cases
227+
228+
Cases can be <<cases-export,exported>> and <<cases-import,imported>> as saved objects using the Saved Objects <<security-project-settings,project settings>> UI.
229+
230+
[IMPORTANT]
231+
====
232+
Before importing Lens visualizations, Timelines, or alerts, ensure their data is present. Without it, they won't work after being imported.
233+
====
234+
235+
[discrete]
236+
[[cases-export]]
237+
=== Export a case
238+
239+
Use the **Export** option to move cases between different {elastic-sec} instances. When you export a case, the following data is exported to a newline-delimited JSON (`.ndjson`) file:
240+
241+
* Case details
242+
* User actions
243+
* Text string comments
244+
* Case alerts
245+
* Lens visualizations (exported as JSON blobs).
246+
247+
[NOTE]
248+
====
249+
The following attachments are _not_ exported:
250+
251+
* **Case files**: Case files are not exported. However, they are accessible in **Project settings** → **Management** → **Files** to download and re-add.
252+
* **Alerts**: Alerts attached to cases are not exported. You must re-add them after importing cases.
253+
====
254+
255+
To export a case:
256+
257+
. Go to **Project settings** → **Management** → **Saved objects**.
258+
. Search for the case by choosing a saved object type or entering the case title in the search bar.
259+
. Select one or more cases, then click the **Export** button.
260+
. Click **Export**. A confirmation message that your file is downloading displays.
261+
+
262+
[TIP]
263+
====
264+
Keep the **Include related objects** option enabled to ensure connectors are exported too.
265+
====
266+
267+
[role="screenshot"]
268+
image::images/cases-open-manage/-cases-cases-export-button.png[Shows the export saved objects workflow]
269+
270+
[discrete]
271+
[[cases-import]]
272+
=== Import a case
273+
274+
To import a case:
275+
276+
. Go to **Project settings** → **Management** → **Saved objects**.
277+
. Click **Import**.
278+
. Select the NDJSON file containing the exported case and configure the import options.
279+
. Click **Import**.
280+
. Review the import log and click **Done**.
281+
+
282+
[IMPORTANT]
283+
====
284+
Be mindful of the following:
285+
286+
* If the imported case had connectors attached to it, you'll be prompted to re-authenticate the connectors. To do so, click **Go to connectors** on the **Import saved objects** flyout and complete the necessary steps. Alternatively, open the main menu, then go to **Project settings** → **Management** → **{connectors-ui}** to access connectors.
287+
* If the imported case had attached alerts, verify that the alerts' source documents exist in the environment. Case features that interact with alerts (such as the Alert details flyout and rule details page) rely on the alerts' source documents to function.
288+
====

0 commit comments

Comments
 (0)