[Security Solution] Webhook - Case Management Connector Documentation (#137726)

Co-authored-by: lcawl <lcawley@elastic.co>

docs/management/action-types.asciidoc

@@ -7,58 +7,62 @@ Connectors provide a central place to store connection information for services
 [cols="2"]
 |===
 
-a| <<email-action-type, Email>>
+a| <<email-action-type,Email>>
 
 | Send email from your server.
 
-a| <<resilient-action-type, IBM Resilient>>
+a| <<resilient-action-type,{ibm-r}>>
 
-| Create an incident in IBM Resilient.
+| Create an incident in {ibm-r}.
 
-a| <<index-action-type, Index>>
+a| <<index-action-type,Index>>
 
 | Index data into Elasticsearch.
 
-a| <<jira-action-type, Jira>>
+a| <<jira-action-type,Jira>>
 
 | Create an incident in Jira.
 
-a| <<teams-action-type, Microsoft Teams>>
+a| <<teams-action-type,Microsoft Teams>>
 
 | Send a message to a Microsoft Teams channel.
 
-a| <<pagerduty-action-type, PagerDuty>>
+a| <<pagerduty-action-type,PagerDuty>>
 
 | Send an event in PagerDuty.
 
-a| <<server-log-action-type, ServerLog>>
+a| <<server-log-action-type,ServerLog>>
 
 | Add a message to a Kibana log.
 
-a| <<servicenow-action-type, ServiceNow ITSM>>
+a| <<servicenow-action-type,{sn-itsm}>>
 
-| Create an incident in ServiceNow.
+| Create an incident in {sn}.
 
-a| <<servicenow-sir-action-type, ServiceNow SecOps>>
+a| <<servicenow-sir-action-type,{sn-sir}>>
 
-| Create a security incident in ServiceNow.
+| Create a security incident in {sn}.
 
-a| <<servicenow-itom-action-type, ServiceNow ITOM>>
+a| <<servicenow-itom-action-type,{sn-itom}>>
 
-| Create an event in ServiceNow.
+| Create an event in {sn}.
 
-a| <<slack-action-type, Slack>>
+a| <<slack-action-type,Slack>>
 
 | Send a message to a Slack channel or user.
 
-a| <<swimlane-action-type, Swimlane>>
+a| <<swimlane-action-type,{swimlane}>>
 
-| Create an incident in Swimlane.
+| Create an incident in {swimlane}.
 
-a| <<webhook-action-type, Webhook>>
+a| <<webhook-action-type, {webhook}>>
 
 | Send a request to a web service.
 
+a| <<cases-webhook-action-type,{webhook-cm}>>
+
+| Send a request to a Case Management web service.
+
 a| <<xmatters-action-type,xMatters>>
 
 | Send actionable alerts to on-call xMatters resources.
@@ -68,7 +72,7 @@ a| <<xmatters-action-type,xMatters>>
 ==============================================
 Some connector types are paid commercial features, while others are free.
 For a comparison of the Elastic subscription levels,
-see https://www.elastic.co/subscriptions[the subscription page].
+see {subscriptions}[the subscription page].
 ==============================================
 
 [float]

docs/management/cases/add-connectors.asciidoc

@@ -6,11 +6,12 @@ preview::[]
 You can add connectors to cases to push information to these external incident
 management systems:
 
-* IBM Resilient
-* Jira
-* ServiceNow ITSM
-* ServiceNow SecOps
+* {ibm-r}
+* {jira}
+* {sn-itsm}
+* {sn-sir}
 * {swimlane}
+* {webhook-cm}
 
 NOTE: To create connectors and send cases to external systems, you must have the
 appropriate {kib} feature privileges. Refer to <<setup-cases>>.
@@ -34,7 +35,8 @@ image::images/cases-connectors.png[]
 
 . Enter your required settings. Refer to <<resilient-action-type>>,
 <<jira-action-type>>, <<servicenow-action-type>>, <<servicenow-sir-action-type>>,
-or <<swimlane-action-type>> for connector configuration details.
+<<swimlane-action-type>>, or <<cases-webhook-action-type>> for connector
+configuration details.
 
 . Click *Save*.
 
@@ -53,4 +55,5 @@ external system, update the case closure options.
 . To change the default connector for new cases, select the connector from the
 *Incident management system* list.
 
-. To update a connector, click *Update <connector name>* and edit the connector fields as required.
+. To update a connector, click *Update <connector name>* and edit the connector
+fields as required.

docs/management/connectors/action-types/cases-webhook.asciidoc

@@ -0,0 +1,390 @@
+[role="xpack"]
+[[cases-webhook-action-type]]
+== {webhook-cm} connector and action
+++++
+<titleabbrev>{webhook-cm}</titleabbrev>
+++++
+
+The {webhook-cm} connector uses https://github.com/axios/axios[axios] to send POST, PUT, and GET requests to a case management RESTful API web service.
+
+[float]
+[[cases-webhook-connector-configuration]]
+=== Connector configuration
+
+{webhook-cm} connectors have the following configuration properties:
+
+Name::      The name of the connector. The name is used to identify a connector in the management UI connector listing and in the connector list when configuring an action.
+Require authentication:: If true, a username and password for login type authentication must be provided.
+Username::      Username for HTTP basic authentication.
+Password::  Password for HTTP basic authentication.
+Headers::   A set of key-value pairs sent as headers with the request URLs for the create case, update case, get case, and create comment methods.
+Create case method:: REST API HTTP request method to create a case in the third-party system, either `post`(default), `put`, or `patch`.
+Create case URL:: REST API URL to create a case in the third-party system. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
+Create case object:: A JSON payload sent to the create case URL to create a case. Use the variable selector to add case data to the payload. Required variables are `case.title` and `case.description`. For example:
++
+[source,json]
+--
+{
+	"fields": {
+	  "summary": {{{case.title}}},
+	  "description": {{{case.description}}},
+	  "labels": {{{case.tags}}}
+	}
+}
+--
++
+NOTE: Due to Mustache template variables (the text enclosed in triple braces, for example, `{{{case.title}}}`), the JSON is not validated in this step. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+Create case response - case ID key:: JSON key in the create case response that contains the external case ID.
+Get case URL:: REST API URL to GET case by ID from the third-party system. Use the variable selector to add the external system ID to the URL. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts. For example:
++
+[source,text]
+--
+https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}
+--
++
+NOTE: Due to Mustache template variables (the text enclosed in triple braces, for example, `{{{case.title}}}`), the JSON is not validated in this step. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+Get case response - title key:: JSON key in get case response that contains the external case title
+External case view URL:: URL to view case in the external system. Use the variable selector to add the external system ID or external system title to the URL. For example:
++
+[source,text]
+--
+https://testing-jira.atlassian.net/browse/{{{external.system.title}}}
+--
+Update case method:: REST API HTTP request method to update the case in the third-party system, either `post`, `put`(default), or `patch`.
+Update case URL:: REST API URL to update the case by ID in the third-party system. Use the variable selector to add the external system ID to the URL. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts. For example:
++
+[source,text]
+--
+https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.ID}}}
+--
+
+Update case object:: A JSON payload sent to the update case URL to update the case. Use the variable selector to add Kibana Cases data to the payload. Required variables are `case.title` and `case.description`. For example:
++
+[source,json]
+--
+{
+	"fields": {
+	  "summary": {{{case.title}}},
+	  "description": {{{case.description}}},
+	  "labels": {{{case.tags}}}
+	}
+}
+--
++
+NOTE: Due to Mustache template variables (which is the text enclosed in triple braces, for example, `{{{case.title}}}`), the JSON is not validated in this step. The JSON is validated after the Mustache variables have been placed when REST method runs. Manually ensure that the JSON is valid to avoid future validation errors; disregard Mustache variables during your review.
+
+Create comment method:: (Optional) REST API HTTP request method to create a case comment in the third-party system, either `post`, `put`(default), or `patch`.
+
+Create comment URL:: (Optional) REST API URL to create a case comment by ID in the third-party system. Use the variable selector to add the external system ID to the URL. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts. For example:
++
+[source,text]
+--
+https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment
+--
+
+Create comment object:: (Optional) A JSON payload sent to the create comment URL to create a case comment. Use the variable selector to add Kibana Cases data to the payload. The required variable is `case.comment`. For example:
++
+[source,json]
+--
+{
+  "body": {{{case.comment}}}
+}
+--
++
+NOTE: Due to Mustache template variables (the text enclosed in triple braces, for example, `{{{case.title}}}`), the JSON is not validated in this step. The JSON is validated once the mustache variables have been placed and when REST method runs. We recommend manually ensuring that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+[float]
+[[cases-webhook-connector-networking-configuration]]
+=== Connector networking configuration
+
+Use the <<action-settings,action configuration settings>> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations.
+
+[float]
+[[Preconfigured-cases-webhook-configuration]]
+=== Preconfigured connector type
+
+[source,text]
+--
+ my-case-management-webhook:
+   name: Case Management Webhook Connector
+   actionTypeId: .cases-webhook
+   config:
+     hasAuth: true
+     headers:
+       'content-type': 'application/json'
+     createIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue'
+     createIncidentMethod: 'post'
+     createIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}'
+     getIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}'
+     getIncidentResponseExternalTitleKey: 'key'
+     viewIncidentUrl: 'https://testing-jira.atlassian.net/browse/{{{external.system.title}}}'
+     updateIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}'
+     updateIncidentMethod: 'put'
+     updateIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}'
+     createCommentMethod: 'post',
+     createCommentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment',
+     createCommentJson: '{"body": {{{case.comment}}}}',
+   secrets:
+     user: testuser
+     password: passwordvalue
+--
+
+`config`:: Defines information for the connector type.
+`hasAuth`::: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
+`headers`::: A `record<string, string>` that corresponds to *Headers*.
+`createIncidentUrl`::: A URL string that corresponds to *Create Case URL*.
+`createIncidentMethod`::: A string that corresponds to *Create Case Method*.
+`createIncidentJson`::: A stringified JSON with Mustache variables that corresponds to *Create Case JSON*.
+`createIncidentResponseKey`::: A string from the response body of the create case method that corresponds to the *External Service Id*.
+`getIncidentUrl`::: A URL string with an *External Service Id* Mustache variable that corresponds to *Get Case URL*.
+`getIncidentResponseExternalTitleKey`::: A string from the response body of the get case method that corresponds to the *External Service Title*.
+`viewIncidentUrl`::: A URL string with either the *External Service Id* or *External Service Title* Mustache variable that corresponds to *View Case URL*.
+`updateIncidentUrl`::: A URL string that corresponds to *Update Case URL*.
+`updateIncidentMethod`::: A string that corresponds to *Update Case Method*.
+`updateIncidentJson`::: A stringified JSON with Mustache variables that corresponds to *Update Case JSON*.
+`createCommentUrl`::: A URL string that corresponds to *Create Comment URL*.
+`createCommentMethod`::: A string that corresponds to *Create Comment Method*.
+`createCommentJson`::: A stringified JSON with Mustache variables that corresponds to *Create Comment JSON*.
+
+`secrets`:: Defines sensitive information for the connector type.
+`user`::: A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
+`password`::: A string that corresponds to *Password*. Required if `hasAuth` is set to `true`.
+
+[float]
+[[define-cases-webhook-ui]]
+=== Define connector in {stack-manage-app}
+
+Define {webhook-cm} connector properties:
+
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-connector.gif[{webhook-cm} connector]
+
+Test {webhook-cm} action parameters:
+
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-test.gif[{webhook-cm} params test]
+
+[float]
+[[cases-webhook-action-configuration]]
+=== Action configuration
+
+{webhook-cm} actions have the following configuration properties:
+
+Title:: A title for the issue, which is used for searching the contents of the knowledge base.
+Description:: The details about the incident.
+Labels:: The labels for the incident.
+Additional comments:: Additional information for the client, such as how to troubleshoot the issue.
+
+////
+[float]
+[[cases-webhook-connector-full-example]]
+== Full example with third-party system
+
+In the following example, we connect the {webhook-cm} Connector with a demo instance of {jira} (a third-party case management system). Refer to the https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/[{Jira} API documentation] to learn how to create an issue.
+
+NOTE: If you want to connect with {jira} quickly, we recommend using the <<jira-action-type,preconfigured {jira} connector>>.
+
+[float]
+====  Step 1 - Set up connector
+
+In the {webhook-cm} connector create flyout, begin by entering a connector *Name*, for example, `Jira Test Connector`. Basic authentication will be used in this example, so keep the *Require authentication* option selected and enter the *Username* and *Password* for the test instance, for example, `test-user@elastic.co` and `notarealpassword`. We will not be setting any *Headers* for the requests.
+
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-step1.png[{webhook-cm} connector Step 1, {jira} example]
+
+[float]
+====  Step 2 - Create case
+
+To find the required values for this step, refer to the https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post[{jira} create issue method documentation].
+
+{jira} create issue request method: `POST`
+
+{jira} create issue request URL: `/rest/api/2/issue`
+
+{jira} create issue request body:
+[source,json]
+--
+{
+    "fields": {
+        "summary": "Main order flow broken",
+        "description": "Order entry fails when selecting supplier.",
+        "labels": ["bugfix",  "blitz_test"],
+        "project":{"key":"PROJ-123"},
+        "issuetype":{"id":"10000"}
+    }
+}
+--
+
+{jira} create issue response body:
+[source,json]
+--
+{
+  "id": "10000",
+  "key": "ED-24",
+  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10000",
+  "transition": {
+    "status": 200,
+    "errorCollection": {
+      "errorMessages": [],
+      "errors": {}
+    }
+  }
+}
+--
+In the following screen capture, we enter `POST` as the *Create Case Method* and `https://testing-jira.atlassian.net/rest/api/2/issue` as the **Create Case Url**. In our example {jira} instance, the project key is "ROC" and the issuetype ID is "10024". We have entered the {jira} request JSON as the *Create Case Object*, updating the project key to "ROC" and the issuetype ID to "10024". We then use the Case variable selector to enter where we will map the Kibana case title, Kibana case description, and Kibana case tags. The {jira} response body contains an ID with the JSON key of "id", so we enter `id` as the *Create Case Response - Case ID Key*.
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-step2.gif[{webhook-cm} connector Step 2, {jira} example]
+
+[float]
+====  Step 3 - Get case information
+
+Next we'll need to look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-[Get issue method documentation] to find the values for this step. In the GET response JSON below, we thinned out some null and unrelated data so that we can focus on the fields we need.
+
+{jira} get issue request URL: `/rest/api/2/issue/{issueIdOrKey}`
+
+{jira} get issue response body:
+[source,json]
+--
+{
+    "id": "71964",
+    "self": "https://testing-jira.atlassian.net/rest/api/2/issue/71964",
+    "key": "ROC-584",
+    "fields": {
+        "issuetype": {
+            "self": "https://testing-jira.atlassian.net/rest/api/2/issuetype/10024",
+            "id": "10024",
+            "description": "An improvement or enhancement to an existing feature or task.",
+            "name": "Improvement",
+            "subtask": false,
+            "avatarId": 10310,
+            "hierarchyLevel": 0
+        },
+        "project": {
+            "self": "https://testing-jira.atlassian.net/rest/api/2/project/10021",
+            "id": "10021",
+            "key": "ROC",
+            "name": "ResponseOps Cases",
+            "projectTypeKey": "software",
+            "simplified": false
+        },
+        "created": "2022-08-02T16:52:20.554+0300",
+        "priority": {
+            "name": "Medium",
+            "id": "3"
+        },
+        "labels": ["kibanaTag"],
+        "updated": "2022-08-02T16:52:20.554+0300",
+        "status": {
+            "self": "https://testing-jira.atlassian.net/rest/api/2/status/10003",
+            "description": "",
+            "name": "To Do",
+            "id": "10003",
+            "statusCategory": {
+                "self": "https://testing-jira.atlassian.net/rest/api/2/statuscategory/2",
+                "id": 2,
+                "key": "new",
+                "colorName": "blue-gray",
+                "name": "To Do"
+            }
+        },
+        "description": "Kibana Description",
+        "summary": "Kibana Title",
+        "creator": {
+            "self": "https://testing-jira.atlassian.net/rest/api/2/user?accountId=12345",
+            "accountId": "12345",
+            "emailAddress": "test-user@elastic.co",
+            "displayName": "MLR-QA",
+            "active": true,
+            "timeZone": "Europe/Athens",
+            "accountType": "atlassian"
+        },
+        "reporter": {
+            "self": "https://testing-jira.atlassian.net/rest/api/2/user?accountId=12345",
+            "accountId": "12345",
+            "emailAddress": "test-user@elastic.co",
+            "displayName": "MLR-QA",
+            "active": true,
+            "timeZone": "Europe/Athens",
+            "accountType": "atlassian"
+        },
+        "comment": {
+            "comments": [],
+            "self": "https://testing-jira.atlassian.net/rest/api/2/issue/71964/comment",
+            "maxResults": 0,
+            "total": 0,
+            "startAt": 0
+        }
+    }
+}
+--
+
+To make the Get Case URL, we need `/rest/api/2/issue/{issueIdOrKey}`. We will fill in the value with the issue ID, which we stored in the last step as *Create Case Response - Case ID Key*. Using the variable selector on the Get Case URL input, we can see the issue ID is stored as a Mustache value `{{{external.system.id}}}`. So our value for *Get Case URL* will be `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}`.
+
+In the response JSON we can see the title of the case is "ROC-538". The key for this value is `key` so we enter `key` as the *Get Case Response External Title Key* value.
+
+We also need the *External Case View URL*. https://support.atlassian.com/jira-software-cloud/docs/link-an-issue/[{jira}'s documentation] instructs you to get the link from the issue itself. The format for this link looks like `https://<user’s subdomain>.atlassian.net/browse/<issueKey>`. We mapped `key` to the *Get Case Response External Title Key* and using the variable selector on the *External Case View URL* input, we can see the issue key is stored as a Mustache value `{{{external.system.title}}}`. Using this, the value for *External Case View URL* is `https://testing-jira.atlassian.net/browse/{{{external.system.title}}}`.
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-step3.gif[{webhook-cm} connector Step 3, {jira} example]
+
+[float]
+====  Step 4 - Comments and updates
+
+During this step, we need to set the REST API data for updates and comments. Let's look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-put[Edit issue documentation].
+
+{jira} update issue request method: `PUT`
+
+{jira} update issue request URL: `/rest/api/2/issue/{issueIdOrKey}`
+
+{jira} update issue request body:
+[source,json]
+--
+{
+    "fields": {
+        "summary": "Main order flow broken",
+        "description": "Order entry fails when selecting supplier.",
+        "labels": ["bugfix",  "blitz_test"],
+        "project":{"key":"PROJ-123"},
+        "issuetype":{"id":"10000"}
+    }
+}
+--
+
+In the screen capture below, on Step 4 we enter `PUT` as the *Update Case Method* and `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}` as the **Update Case Url** using the variable selector to insert the `{{{external.system.id}}}`. Just like the create case JSON, have entered the {jira} request JSON as the *Update Case Object*, updating the project key to "ROC" and the issuetype ID to "10024". We then use the Case variable selector to enter where we will map the Kibana case title, Kibana case description, and Kibana case tags.
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-step4a.gif[{webhook-cm} connector Step 4 Update, {jira} example]
+
+Lastly we will look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post[Add comment documentation] to fill out the optional comment REST fields.
+
+{jira} create comment request method: `POST`
+
+{jira} create comment request URL: `/rest/api/2/issue/{issueIdOrKey}/comment`
+
+{jira} create comment request body:
+[source,json]
+--
+{
+    "body": "Lorem ipsum dolor sit amet."
+}
+--
+
+In the following screen capture, we enter `POST` as the *Create Comment Method* and `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment` as the **Create Comment Url** using the variable selector to insert the `{{{external.system.id}}}`. We enter the {jira} request JSON as the *Create Comment Object*, using the case variable selector to enter where we will map the case comment.
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-step4b.gif[{webhook-cm} connector Step 4 Comments, {jira} example]
+
+[float]
+[[cases-webhook-example-implementation]]
+=== Implement connector in Kibana Cases
+Let's take a look at how our new {webhook-cm} connector works within the case workflow.
+
+[float]
+====  Create a case
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-create.gif[{webhook-cm} connector Create, {jira} example]
+
+[float]
+====  Update and comment on a case
+[role="screenshot"]
+image::management/connectors/images/cases-webhook-update.gif[{webhook-cm} connector Update, {jira} example]
+////

docs/management/connectors/index.asciidoc

@@ -11,5 +11,6 @@ include::action-types/servicenow-itom.asciidoc[leveloffset=+1]
 include::action-types/swimlane.asciidoc[]
 include::action-types/slack.asciidoc[]
 include::action-types/webhook.asciidoc[]
+include::action-types/cases-webhook.asciidoc[leveloffset=+1]
 include::action-types/xmatters.asciidoc[]
 include::pre-configured-connectors.asciidoc[]