[SIEM] [Docs] Cases API (#761) (#977)

* intial case api docs * starts updating the api * updates patch comments * api updates * starts conf api * more conf api stuff * minor fixes * more updates * proofing * typo * formatting * gets rid of me * adds delete all comments method * corrections after feedback * corrections 2 * corrections continued * cmore corrections * and more corrections * even more * rebase * adds reporters to find * corrections * corrections II * connector corrections * final corrections
elastic · Apr 3, 2020 · 964419c · 964419c
1 parent c620169
commit 964419c
Show file tree

Hide file tree

Showing 24 changed files with 2,036 additions and 0 deletions.
diff --git a/docs/en/siem/case-api-update-connector.asciidoc b/docs/en/siem/case-api-update-connector.asciidoc
@@ -0,0 +1,83 @@
+[[case-api-update-connector]]
+=== Update case configurations
+
+Updates the connector's case closure settings.
+
+Connectors are used to interface with external systems. You can only call this
+method after you have created a connector (see <<register-connector>>). After a
+connector has been created and assigned, call <<cases-actions-api-execute>> to
+send cases to the external system.
+
+==== Request URL
+
+`PATCH <kibana host>/<port>/api/cases/configure`
+
+==== Request body
+
+A JSON object with these fields:
+
+|==============================================
+|Name |Type |Description |Required
+
+|`connector_id` |String |The ID of the connector you want to use for sending
+cases to external systems. |No
+|`connector_name` |String |The connector name. |No
+|`closure_type` |String a|Determines whether a case is automatically closed in
+the {siem-app} when it is pushed to {sn}. Valid values are:
+
+* `close-by-pushing`: {siem-app} cases are automatically closed when they
+are pushed to {sn}.
+* `close-by-user`: {siem-app} cases are not automatically closed.
+
+|No
+
+|`version` |String |The connector version. |Yes
+|==============================================
+
+NOTE: Call <<cases-get-connector>> to retrieve the version value, and
+<<cases-api-find-connectors>> to retrieve connector IDs.
+
+===== Example request
+
+Changes the connector's case closure option: 
+
+[source,sh]
+--------------------------------------------------
+PATCH api/cases/configure
+{
+  "connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
+  "closure_type": "close-by-pushing",
+  "version": "WzIwMiwxXQ=="
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response code
+
+`200`:: 
+   Indicates a successful call.
+
+===== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
+  "closure_type": "close-by-pushing",
+  "connector_name": "ServiceNow",
+  "created_at": "2020-03-30T13:31:38.083Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Ms Admin",
+    "username": "admin"
+  },
+  "updated_at": "2020-03-31T06:21:35.759Z",
+  "updated_by": {
+    "email": "[email protected]",
+    "full_name": "Ms Admin",
+    "username": "admin"
+  },
+  "version": "WzIwMywxXQ=="
+}
+--------------------------------------------------
+
diff --git a/docs/en/siem/cases-api-add-comment.asciidoc b/docs/en/siem/cases-api-add-comment.asciidoc
@@ -0,0 +1,98 @@
+[[cases-api-add-comment]]
+=== Add comment
+
+Adds a comment to an existing case.
+
+==== Request URL
+
+`POST <kibana host>/<port>/api/cases/<case ID>/comments`
+
+===== URL parts
+
+The URL must include the `case ID` of the case to which you are adding a 
+comment. Call <<cases-api-find-cases>> to retrieve case IDs.
+
+==== Request body
+
+A JSON object with a `comment` field:
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`comment` |String |The case's new comment. |Yes
+|==============================================
+
+===== Example request
+
+Adds a comment to case ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`:
+
+[source,sh]
+--------------------------------------------------
+POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
+{
+  "comment": "That is nothing - Ethan Hunt answered a targeted social
+  media campaign promoting phishy pension schemes to IMF operatives."
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response code
+
+`200`:: 
+   Indicates a successful call.
+
+==== Response payload
+
+The updated JSON case object with the new comment, the user who created the
+comment, and the comment's ID, version, and creation time.
+
+===== Example response
+
+[source,json]
+--------------------------------------------------
+
+  "id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
+  "version": "WzIwNDMyLDFd",
+  "comments": [
+    {
+      "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
+      "version": "WzIwNDMxLDFd",
+      "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
+      "created_at": "2020-04-02T15:28:03.034Z",
+      "created_by": {
+        "email": "[email protected]",
+        "full_name": "Ms Moneypenny",
+        "username": "moneypenny"
+      },
+      "pushed_at": null,
+      "pushed_by": null,
+      "updated_at": null,
+      "updated_by": null
+    }
+  ],
+  "totalComment": 0,
+  "title": "This case will self-destruct in 5 seconds",
+  "tags": [
+    "phishing",
+    "social engineering"
+  ],
+  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
+  "closed_at": null,
+  "closed_by": null,
+  "created_at": "2020-04-02T15:25:19.088Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Alan Hunley",
+    "username": "ahunley"
+  },
+  "external_service": null,
+  "status": "open",
+  "updated_at": "2020-04-02T15:28:03.034Z",
+  "updated_by": {
+    "email": "[email protected]",
+    "full_name": "Ms Moneypenny",
+    "username": "moneypenny"
+  }
+}
+--------------------------------------------------
diff --git a/docs/en/siem/cases-api-assign-connector.asciidoc b/docs/en/siem/cases-api-assign-connector.asciidoc
@@ -0,0 +1,72 @@
+[[assign-connector]]
+=== Set connector
+
+Sets the default connector in the {siem-ui}.
+
+Connectors are used to interface with external systems. You can only call this
+method after you have created a connector (see <<register-connector>>). After a
+connector has been created and assigned, call <<cases-actions-api-execute>> to
+send cases to the external system.
+
+==== Request URL
+
+`POST <kibana host>/<port>/api/cases/configure`
+
+==== Request body
+
+A JSON object with these fields:
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`connector_id` |String |The connector ID. |Yes
+|`connector_name` |String |The connector name. |Yes
+|`closure_type` |String a|Determines whether a case is automatically closed in
+the {siem-app} when it is pushed to {sn}. Valid values are:
+
+* `close-by-pushing`: {siem-app} cases are automatically closed when they
+are pushed to {sn}.
+* `close-by-user`: {siem-app} cases are not automatically closed.
+
+|Yes
+|==============================================
+
+NOTE: Call <<cases-api-find-connectors>> to retrieve connector IDs and names.
+
+==== Example request
+
+[source,sh]
+--------------------------------------------------
+POST api/cases/configure
+{
+  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "closure_type": "close-by-user",
+  "connector_name": "ServiceNow"
+}
+--------------------------------------------------
+
+==== Response code
+
+`200`:: 
+   Indicates a successful call.
+
+==== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "closure_type": "close-by-user",
+  "connector_name": "ServiceNow",
+  "created_at": "2020-03-30T13:31:38.083Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Ms Moneypenny",
+    "username": "moneypenny"
+  },
+  "updated_at": null,
+  "updated_by": null,
+  "version": "WzE3NywxXQ=="
+}
+--------------------------------------------------
diff --git a/docs/en/siem/cases-api-associate-sn.asciidoc b/docs/en/siem/cases-api-associate-sn.asciidoc
@@ -0,0 +1,103 @@
+[[cases-api-associate-sn-incident]]
+=== Add external details to case
+
+Adds the data returned from {sn} to the specified case.
+
+After sending a new or updated case to {sn}, you must associate the returned
+{sn} incident fields with the case in the {siem-app}.
+
+==== Request URL
+
+`POST <kibana host>/<port>/api/cases/<case ID>/_push`
+
+===== URL parts
+
+The URL must include the `case ID` of the case you are updating. Call
+<<cases-api-find-cases>> to retrieve case IDs.
+
+==== Request body
+
+A JSON object with the data returned from {sn}:
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`connector_id` |String |The ID of the connector used to send the case to {sn}.
+|Yes
+|`connector_name` |String |The ID of the connector used to send the case to
+{sn}. |Yes
+|`external_id` |String |The `incidentId` returned when calling
+<<cases-actions-api-execute>>. |Yes
+|`external_title` |String |The `number` returned when calling
+<<cases-actions-api-execute>>. |Yes
+|`external_url` |String |The `url` returned when calling
+<<cases-actions-api-execute>>. |Yes
+|==============================================
+
+===== Example request
+
+[source,sh]
+--------------------------------------------------
+POST api/cases/718265d0-733a-11ea-a0b2-c51ea50a58e2/_push
+
+  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "connector_name": "ServiceNow",
+  "external_id": "74c15d07dbb300106ba884da0b9619a0",
+  "external_title": "INC0010016",
+  "external_url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=74c15d07dbb300106ba884da0b9619a0"
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response code
+
+`200`:: 
+   Indicates a successful call.
+
+==== Response payload
+
+The updated JSON case object.
+
+===== Example response
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "718265d0-733a-11ea-a0b2-c51ea50a58e2",
+  "version": "WzMyNywxXQ==",
+  "comments": [],
+  "totalComment": 0,
+  "closed_at": null,
+  "closed_by": null,
+  "created_at": "2020-03-31T10:29:03.781Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Alan Hunley",
+    "username": "ahunley"
+  },
+  "external_service": {
+    "pushed_at": "2020-03-31T10:56:10.959Z",
+    "pushed_by": {
+      "username": "ahunley",
+      "full_name": "Alan Hunley",
+      "email": "[email protected]"
+    },
+    "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+    "connector_name": "ServiceNow",
+    "external_id": "74c15d07dbb300106ba884da0b9619a0",
+    "external_title": "INC0010016",
+    "external_url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=74c15d07dbb300106ba884da0b9619a0"
+  },
+  "updated_at": "2020-03-31T10:56:10.959Z",
+  "updated_by": {
+    "username": "ahunley",
+    "full_name": "Alan Hunley",
+    "email": "[email protected]"
+  },
+  "title": "This case will self-destruct in 5 seconds",
+  "tags": [],
+  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
+  "status": "open"
+}
+--------------------------------------------------