diff --git a/docs/cases/cases-index.asciidoc b/docs/cases/cases-index.asciidoc index f51f96bbd2..51e53a4ac1 100644 --- a/docs/cases/cases-index.asciidoc +++ b/docs/cases/cases-index.asciidoc @@ -1,3 +1,5 @@ include::cases-overview.asciidoc[leveloffset=+1] +include::cases-manage.asciidoc[leveloffset=+2] + include::cases-ui-integrations.asciidoc[] diff --git a/docs/cases/cases-manage.asciidoc b/docs/cases/cases-manage.asciidoc new file mode 100644 index 0000000000..a43721c9de --- /dev/null +++ b/docs/cases/cases-manage.asciidoc @@ -0,0 +1,180 @@ +[[cases-open-manage]] += Open and manage cases + +You can create and manage cases using the UI or the <>. + +[float] +[[cases-ui-open]] +== Open a new case + +Open a new case to keep track of security issues and share their details with +colleagues. + +. Go to *Investigate* -> *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. +. Give the case a name, add relevant tags, assign a severity level, and provide a description. You can use +https://www.markdownguide.org/cheat-sheet[Markdown] syntax in the case description. ++ +NOTE: If you do not assign your case a severity level, it will be assigned *Low* by default. + ++ +TIP: You can insert a Timeline link in the case description by clicking the Timeline icon (image:images/add-timeline-button.png[Timeline icon,17,17]). + +. 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. +. From *External incident management*, select a <>. If you’ve previously added one, that connector displays as the default selection. Otherwise, the default setting is `No connector selected`. +. Click *Create case*. ++ +NOTE: If you've selected a connector for the case, the case is automatically pushed to the third-party system it's connected to. + + +[role="screenshot"] +image::images/cases-ui-open.png[Shows an open case] + +[float] +[[cases-ui-manage]] +== Manage existing cases + +From the Cases page, you can search existing cases and filter them by severity, tags, reporter, and status: `Open`, `In progress`, or `Closed`. General case metrics, including how long it takes to close cases, are provided above the table. + +[role="screenshot"] +image::images/cases-home-page.png[Case UI Home] + +To explore a case, click on its name. You can then: + +* <> +* Add and <> ++ +TIP: Comments can contain Markdown. For syntax help, click the Markdown icon (image:images/markdown-icon.png[Click markdown icon,17,17]) in the bottom right of the comment. + +* <> +* <> +* Modify the case's description +* <> and send updates to external systems (if you've added a connector to the case) +* Close the case or reopen it +* Edit tags +* Update the case's severity +* Refresh the case to retrieve the latest updates + +[float] +[[cases-summary]] +=== Review the case summary + +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: + +* **Total alerts**: Total number of unique alerts attached to the case +* **Associated users**: Total number of unique users that are represented in the attached alerts +* **Associated hosts**: Total number of unique hosts that are represented in the attached alerts +* **Total connectors**: Total number of connectors that have been added to the case +* **Case created**: Date and time that the case was created +* **Open duration**: Time elapsed since the case was created +* **In progress duration**: How long the case has been in the `In progress` state +* **Duration from creation to close**: Time elapsed from when the case was created to when it was closed + +[role="screenshot"] +image::images/cases-summary.png[Shows you a summary of the case] + +[float] +[[cases-manage-comments]] +=== Manage case comments +To edit, delete, or quote a comment, select the appropriate option from the *More actions* menu (*…​*). + +[role="screenshot"] +image::images/cases-manage-comments.png[Shows you a summary of the case] + +[float] +[[cases-examine-alerts]] +=== Examine alerts attached to a case + +preview::[] + +To explore the alerts attached to a case, click the *Alerts* tab. In the table, alerts are organized from oldest to newest. To <>, click the *View details* button. + +[role="screenshot"] +image::images/cases-alert-tab.png[Shows you the Alerts tab] + +[float] +[[cases-lens-visualization]] +=== Add a Lens visualization + +beta[] + +Add a Lens visualization to your case to portray event and alert data through charts and graphs. + +[role="screenshot"] +image::images/add-vis-to-case.gif[Shows how to add a visualization to a case] + +To add a Lens visualization to a comment within your case: + +. Click the *Visualization* button. The **Add visualization** dialog appears.  +. Select an existing visualization from your Visualize Library or create a new visualization. + ++ + +IMPORTANT: 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. + ++ +. Save the visualization to your Visualize Library by clicking the *Save to library* button (optional). +.. Enter a title and description for the visualization.  +.. 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. +. After you've finished creating your visualization, click *Save and return* to go back to your case. +. Click *Preview* to show how the visualization will appear in the case comment. +. Click *Add Comment* to add the visualization to your case.  + +NOTE: Once a visualization has been added to a case, it cannot be modified or deleted. However, you can interact with the visualization by clicking the *Open Visualization* option in the comment menu. +   +[role="screenshot"] +image::images/cases-open-vis.png[Shows where the Open Visualization option is] + +[float] +[[cases-export-import]] +== Export and import cases + +Cases can be <> and <> as saved objects using the {kib} {kibana-ref}/managing-saved-objects.html[Saved Objects] UI. + +IMPORTANT: Before importing Lens visualizations, Timelines, or alerts into a space, ensure their data is present. Without it, they won't work after being imported. + +[float] +[[cases-export]] +=== Export a case +Use the *Export* option to move cases between different Kibana instances. When you export a case, the following data is exported to a newline-delimited JSON (`.ndjson`) file: + +* Case details +* User actions +* Text string comments +* Case alerts +* Lens visualizations (exported as JSON blobs). + +To export a case: + +. Open the main menu, go to *Stack Management -> {kib}*, then select the *Saved Objects* tab. +. Search for the case by choosing a saved object type or entering the case title in the search bar. +. Select one or more cases, then click the *Export* button. +. Click *Export*. A confirmation message that your file is downloading displays. + ++ +TIP: Keep the *Include related objects* option enabled to ensure connectors are exported too. + +[role="screenshot"] +image::images/cases-export-button.png[Shows the export saved objects workflow] + +[float] +[[cases-import]] +=== Import a case + +To import a case: + +. Open the main menu, go to *Stack Management -> {kib}*, then select the *Saved Objects* tab. +. Click *Import*. +. Select the NDJSON file containing the exported case and configure the import options. +. Click *Import*. +. Review the import log and click *Done*. ++ +[IMPORTANT] +========================= + +Be mindful of the following: + +* 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 *Stack Management -> Alerts and Insights -> Rules and Connectors -> Connectors* to access connectors. +* 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. + +========================= ++ diff --git a/docs/cases/cases-overview.asciidoc b/docs/cases/cases-overview.asciidoc index be4c0f0a19..86267052c1 100644 --- a/docs/cases/cases-overview.asciidoc +++ b/docs/cases/cases-overview.asciidoc @@ -3,10 +3,9 @@ = Cases -Cases are used to open and track security issues directly in the {es-sec-app}. -All cases list the original reporter and all users who contribute to a case -(`participants`). Comments support Markdown syntax and allow linking to saved <>. Additionally, you can send cases to these -external systems from within {es-sec}: +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 <> to perform the same tasks. + +You can also send cases to these external systems by <>: * {sn} ITSM * {sn} SecOps @@ -14,161 +13,7 @@ external systems from within {es-sec}: * {ibm-r} * {swimlane} -<> describes how to set up external integrations. When configuring case fields, note that data from mapped fields can be pushed to external systems but cannot be pulled in. - -You can create and manage cases using the UI or the <>. - -IMPORTANT: To send cases to external systems, you need the -https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For information about the base role privileges you need to access cases, refer to <>. - -NOTE: From {elastic-sec}, you cannot access cases created in {observability} or Stack Management. - [role="screenshot"] image::images/cases-home-page.png[Case UI Home] -[float] -[[cases-ui-open]] -== Open a new case - -Open a new case to keep track of security issues and share their details with -colleagues. - -. Go to *Investigate* -> *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. -. 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 -timeline link (click the icon in the top right corner of the area). - -. Choose whether 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 still turn it off after creating the case. -. When ready, create the case. -. If external connections are configured, you can: -* Select which connector is used to send the case to an external system -(`External incident management system`). -* Send the case to an external system. You can send the case to more than one -external system. - -[role="screenshot"] -image::images/cases-ui-open.png[Shows an open case] - -[float] -[[cases-ui-manage]] -== Manage existing cases - -From the Cases page, you can search existing cases and filter them by tags, reporter, and status -(open, in-progress, or closed). - -To explore a case, click on its name. You can then: - -* <> -* Add a new comment -* <> -* Edit existing comments and the case's description -* Add a connector (if you did not select one while creating the case) -* Send updates to external systems (if external connections are configured) -* Close the case -* Reopen a closed case -* Edit tags -* Refresh the case to retrieve the latest updates - -NOTE: Comments can also contain Markdown syntax and Timeline links. - -[float] -[[cases-summary]] -== Review the case summary - -Click on an existing case to access the case 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 more connectors, or modify the case's status: - -* **Total alerts**: Total number of unique alerts attached to the case. -* **Associated users**: Total number of unique users that are represented in the attached alerts. -* **Associated hosts**: Total number of unique hosts that are represented in the attached alerts. -* **Total connectors**: Total number of connectors that have been added to the case. -* **Case created**: Date and time that the case was created. -* **Open duration**: Time elapsed since the case was created. -* **In progress duration**: How long the case has been in the `In progress` state. -* **Duration from creation to close**: Time elapsed from when the case was created to when it was closed. - -[role="screenshot"] -image::images/cases-summary.png[Shows you a summary of the case] - -[float] -[[cases-lens-visualization]] -== Add a Lens visualization - -beta[] - -Add a Lens visualization to your case to portray event and alert data through charts and graphs. - -[role="screenshot"] -image::images/add-vis-to-case.gif[Shows how to add a visualization to a case] - -To add a Lens visualization to a comment within your case: - -. Click the *Visualization* button. The Add visualization dialog appears.  -. Select an existing visualization from your Visualize Library or create a new visualization. - -+ - -IMPORTANT: 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. - -+ -. Save the visualization to your Visualize Library by clicking the *Save to library* button (optional). -.. Enter a title and description for the visualization.  -.. Choose whether 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. -. After you've finished creating your visualization, click *Save and return* to go back to your case. -. Click *Preview* to show how the visualization will appear in the case comment. -. Click *Add Comment* to add the visualization to your case.  - -NOTE: Once a visualization has been added to a case, it cannot be modified or deleted. However, you can interact with the visualization by clicking the *Open Visualization* option in the comment menu. -   -[role="screenshot"] -image::images/cases-open-vis.png[Shows where the Open Visualization option is] - -[float] -[[cases-export-import]] -== Export and import cases - -Cases can be <> and <> as saved objects through the Kibana {kibana-ref}/managing-saved-objects.html[Saved Objects] UI. - -IMPORTANT: Before importing Lens visualizations, Timelines, or alerts into a space, ensure their data is present. Without it, they won't work after being imported. - -[float] -[[cases-export]] -=== Export a case -Use the *Export* option to move cases between different Kibana instances. When you export a case, the following data is exported to a newline-delimited JSON (`.ndjson`) file: case details, user actions, text string comments, case alerts, and lens visualizations (which are exported as JSON blobs). - -To export a case: - -. Open the main menu, click *Stack Management -> Kibana*, then select the *Saved Objects* tab. -. Search for the case by choosing a saved object type or entering the case title in the search bar. -. Select one or more cases, then click the *Export* button. -. Click *Export*. A confirmation message that your file is downloading displays. - -+ -TIP: Keep the *Include related objects* option enabled to ensure connectors are exported too. - -[role="screenshot"] -image::images/cases-export-button.png[Shows the export saved objects workflow] - -[float] -[[cases-import]] -=== Import a case - -To import a case: - -. Open the main menu, click *Stack Management -> Kibana* and then select the *Saved Objects* tab. -. Click *Import*. -. Select the NDJSON file containing the exported case and configure the import options. -. Click *Import*. -. Review the import log and click *Done*. -+ -[IMPORTANT] -========================= - -Be mindful of the following: - -* 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 *Stack Management -> Alerts and Insights -> Rules and Connectors -> Connectors* to access connectors. -* If the imported case had attached alerts, verify that the alerts’ source documents are present 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. - -========================= -+ +NOTE: From {elastic-sec}, you cannot access cases created in {observability} or Stack Management. diff --git a/docs/cases/cases-ui-integrations.asciidoc b/docs/cases/cases-ui-integrations.asciidoc index fd63099cd7..962ada2c82 100644 --- a/docs/cases/cases-ui-integrations.asciidoc +++ b/docs/cases/cases-ui-integrations.asciidoc @@ -17,7 +17,7 @@ After you have created a connector, you can set {es-sec} cases to automatically close when they are sent to external systems. NOTE: To create connectors and send cases to external systems, you need the -https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For more information, see <>. +https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For more information, refer to <>. [[create-new-connector]] [float] @@ -67,7 +67,7 @@ authenticate {ibm-r} updates. . Save the connector. -TIP: To see how to connect {elastic-sec} to {jira}, watch the <> at the end of this topic. +TIP: To learn how to connect {elastic-sec} to {jira}, check out the <> at the end of this topic. To represent an {es-sec} case in an external system, {es-sec} case fields are mapped as follows: @@ -110,22 +110,33 @@ Security case description is sent to {swimlane}, the field that is mapped to the field is overwritten. ** *Comments*: Mapped to the {swimlane} `Comments` field. When a new comment is added to a Security case, or an existing one is updated, the field that is mapped to the {swimlane} `Comment` field is appended. Comments are posted to the {swimlane} incident record individually. +[[close-connector]] [float] === Close sent cases automatically To close cases when they are sent to an external system, select *Automatically close Security cases when pushing new incident to external system*. +[[default-connector]] [float] === Change the default connector To change the default connector used to send cases to external systems, go to *Cases* -> *Edit external connection* and select the required connector from the Incident management system list. -TIP: You can also configure which connector is used for each case individually. See <>. - [role="screenshot"] image::images/cases-change-default-connector.png[Shows list of available connectors] +[[add-connector]] +[float] +=== Add connectors + +After you <>, you can add connectors to it. From the case details page, go to *External incident management system*, then select a connector. A case can have multiple connectors, but only one connector can be selected at a time. + +[role="screenshot"] +image::images/add-connectors.png[width=60%][height=60%][Shows how to add connectors] + + +[[modify-connector]] [float] === Modify connector settings @@ -143,7 +154,7 @@ image::images/cases-modify-connector.png[] [[connect-security-to-jira]] === Tutorial: Connect {elastic-sec} to {jira} -To see how to connect {elastic-sec} to {jira}, watch the following tutorial. +To learn how to connect {elastic-sec} to {jira}, check out the following tutorial. ======= ++++ diff --git a/docs/cases/images/add-connectors.png b/docs/cases/images/add-connectors.png new file mode 100644 index 0000000000..09c7ea617d Binary files /dev/null and b/docs/cases/images/add-connectors.png differ diff --git a/docs/cases/images/add-timeline-button.png b/docs/cases/images/add-timeline-button.png new file mode 100644 index 0000000000..4062c9b5f1 Binary files /dev/null and b/docs/cases/images/add-timeline-button.png differ diff --git a/docs/cases/images/add-vis-to-case.gif b/docs/cases/images/add-vis-to-case.gif index c7d4f5c36c..f6918496e2 100644 Binary files a/docs/cases/images/add-vis-to-case.gif and b/docs/cases/images/add-vis-to-case.gif differ diff --git a/docs/cases/images/cases-alert-tab.png b/docs/cases/images/cases-alert-tab.png new file mode 100644 index 0000000000..90354f2e42 Binary files /dev/null and b/docs/cases/images/cases-alert-tab.png differ diff --git a/docs/cases/images/cases-export-button.png b/docs/cases/images/cases-export-button.png index a1484cb155..c1b17befac 100644 Binary files a/docs/cases/images/cases-export-button.png and b/docs/cases/images/cases-export-button.png differ diff --git a/docs/cases/images/cases-home-page.png b/docs/cases/images/cases-home-page.png index a8f3e3ac4d..12061dd3c4 100644 Binary files a/docs/cases/images/cases-home-page.png and b/docs/cases/images/cases-home-page.png differ diff --git a/docs/cases/images/cases-manage-comments.png b/docs/cases/images/cases-manage-comments.png new file mode 100644 index 0000000000..8612ac725a Binary files /dev/null and b/docs/cases/images/cases-manage-comments.png differ diff --git a/docs/cases/images/cases-open-vis.png b/docs/cases/images/cases-open-vis.png index 9b8e08cfd9..890c856ddc 100644 Binary files a/docs/cases/images/cases-open-vis.png and b/docs/cases/images/cases-open-vis.png differ diff --git a/docs/cases/images/cases-summary.png b/docs/cases/images/cases-summary.png index 6191dc0dcb..b9d8d51100 100644 Binary files a/docs/cases/images/cases-summary.png and b/docs/cases/images/cases-summary.png differ diff --git a/docs/cases/images/cases-ui-open.png b/docs/cases/images/cases-ui-open.png index f5f9e82f76..1db008f83e 100644 Binary files a/docs/cases/images/cases-ui-open.png and b/docs/cases/images/cases-ui-open.png differ diff --git a/docs/detections/alerts-ui-manage.asciidoc b/docs/detections/alerts-ui-manage.asciidoc index 4bf4bef9a9..d8060dd201 100644 --- a/docs/detections/alerts-ui-manage.asciidoc +++ b/docs/detections/alerts-ui-manage.asciidoc @@ -62,7 +62,7 @@ image::images/additional-filters.png[Shows multiple ways to filter information] === Customize the Alerts table Use the toolbar buttons in the upper-left of the Alerts table to customize the columns you want displayed: -* **Columns**: Reorder the columns. +* **Columns**: Reorder the columns. * **_x_ fields sorted**: Sort the table by one or more columns. * **Fields**: Select the fields to display in the table. You can also add <> to detection alerts and display them in the Alerts table. @@ -171,7 +171,7 @@ The *JSON* tab shows the alert details in JSON format. === Take actions on an alert From the Alerts table or the Alert details flyout, you can do the following: -* <> +* <> * <> * <> * <> @@ -199,9 +199,7 @@ image::images/alert-change-status.gif[width=50%][height=50%][Shows how to change [float] [[signals-to-cases]] === Add alerts to cases -From the Alerts table, you can attach one or more alerts to a case by clicking the *More actions* menu. You can choose to <> or <>. You can also add an alert to a case from the Alert details flyout by clicking **Take action**. - -You can add multiple alerts from any rule type. 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. +From the Alerts table, you can attach one or more alerts to a <> or <>. Alerts from any rule type can be added to a case. NOTE: Once you've added an alert to a case, you can only remove it through the <>. @@ -210,12 +208,18 @@ image::images/add-alert-to-case.gif[width=50%][height=50%][Shows how to add an a [float] [[signals-to-new-cases]] -==== Add an alert to a new case -To add an alert to a new case: +==== Add alerts to a new case +To add alerts to a new case: + +. Do one of the following: +** 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*. +** To add multiple alerts, select the alerts, then select +*Add to a new case* from the *Bulk actions* menu. +. In the **Create new case** flyout, give your case a name, add relevant tags (optional), assign a severity level, and include a case description. ++ +NOTE: If you do not assign your case a severity level, it will be assigned *Low* by default. -. Select the *More actions* menu (*...*) in the Alerts table, or **Take action** in the Alert details flyout, then select -*Add exception*. -. In the **Create new case** flyout, give your case a name, add relevant tags (optional), and include a case description. . 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. . Select a connector. If you've previously added one, that connector displays as the default selection. Otherwise, the default setting is `No connector selected`. . 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. @@ -225,11 +229,15 @@ image::images/add-alert-to-new-case.png[Shows how to add an alert to an existing [float] [[signals-to-existing-cases]] -==== Add an alert to an existing case -To attach an alert to an existing case: +==== Add alerts to an existing case +To add alerts to an existing case: -. Select the *More actions* menu (*...*) in the Alerts table or **Take action** in the Alert details flyout, then select **Add to existing case**. +. Do one of the following: +** 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**. +** To add multiple alerts, select the alerts, then select *Add to an existing case* from the *Bulk actions* menu. . 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. ++ +NOTE: 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. [role="screenshot"] image::images/add-alert-to-existing-case.png[Shows how to add an alert to an existing case] diff --git a/docs/detections/images/add-alert-to-existing-case.png b/docs/detections/images/add-alert-to-existing-case.png index 9e6f507386..4c7cee727a 100644 Binary files a/docs/detections/images/add-alert-to-existing-case.png and b/docs/detections/images/add-alert-to-existing-case.png differ diff --git a/docs/detections/images/add-alert-to-new-case.png b/docs/detections/images/add-alert-to-new-case.png index 6237396341..622c6aba7a 100644 Binary files a/docs/detections/images/add-alert-to-new-case.png and b/docs/detections/images/add-alert-to-new-case.png differ diff --git a/docs/detections/images/markdown-icon.png b/docs/detections/images/markdown-icon.png new file mode 100644 index 0000000000..b0f8c99433 Binary files /dev/null and b/docs/detections/images/markdown-icon.png differ