diff --git a/docs/en/siem/case-api-update-connector.asciidoc b/docs/en/siem/case-api-update-connector.asciidoc new file mode 100644 index 000000000..39513fa58 --- /dev/null +++ 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 <>). After a +connector has been created and assigned, call <> to +send cases to the external system. + +==== Request URL + +`PATCH //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 <> to retrieve the version value, and +<> 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": "admin@hms.gov.uk", + "full_name": "Ms Admin", + "username": "admin" + }, + "updated_at": "2020-03-31T06:21:35.759Z", + "updated_by": { + "email": "admin@hms.gov.uk", + "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 new file mode 100644 index 000000000..03477a034 --- /dev/null +++ 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 //api/cases//comments` + +===== URL parts + +The URL must include the `case ID` of the case to which you are adding a +comment. Call <> 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": "moneypenny@hms.gov.uk", + "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": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, + "status": "open", + "updated_at": "2020-04-02T15:28:03.034Z", + "updated_by": { + "email": "moneypenny@hms.gov.uk", + "full_name": "Ms Moneypenny", + "username": "moneypenny" + } +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-assign-connector.asciidoc b/docs/en/siem/cases-api-assign-connector.asciidoc new file mode 100644 index 000000000..5ceb5a24e --- /dev/null +++ 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 <>). After a +connector has been created and assigned, call <> to +send cases to the external system. + +==== Request URL + +`POST //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 <> 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": "moneypenny@hms.gov.uk", + "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 new file mode 100644 index 000000000..c71fb2932 --- /dev/null +++ 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 //api/cases//_push` + +===== URL parts + +The URL must include the `case ID` of the case you are updating. Call +<> 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 +<>. |Yes +|`external_title` |String |The `number` returned when calling +<>. |Yes +|`external_url` |String |The `url` returned when calling +<>. |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": "ahunley@imf.usa.gov", + "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": "ahunley@imf.usa.gov" + }, + "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": "ahunley@imf.usa.gov" + }, + "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" +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-create.asciidoc b/docs/en/siem/cases-api-create.asciidoc new file mode 100644 index 000000000..d714f4b15 --- /dev/null +++ b/docs/en/siem/cases-api-create.asciidoc @@ -0,0 +1,82 @@ +[[cases-api-create]] +=== Create case + +Creates a new case. + +==== Request URL + +`POST //api/cases` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`title` |String |The case's title. |Yes +|`description` |String |The case's description. |Yes +|`tags` |String[] |String array containing words and phrases that help +categorize cases. |Yes, can be an empty array. +|============================================== + +===== Example request + +[source,sh] +-------------------------------------------------- +POST api/cases +{ + "description": "James Bond clicked on a highly suspicious email + banner advertising cheap holidays for underpaid civil servants.", + "title": "This case will self-destruct in 5 seconds", + "tags": [ + "phishing", + "social engineering" + ] +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object that includes the user who created the case and the case's ID, +version, and creation time. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "Wzc0LDFd", + "comments": [], + "totalComment": 0, + "closed_at": null, + "closed_by": null, + "created_at": "2020-03-29T11:30:02.658Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, <1> + "updated_at": null, + "updated_by": null, + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.", + "title": "This case will self-destruct in 5 seconds", + "status": "open", + "tags": [ + "phishing", + "social engineering" + ] +} +-------------------------------------------------- + +<1> The `external_service` object stores information when the case is pushed to +external systems. For more information, see <>. diff --git a/docs/en/siem/cases-api-delete-all-comments.asciidoc b/docs/en/siem/cases-api-delete-all-comments.asciidoc new file mode 100644 index 000000000..855e10a98 --- /dev/null +++ b/docs/en/siem/cases-api-delete-all-comments.asciidoc @@ -0,0 +1,28 @@ +[[cases-api-delete-all-comments]] +=== Delete all comments + +Deletes all comments from the specified case. + +==== Request URL + +`DELETE //api/cases//comments` + +===== URL parts + +The URL must include the `case ID` of the comment’s associated case (call +<> to retrieve case IDs). + +===== Example request + +Deletes all comments from case ID `9c235210-6834-11ea-a78c-6ffb38a34414`: + +[source,console] +-------------------------------------------------- +DELETE api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments +-------------------------------------------------- +// KIBANA + +==== Response code + +`204`:: + Indicates a successful call. \ No newline at end of file diff --git a/docs/en/siem/cases-api-delete-case.asciidoc b/docs/en/siem/cases-api-delete-case.asciidoc new file mode 100644 index 000000000..0ef1da7ae --- /dev/null +++ b/docs/en/siem/cases-api-delete-case.asciidoc @@ -0,0 +1,33 @@ +[[cases-api-delete-case]] +=== Delete case + +Deletes the specified cases and all associated comments. + +==== Request URL + +`DELETE //api/cases?ids=["",""]` + +===== URL parts + +The URL must include the case IDs of the cases you are deleting. Call +<> to retrieve case IDs. + +NOTE: All non-ascii characters must be encoded. + +===== Example request + +Deletes cases with these IDs: + +* `2e3a54f0-6754-11ea-a1c2-e3a8bc9f7aca` +* `40b9a450-66a0-11ea-be1b-2bd3fef48984` + +[source,console] +-------------------------------------------------- +DELETE api/cases?ids=%5B%222e3a54f0-6754-11ea-a1c2-e3a8bc9f7aca%22%2C%2240b9a450-66a0-11ea-be1b-2bd3fef48984%22%5D +-------------------------------------------------- +// KIBANA + +==== Response code + +`204`:: + Indicates a successful call. \ No newline at end of file diff --git a/docs/en/siem/cases-api-delete-comment.asciidoc b/docs/en/siem/cases-api-delete-comment.asciidoc new file mode 100644 index 000000000..821fe78bc --- /dev/null +++ b/docs/en/siem/cases-api-delete-comment.asciidoc @@ -0,0 +1,33 @@ +[[cases-api-delete-comment]] +=== Delete comment + +Deletes the specified comment. + +==== Request URL + +`DELETE //api/cases//comments/` + +===== URL parts + +The URL must include: + +* the `case ID` of the comment’s associated case (call <> +to retrieve case IDs). +* the `comment ID` of the comment you are retrieving (call +<> to retrieve comment IDs). + +===== Example request + +Deletes comment ID `71ec1870-725b-11ea-a0b2-c51ea50a58e2` from case ID +`a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +DELETE api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments/71ec1870-725b-11ea-a0b2-c51ea50a58e2 +-------------------------------------------------- +// KIBANA + +==== Response code + +`204`:: + Indicates a successful call. \ No newline at end of file diff --git a/docs/en/siem/cases-api-find-cases.asciidoc b/docs/en/siem/cases-api-find-cases.asciidoc new file mode 100644 index 000000000..8f525ce1f --- /dev/null +++ b/docs/en/siem/cases-api-find-cases.asciidoc @@ -0,0 +1,131 @@ +[[cases-api-find-cases]] +=== Find cases + +Retrieves a paginated subset of cases. By default, the first page is returned +with 20 results per page. + +NOTE: Cases are saved objects. See +{kibana-ref}/saved-objects-api-find.html[Find objects API] for more query +parameters. + +==== Request URL + +`GET //api/cases/_find` + +===== URL query parameters + +All parameters are optional: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|`page` |Integer |The page number to return. + +|`perPage` |Integer |The number of rules to return per page. + +|`sortField` |String |Determines which field is used to sort the results, +`createdAt` or `updatedAt`. + +|`sortOrder` |String |Determines the sort order, which can be `desc` or `asc`. + +|`status` |String |Filters the returned cases by state, which can be `open` or +`closed`. + +|`tags` |String |Filters the returned cases by tags. + +|`reporters` |String |Filters the returned cases by the reporter's `username`. + +|============================================== + +NOTE: Even though the JSON case object uses `created_at` and `updated_at` +fields, you must use `createdAt` and `updatedAt` fields in the URL +query. + +===== Example request + +Retrieves the first five cases with the `phishing` tag, in ascending order by +last update time. + +[source,sh] +-------------------------------------------------- +GET api/cases/_find?page=1&perPage=5&sortField=updatedAt&sortOrder=asc&tags=phishing +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing the retrieved cases. + +===== Response example + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "per_page": 5, + "total": 2, + "cases": [ + { + "id": "abed3a70-71bd-11ea-a0b2-c51ea50a58e2", + "version": "WzExMCwxXQ==", + "comments": [], + "totalComment": 0, + "closed_at": null, + "closed_by": null, + "created_at": "2020-03-29T13:03:23.533Z", + "created_by": { + "email": "rhustler@aol.com", + "full_name": "Rat Hustler", + "username": "rhustler" + }, + "external_service": null, + "updated_at": null, + "updated_by": null, + "title": "The Long Game", + "tags": [ + "windows", + "phishing" + ], + "description": "Windows 95", + "status": "open" + }, + { + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "Wzk4LDFd", + "comments": [], + "totalComment": 1, + "closed_at": null, + "closed_by": null, + "created_at": "2020-03-29T11:30:02.658Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, + "updated_at": "2020-03-29T12:01:50.244Z", + "updated_by": { + "full_name": "Classified", + "email": "classified@hms.oo.gov.uk", + "username": "M" + }, + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active!", + "title": "This case will self-destruct in 5 seconds", + "status": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ] + } + ], + "count_open_cases": 2, + "count_closed_cases": 0 +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-find-connectors.asciidoc b/docs/en/siem/cases-api-find-connectors.asciidoc new file mode 100644 index 000000000..7ce9c085f --- /dev/null +++ b/docs/en/siem/cases-api-find-connectors.asciidoc @@ -0,0 +1,97 @@ +[[cases-api-find-connectors]] +=== Find connectors + +Retrieves a paginated subset of all {sn} connectors. + +NOTE: Only {sn} connectors are returned. For more information on connectors, +see <>. + +==== Request URL + +`GET //api/cases/configure/connectors/_find` + +===== Example request + +[source,sh] +-------------------------------------------------- +GET api/cases/configure/connectors/_find +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object describing the connectors and their settings. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "perPage": 20, + "total": 2, + "data": [ + { + "id": "61787f53-4eee-4741-8df6-8fe84fa616f7", + "actionTypeId": ".servicenow", + "name": "ServiceNow", + "config": { + "casesConfiguration": { + "mapping": [ + { + "actionType": "overwrite", + "source": "title", + "target": "short_description" + }, + { + "actionType": "append", + "source": "description", + "target": "description" + }, + { + "actionType": "append", + "source": "comments", + "target": "comments" + } + ] + }, + "apiUrl": "https://dev78437.service-now.com" + }, + "referencedByCount": 0 + }, + { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "actionTypeId": ".servicenow", + "name": "Defector", + "config": { + "apiUrl": "https://dev87359.service-now.com", + "casesConfiguration": { + "mapping": [ + { + "source": "title", + "target": "short_description", + "actionType": "append" + }, + { + "source": "description", + "target": "description", + "actionType": "append" + }, + { + "source": "comments", + "target": "comments", + "actionType": "append" + } + ] + } + }, + "referencedByCount": 0 + } + ] +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-case-activity.asciidoc b/docs/en/siem/cases-api-get-case-activity.asciidoc new file mode 100644 index 000000000..386a8104d --- /dev/null +++ b/docs/en/siem/cases-api-get-case-activity.asciidoc @@ -0,0 +1,111 @@ +[[cases-api-get-case-activity]] +=== Get all case activity + +Returns all user activity for the specified case. + +==== Request URL + +`GET //api/cases//user_actions` + +===== URL parts + +The URL must include the `case ID` of the case for which you are retrieving +activity. Call <> to retrieve case IDs. + +===== Example request + +Gets all comments for case ID `a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/user_actions +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON array containing all user activity for the specified case. + +===== Response example + +[source,json] +-------------------------------------------------- +[ + { + "action_field": [ + "description", + "status", + "tags", + "title" + ], + "action": "create", + "action_at": "2020-04-02T15:25:19.088Z", + "action_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "new_value": "{\"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.\"}", + "old_value": null, + "action_id": "29ce6370-74f6-11ea-b83a-553aecdb28b6", + "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6", + "comment_id": null + }, + { + "action_field": [ + "comment" + ], + "action": "create", + "action_at": "2020-04-02T15:28:03.034Z", + "action_by": { + "email": "moneypenny@hms.gov.uk", + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "new_value": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "old_value": null, + "action_id": "8b0d6870-74f6-11ea-b83a-553aecdb28b6", + "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6", + "comment_id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6" + }, + { + "action_field": [ + "comment" + ], + "action": "update", + "action_at": "2020-04-02T15:34:01.118Z", + "action_by": { + "email": "jbond@hms.gov.uk", + "full_name": "James Bond", + "username": "_007" + }, + "new_value": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives. Even worse, he likes baked beans.", + "old_value": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "action_id": "60dafd50-74f7-11ea-b83a-553aecdb28b6", + "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6", + "comment_id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6" + }, + { + "action_field": [ + "comment" + ], + "action": "create", + "action_at": "2020-04-02T17:48:16.293Z", + "action_by": { + "email": "classified@hms.oo.gov.uk", + "full_name": "Classified", + "username": "M" + }, + "new_value": "I'm on it.", + "old_value": null, + "action_id": "223f7bd0-750a-11ea-b83a-553aecdb28b6", + "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6", + "comment_id": "21a844e0-750a-11ea-b83a-553aecdb28b6" + } +] +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-case-comments.asciidoc b/docs/en/siem/cases-api-get-case-comments.asciidoc new file mode 100644 index 000000000..b4c9e9627 --- /dev/null +++ b/docs/en/siem/cases-api-get-case-comments.asciidoc @@ -0,0 +1,74 @@ +[[cases-api-get-all-case-comments]] +=== Get all case comments + +Returns all comments for the specified case. + +==== Request URL + +`GET //api/cases//comments` + +===== URL parts + +The URL must include the `case ID` of the case for which you are retrieving +comments. Call <> to retrieve case IDs. + +===== Example request + +Gets all comments for case ID `a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON array containing all comments for the specified case. + +===== Response example + +[source,json] +-------------------------------------------------- +[ + { + "id": "c6f0dca0-71b3-11ea-a0b2-c51ea50a58e2", + "version": "WzEwNSwxXQ==", + "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives. Even worse, he likes baked beans.", + "created_at": "2020-03-29T11:52:33.889Z", + "created_by": { + "email": "moneypenny@hms.gov.uk", + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "pushed_at": null, + "pushed_by": null, + "updated_at": "2020-03-29T12:14:32.997Z", + "updated_by": { + "email": "jbond@hms.gov.uk", + "full_name": "James Bond", + "username": "_007" + } + }, + { + "id": "71ec1870-725b-11ea-a0b2-c51ea50a58e2", + "version": "WzEyOCwxXQ==", + "comment": "Start operation bubblegum immediately! And chew fast!", + "created_at": "2020-03-30T07:52:46.702Z", + "created_by": { + "email": "classified@hms.oo.gov.uk", + "full_name": "Classified", + "username": "M" + }, + "pushed_at": null, + "pushed_by": null, + "updated_at": null, + "updated_by": null + } +] +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-case.asciidoc b/docs/en/siem/cases-api-get-case.asciidoc new file mode 100644 index 000000000..2fa4d88c9 --- /dev/null +++ b/docs/en/siem/cases-api-get-case.asciidoc @@ -0,0 +1,77 @@ +[[cases-api-get-case]] +=== Get case + +Returns the specified case. + +==== Request URL + +`GET //api/cases/` + +===== URL parts + +The URL must include the `case ID` of the case you are retrieving. Call +<> to retrieve case IDs. + +===== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`includeComments` |Boolean |Determines whether case comments are +returned. |No, defaults to `true`. +|============================================== + +===== Example request + +Returns case ID `a18b38a0-71b0-11ea-a0b2-c51ea50a58e2` without comments: + +[source,sh] +-------------------------------------------------- +GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2?includeComments=false +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The requested case JSON object. + +===== Response example + +[source,json] +-------------------------------------------------- +{ + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "Wzk4LDFd", + "comments": [], + "totalComment": 0, + "closed_at": null, + "closed_by": null, + "created_at": "2020-03-29T11:30:02.658Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, + "updated_at": "2020-03-29T12:01:50.244Z", + "updated_by": { + "full_name": "Classified", + "email": "classified@hms.oo.gov.uk", + "username": "M" + }, + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active!", + "title": "This case will self-destruct in 5 seconds", + "status": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ] +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-comment.asciidoc b/docs/en/siem/cases-api-get-comment.asciidoc new file mode 100644 index 000000000..320c00ada --- /dev/null +++ b/docs/en/siem/cases-api-get-comment.asciidoc @@ -0,0 +1,58 @@ +[[cases-api-get-comment]] +=== Get comment + +Gets the specified comment. + +==== Request URL + +`GET //api/cases//comments/` + +===== URL parts + +The URL must include: + +* the `case ID` of the comment’s associated case (call <> +to retrieve case IDs). +* the `comment ID` of the comment you are retrieving (call +<> to retrieve comment IDs). + +===== Example request + +Retrieves comment ID `71ec1870-725b-11ea-a0b2-c51ea50a58e2` from case ID +`a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +GET api/cases/a18b38a0-71b0-11ea-a0b2-c51ea50a58e2/comments/71ec1870-725b-11ea-a0b2-c51ea50a58e2 +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The requested comment JSON object. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "id": "71ec1870-725b-11ea-a0b2-c51ea50a58e2", + "version": "WzEyOCwxXQ==", + "comment": "Start operation bubblegum immediately! And chew fast!", + "created_at": "2020-03-30T07:52:46.702Z", + "created_by": { + "email": "classified@hms.oo.gov.uk", + "full_name": "Classified", + "username": "M" + }, + "pushed_at": null, + "pushed_by": null, + "updated_at": null, + "updated_by": null +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-connector.asciidoc b/docs/en/siem/cases-api-get-connector.asciidoc new file mode 100644 index 000000000..986dd235a --- /dev/null +++ b/docs/en/siem/cases-api-get-connector.asciidoc @@ -0,0 +1,43 @@ +[[cases-get-connector]] +=== Get current connector + +Retrieves the currently used connector. + +NOTE: For more information on connectors, see <>. + +==== Request URL + +`GET //api/cases/configure` + +===== Example request + +[source,sh] +-------------------------------------------------- +GET api/cases/configure +-------------------------------------------------- +// KIBANA + +==== 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": "admin@hms.gov.uk", + "full_name": "Mr Admin", + "username": "admin" + }, + "updated_at": null, + "updated_by": null, + "version": "WzE3NywxXQ==" +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-reporters.asciidoc b/docs/en/siem/cases-api-get-reporters.asciidoc new file mode 100644 index 000000000..bfea63e45 --- /dev/null +++ b/docs/en/siem/cases-api-get-reporters.asciidoc @@ -0,0 +1,39 @@ +[[cases-api-get-reporters]] +=== Get reporters + +Returns all case reporters (users who opened cases). + +==== Request URL + +`GET //api/cases/reporters` + +===== Example request + +[source,sh] +-------------------------------------------------- +GET api/cases/reporters +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +===== Example response + +[source,json] +-------------------------------------------------- +[ + { + "full_name": "Alan Hunley", + "email": "ahunley@imf.usa.gov", + "username": "ahunley" + }, + { + "full_name": "Rat Hustler", + "email": "jrhustler@aol.com", + "username": "rhustler" + } +] +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-status.asciidoc b/docs/en/siem/cases-api-get-status.asciidoc new file mode 100644 index 000000000..b64e4ee64 --- /dev/null +++ b/docs/en/siem/cases-api-get-status.asciidoc @@ -0,0 +1,31 @@ +[[cases-api-get-status]] +=== Get status + +Returns the number of open and closed cases. + +==== Request URL + +`GET //api/cases/status` + +===== Example request + +[source,sh] +-------------------------------------------------- +GET api/cases/status +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "count_open_cases": 27, + "count_closed_cases": 1198 +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-tags.asciidoc b/docs/en/siem/cases-api-get-tags.asciidoc new file mode 100644 index 000000000..4d31652e5 --- /dev/null +++ b/docs/en/siem/cases-api-get-tags.asciidoc @@ -0,0 +1,35 @@ +[[cases-api-get-tag]] +=== Get tags + +Aggregates and returns all unique tags from all cases. + +==== Request URL + +`GET //api/cases/tags` + +===== Example request + +Gets all tags for all cases: + +[source,sh] +-------------------------------------------------- +GET api/cases/tags +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +===== Example response + +[source,json] +-------------------------------------------------- +[ + "windows", + "phishing", + "social engineering", + "bubblegum" +] +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-update-comment.asciidoc b/docs/en/siem/cases-api-update-comment.asciidoc new file mode 100644 index 000000000..53cf8a16c --- /dev/null +++ b/docs/en/siem/cases-api-update-comment.asciidoc @@ -0,0 +1,111 @@ +[[cases-api-update-comment]] +=== Update comment + +Updates an existing comment. + +==== Request URL + +`PATCH //api/cases//comments` + +===== URL parts + +The URL must include the `case ID` of the comment's associated case. Call +<> to retrieve case IDs. + +==== Request body + +A JSON object with the updated comment: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`comment` |String |The updated comment. |Yes +|`id` |String |The comment's ID. |Yes +|`version` |String |The current comment version. |Yes +|============================================== + +NOTE: Call <> to retrieve comment IDs and +version values. + +===== Example request + +Updates comment ID `8af6ac20-74f6-11ea-b83a-553aecdb28b6` (associated with case +ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`): + +[source,sh] +-------------------------------------------------- +PATCH api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments +{ + "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6", + "comment": "That is nothing - Ethan Hunt answered a targeted social + media campaign promoting phishy pension schemes to IMF operatives. + Even worse, he likes baked beans.", + "version": "Wzk1LDFd" +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The updated JSON case object with the updated comment, the user who updated the +comment, and the comment's ID, version, and update time. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6", + "version": "WzIwNjM2LDFd", + "comments": [ + { + "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6", + "version": "WzIwNjM3LDFd", + "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": "moneypenny@hms.gov.uk", + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "pushed_at": null, + "pushed_by": null, + "updated_at": "2020-04-02T15:34:01.118Z", + "updated_by": { + "email": "jbond@hms.gov.uk", + "full_name": "James Bond", + "username": "_007" + } + } + ], + "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": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, + "status": "open", + "updated_at": "2020-04-02T15:34:01.118Z", + "updated_by": { + "email": "jbond@hms.gov.uk", + "full_name": "James Bond", + "username": "_007" + } +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api-update.asciidoc b/docs/en/siem/cases-api-update.asciidoc new file mode 100644 index 000000000..39b0d0500 --- /dev/null +++ b/docs/en/siem/cases-api-update.asciidoc @@ -0,0 +1,112 @@ +[[cases-api-update]] +=== Update case + +Updates existing cases. + +==== Request URL + +`PATCH //api/cases` + +==== Request body + +A JSON array containing one or more case objects with updated field values: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`cases` |<> |Array containing one or more case objects. |Yes +|============================================== + +[[update-cases-schema]] +===== `cases` schema +|============================================== +|Name |Type |Description |Required + +|`id` |String |The ID of the case being updated. |Yes +|`title` |String |The updated case title. |No +|`description` |String |The updated case description. |No +|`status` |String a|The updated case status, which can be: + +* `open` +* `closed` + +|No +|`tags` |String[] |The updated case tags. |No +|`version` |String |The current case version (returned when calling +<> or <>). |Yes +|============================================== + +===== Example request + +Updates the `description` and `tags` fields of case ID +`a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +PATCH api/cases +{ + "cases": [ + { + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "description": "James Bond clicked on a highly suspicious email + banner advertising cheap holidays for underpaid civil servants. + Operation bubblegum is active. Repeat - operation bubblegum is + now active!", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ], + "version": "WzIzLDFd" + } + ] +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The updated case with a new `version` value. + +===== Example response + +[source,json] +-------------------------------------------------- +[ + { + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "Wzk4LDFd", + "comments": [], + "totalComment": 0, + "closed_at": null, + "closed_by": null, + "created_at": "2020-03-29T11:30:02.658Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "external_service": null, + "updated_at": "2020-03-29T12:01:50.244Z", + "updated_by": { + "email": "classified@hms.oo.gov.uk", + "full_name": "Classified", + "username": "M" + }, + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active!", + "title": "This case will self-destruct in 5 seconds", + "status": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ] + } +] +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-api.asciidoc b/docs/en/siem/cases-api.asciidoc new file mode 100644 index 000000000..fbaa485a6 --- /dev/null +++ b/docs/en/siem/cases-api.asciidoc @@ -0,0 +1,47 @@ +[[cases-api-overview]] +[role="xpack"] +== Cases API + +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 +`//api/cases`, where `` is the host name and +`` is the port number of your Kibana instance. + +* Actions API: Used to send cases to external systems. The API endpoint +is `//api/actions`. <> +describes how to set up integrations with third-party systems, and +<> describes how to push {siem-app} cases to third +party systems (currently, ServiceNow). + +NOTE: In dev mode, the Kibana server runs behind a proxy which adds a random +path component to its URL. +{kibana-ref}/development-basepath.html[Considerations for basePath] describes +how to work with and disable the random path component. + +[float] +=== Authentication + +Token-based authentication, using the same username and password used to log in +to the Kibana UI, is required to access the API. + +[float] +=== API calls + +All calls to the API are stateless. Each call must include all the information +{siem-soln} needs to perform the request. + +All requests must contain these headers: + +* `kbn-xsrf: `, where `` can be any alphanumeric string (for +example, `kbn-xsrf: kibana`) +* `Content-Type: application/json` (when the request contains a JSON payload) + +For example, the following call retrieves the first 20 cases: + +[source,sh] +-------------------------------------------------- +curl -X GET "//api/cases" +-H 'kbn-xsrf: kibana' -u : +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-kbn-actions-api.asciidoc b/docs/en/siem/cases-kbn-actions-api.asciidoc new file mode 100644 index 000000000..ac0b6f4b5 --- /dev/null +++ b/docs/en/siem/cases-kbn-actions-api.asciidoc @@ -0,0 +1,485 @@ +[[cases-actions-api-connectors]] +=== Configure and send cases to external interfaces + +You can create {sn} incidents from {siem-soln} cases. This requires creating +a {sn} connector using the {kib} Actions API. Connectors store the information +required to push cases to {sn} via {sn}'s https://developer.servicenow.com/dev.do#!/reference/api/madrid/rest/c_TableAPI[Table API], such as the {sn} URL, +account credentials, and the field mappings required for representing a +{siem-soln} case as a {sn} incident. + +To send cases to {sn} and keep the {siem-ui} updated: + +. <>: Create the connector. +. <> or <>: If required, configure +connector options. +. [[sn-returned-data]]<>: Send the case to {sn}. You +must store the returned data as it is required for updating the +`external_service` object in the {siem-soln} case. +. [[update-case-sn-data]]<>: Update the +{siem-soln} case with the associated {sn} incident data returned in +<>. +. Repeat <> and <> each +time you open or update a case. + + + +[[register-connector]] +==== Create connector + +Creates a {sn} connector, which can then be used to open {sn} incidents from +{siem-soln} cases. + +===== Request URL + +`POST //api/action` + +===== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`actionTypeId` |String |Must be: `.servicenow`. |Yes +|`config` |<> |Object containing the action's +configuration. |Yes +|`secrets` |Object a|Object containing the {sn} account credentials used +to create and update incidents: + +* `username` (string): The account username. +* `password` (string): The account password. + +|Yes + +|`name` |String |The registered {sn} connector. |Yes +|============================================== + +[[config-schema]] +*`config` schema* + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`casesConfiguration` |Object a|Contains a `mapping` array, which determines how {siem-soln} case fields are mapped to {sn} incident fields: + +* `source` (string): The name of the {siem-soln} case field, which can be +`title`, `description`, or `comments`. +* `target` (string): The name of the mapped {sn} incident field. For example: `short_description`, `description`, and `comments`. +* `actionType` (string): Determines whether {siem-soln} case updates overwrite +or append to the mapped {sn} incident fields. Valid values are `overwrite` and +`append`. + +|Yes + +|`apiUrl` |String |URL of the {sn} instance. |Yes +|============================================== + +===== Example request + +[source,sh] +-------------------------------------------------- +POST api/action +{ + "actionTypeId": ".servicenow", + "config": { + "casesConfiguration": { + "mapping": [ + { + "source": "title", <1> + "target": "short_description", + "actionType": "overwrite" + }, + { + "source": "description", <2> + "target": "description", + "actionType": "overwrite" + }, + { + "source": "comments", <3> + "target": "comments", + "actionType": "append" + } + ] + }, + "apiUrl": "https://dev87359.service-now.com" + }, + "secrets": { + "username": "admin", + "password": "securePassword123!" + }, + "name": "ServiceNow" +} +-------------------------------------------------- +// KIBANA + +<1> {siem-soln} case `title` fields are mapped to {sn} `short_description` +fields. When a {siem-soln} `title` field is updated and sent to {sn}, the {sn} +`short_description` field is overwritten. + +<2> {siem-soln} case `description` fields are mapped to {sn} `description` +fields. When a {siem-soln} `description` field is updated and sent to {sn}, +the {sn} `description` field is overwritten. + +<3> {siem-soln} case `comments` fields are mapped to {sn} `comments` fields. +When a {siem-soln} `comments` field is updated and sent to {sn}, the updated +text is appended to the {sn} `comments` field. + +===== Response code + +`200`:: + Indicates a successful call. + +===== Response payload + +A JSON object with a connector `id` that is required to push cases to {sn}. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "id": "61787f53-4eee-4741-8df6-8fe84fa616f7", + "actionTypeId": ".servicenow", + "name": "ServiceNow", + "config": { + "casesConfiguration": { + "mapping": [ + { + "source": "title", + "target": "short_description", + "actionType": "overwrite" + }, + { + "source": "description", + "target": "description", + "actionType": "overwrite" + }, + { + "source": "comments", + "target": "comments", + "actionType": "append" + } + ] + }, + "apiUrl": "https://dev78437.service-now.com" + } +} +-------------------------------------------------- + +[[update-connector]] +==== Update connector + +Updates a {sn} connector. + +===== Request URL + +`PUT //api/action/` + +===== URL parts + +The URL must include the `connector ID` of the connector you are updating. +Call <> to retrieve connector IDs. + +===== Request body + +A JSON object with the fields you want to update: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`config` |<> |Object containing the action's +configuration. |Yes +|`secrets` |Object a|Object containing the {sn} account credentials used +to create and update incidents: + +* `username` (string): The account username. +* `password` (string): The account password. + +|Yes + +|`name` |String |The registered {sn} connector. |Yes +|============================================== + +[[config-update-schema]] +*`config` schema* + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`casesConfiguration` |Object a|Contains a `mapping` array, which determines how {siem-soln} case fields are mapped to {sn} incident fields: + +* `source` (string): The name of the {siem-soln} case field, which can be +`title`, `description`, or `comments`. +* `target` (string): The name of the mapped {sn} incident field. For example: `short_description`, `description`, and `comments`. +* `actionType` (string): Determines whether {siem-soln} case updates overwrite +or append to the mapped {sn} incident fields. Valid values are `overwrite` and +`append`. + +|Yes + +|`apiUrl` |String |URL of the {sn} instance. |Yes +|============================================== + +===== Example request + +Updates the `description` field mapping of connector ID +`61787f53-4eee-4741-8df6-8fe84fa616f7`: + +[source,sh] +-------------------------------------------------- +PUT api/action/61787f53-4eee-4741-8df6-8fe84fa616f7 +{ + "name": "ServiceNow", + "config": { + "apiUrl": "https://dev78437.service-now.com", + "casesConfiguration": { + "mapping": [ + { + "source": "title", + "target": "short_description", + "actionType": "overwrite" + }, + { + "source": "description", + "target": "description", + "actionType": "append" + }, + { + "source": "comments", + "target": "comments", + "actionType": "append" + } + ] + } + }, + "secrets": { + "username": "admin", + "password": "me4Vered1!" + } +} +-------------------------------------------------- +// KIBANA + +===== Response code + +`200`:: + Indicates a successful call. + +===== Response payload + +The updated JSON connector object. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "id": "61787f53-4eee-4741-8df6-8fe84fa616f7", + "actionTypeId": ".servicenow", + "name": "ServiceNow", + "config": { + "apiUrl": "https://dev78437.service-now.com", + "casesConfiguration": { + "mapping": [ + { + "source": "title", + "target": "short_description", + "actionType": "overwrite" + }, + { + "source": "description", + "target": "description", + "actionType": "append" + }, + { + "source": "comments", + "target": "comments", + "actionType": "append" + } + ] + } + } +} +-------------------------------------------------- + +[[cases-actions-api-execute]] +==== Create or update an external incident + +Creates a new or updates an existing {sn} incident from a {siem-soln} case. + +NOTE: You can only send cases to external system after you have +<> a connector. After you have sent the case to +{sn}, you must call <> to update the +{siem-soln} case with the relevant {sn} incident details. + +===== Request URL + +`POST //api/action//_execute` + +===== URL parts + +The URL must include the the ServiceNow connector ID. Call +<> to retrieve the currently used connector ID, or +<> to retrieve all connectors IDs. + +===== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`params` |<> |Contains the {siem-soln} case details +for which you are opening a {sn} incident. |Yes +|============================================== + +[[case-conf-params]] +*`params` schema* + +|============================================== +|Name |Type |Description |Required + +|`caseId` |String |The case ID. |Yes +|`createdAt` |String |The time the case was created, using ISO 8601 with UTC +notation. For example, `2020-03-31T06:40:21.674Z`. |Yes +|`createdBy` |Object a|The user who created the case: + +* `fullName` (string): The user's full name. +* `username` (string): The user's username. + +|Yes + +|`comments` |Object[] a|Array containing case comments: + +* `commentId` (string, required): The comment ID. +* `comment` (string, required): The comment text. +* `createdAt` (string, required): The time the comment was created, using ISO 8601 with +UTC notation. +* `createdBy` (object, required): The user who created the comment, containing +`fullName` and `username` fields. +* `updatedBy` (object, optional): The user who last updated the comment, +containing `fullName` and `username` fields. + +|No + +|`description` |String |The case description. |No +|`incidentId` |String |The {sn} incident ID. Required when updating an existing +{sn} incident. |No +|`title` |String |The case title. |Yes +|`updatedAt` |String |The time the case was updated, using ISO 8601 with UTC +notation. |No +|`updatedBy` |Object a|The user who last updated the case: + +* `fullName` (string): The user's full name. +* `username` (string): The user's username. + +|No +|============================================== + +NOTE: When updating an existing case, call <> or +<> to retrieve the `incidentId`. In the case JSON +object, the `incidentId` value is stored in the `external_id` field. + +===== Example requests + +Creates a new {sn} incident: + +[source,sh] +-------------------------------------------------- +POST api/action/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute +{ + "params": { + "caseId": "c1472f70-732a-11ea-a0b2-c51ea50a58e2", + "createdAt": "2020-03-31T08:36:45.661Z", + "createdBy": { + "fullName": "Alan Hunley", + "username": "ahunley" + }, + "comments": [ + { + "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2", + "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "createdAt": "2020-03-31T08:37:33.240Z", + "createdBy": { + "fullName": "Ms Moneypenny", + "username": "moneypenny" + } + } + ], + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active.", + "title": "This case will self-destruct in 5 seconds" + } +} +-------------------------------------------------- +// KIBANA + +Updates an existing {sn} incident: + +[source,sh] +-------------------------------------------------- +POST api/action/7349772f-421a-4de3-b8bb-2d9b22ccee30/_execute +{ + "params": { + "caseId": "c1472f70-732a-11ea-a0b2-c51ea50a58e2", + "createdAt": "2020-03-31T08:36:45.661Z", + "createdBy": { + "fullName": "Alan Hunley", + "username": "ahunley" + }, + "comments": [ + { + "commentId": "8ef6d660-732f-11ea-a0b2-c51ea50a58e2", + "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "createdAt": "2020-03-31T09:11:08.736Z", + "createdBy": { + "fullName": "Ms Moneypenny", + "username": "moneypenny" + } + } + ], + "incidentId": "cc6ef44bdb7300106ba884da0b9619cf", + "title": "This case will self-destruct in 5 seconds" + } +} +-------------------------------------------------- +// KIBANA + +===== Response code + +`200`:: + Indicates a successful call. + +===== Response payload + +A JSON object with the {sn} incident number and link to the {sn} incident. + +IMPORTANT: You need the returned information to associate it with the original +{siem-soln} case. To add the {sn} incident details to the {siem-soln} case, +call <>. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "status": "ok", + "actionId": "61787f53-4eee-4741-8df6-8fe84fa616f7", + "data": { + "number": "INC0010012", + "incidentId": "62dc3c8bdb7300106ba884da0b9619ea", + "pushedDate": "2020-03-31T09:01:33.000Z", + "url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=62dc3c8bdb7300106ba884da0b9619ea", + "comments": [ + { + "commentId": "dda30310-732a-11ea-a0b2-c51ea50a58e2", + "pushedDate": "2020-03-31T09:01:34.000Z" + } + ] + } +} +-------------------------------------------------- \ No newline at end of file diff --git a/docs/en/siem/cases-overview.asciidoc b/docs/en/siem/cases-overview.asciidoc new file mode 100644 index 000000000..aa43789c5 --- /dev/null +++ b/docs/en/siem/cases-overview.asciidoc @@ -0,0 +1,6 @@ +[[cases-overview]] +[role="xpack"] + += Cases + +// Placeholder \ No newline at end of file diff --git a/docs/en/siem/index.asciidoc b/docs/en/siem/index.asciidoc index 5836beb86..1577e7059 100644 --- a/docs/en/siem/index.asciidoc +++ b/docs/en/siem/index.asciidoc @@ -3,6 +3,7 @@ :siem-app: SIEM app :siem-ui: SIEM UI :ml-dir: {docdir}/../stack/ml/ +:sn: ServiceNow = SIEM Guide @@ -59,3 +60,49 @@ include::rule-details/rule-desc-index.asciidoc[] include::tune-rule-signals.asciidoc[] include::prebuilt-rules-changelog.asciidoc[] + +include::cases-overview.asciidoc[] + +include::cases-api.asciidoc[] + +include::cases-api-create.asciidoc[] + +include::cases-api-add-comment.asciidoc[] + +include::cases-api-update.asciidoc[] + +include::cases-api-update-comment.asciidoc[] + +include::cases-api-find-cases.asciidoc[] + +include::cases-api-get-case.asciidoc[] + +include::cases-api-get-case-comments.asciidoc[] + +include::cases-api-get-comment.asciidoc[] + +include::cases-api-get-case-activity.asciidoc[] + +include::cases-api-get-tags.asciidoc[] + +include::cases-api-get-reporters.asciidoc[] + +include::cases-api-get-status.asciidoc[] + +include::cases-api-delete-comment.asciidoc[] + +include::cases-api-delete-all-comments.asciidoc[] + +include::cases-api-delete-case.asciidoc[] + +include::cases-kbn-actions-api.asciidoc[] + +include::cases-api-assign-connector.asciidoc[] + +include::case-api-update-connector.asciidoc[] + +include::cases-api-get-connector.asciidoc[] + +include::cases-api-find-connectors.asciidoc[] + +include::cases-api-associate-sn.asciidoc[]