From 201b352d7f2c2b093091a47020816005011c31f5 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 22 Mar 2022 07:14:52 -0700 Subject: [PATCH] [DOCS] Add create case and update case APIs (#127936) --- docs/api/cases.asciidoc | 7 +- docs/api/cases/cases-api-create.asciidoc | 237 ++++++++++++++++++++ docs/api/cases/cases-api-update.asciidoc | 271 +++++++++++++++++++++++ 3 files changed, 513 insertions(+), 2 deletions(-) create mode 100644 docs/api/cases/cases-api-create.asciidoc create mode 100644 docs/api/cases/cases-api-update.asciidoc diff --git a/docs/api/cases.asciidoc b/docs/api/cases.asciidoc index 5e412c61926db..00fbedc2d1299 100644 --- a/docs/api/cases.asciidoc +++ b/docs/api/cases.asciidoc @@ -5,7 +5,7 @@ You can create, manage, configure, and send cases to external systems with these APIs: * {security-guide}/cases-api-add-comment.html[Add comment] -* {security-guide}/cases-api-create.html[Create case] +* <> * {security-guide}/cases-api-delete-case.html[Delete case] * {security-guide}/cases-api-delete-all-comments.html[Delete all comments] * {security-guide}/cases-api-delete-comment.html[Delete comment] @@ -24,5 +24,8 @@ these APIs: * {security-guide}/cases-api-push.html[Push case] * {security-guide}/assign-connector.html[Set default Elastic Security UI connector] * {security-guide}/case-api-update-connector.html[Update case configurations] -* {security-guide}/cases-api-update.html[Update case] +* <> * {security-guide}/cases-api-update-comment.html[Update comment] + +include::cases/cases-api-create.asciidoc[leveloffset=+1] +include::cases/cases-api-update.asciidoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc new file mode 100644 index 0000000000000..f08b69998321f --- /dev/null +++ b/docs/api/cases/cases-api-create.asciidoc @@ -0,0 +1,237 @@ +[[cases-api-create]] +== Create case API +++++ +Create case +++++ + +Creates a case. + +=== Request + +`POST :/api/cases` + +`POST :/s//api/cases` + +=== Prerequisite + +You must have `all` privileges for the *Cases* feature in the *Management*, +*{observability}*, or *Security* section of the +<>, depending on the +`owner` of the case you're creating. + +=== Path parameters + +``:: +(Optional, string) An identifier for the space. If it is not specified, the +default space is used. + +=== Request body + +`connector`:: +(Required, object) An object that contains the connector configuration. ++ +.Properties of `connector` +[%collapsible%open] +==== +`fields`:: +(Required, object) An object containing the connector fields. ++ +-- +To create a case without a connector, specify `null`. If you want to omit any +individual field, specify `null` as its value. + +For {ibm-r} connectors, specify: + +`issueTypes`::: +(Required, array of numbers) The type of the incident. + +`severityCode`::: +(Required, number) The severity code of the incident. + +For {jira} connectors, specify: + +`issueType`::: +(Required, string) The type of the issue. + +`parent`::: +(Required, string) The key of the parent issue, when the issue type is `Sub-task`. + +`priority`::: +(Required, string) The priority of the issue. + +For {sn-itsm} connectors, specify: + +`category`::: +(Required, string) The category of the incident. + +`impact`::: +(Required, string) The effect an incident had on business. + +`severity`::: +(Required, string) The severity of the incident. + +`subcategory`::: +(Required, string) The subcategory of the incident. + +`urgency`::: +(Required, string) The extent to which the incident resolution can be delayed. + +For {sn-sir} connectors, specify: + +`category`::: +(Required, string) The category of the incident. + +`destIp`::: +(Required, string) A comma separated list of destination IPs. + +`malwareHash`::: +(Required, string) A comma separated list of malware hashes. + +`malwareUrl`::: +(Required, string) A comma separated list of malware URLs. + +`priority`::: +(Required, string) The priority of the incident. + +`sourceIp`::: +(Required, string) A comma separated list of source IPs. + +`subcategory`::: +(Required, string) The subcategory of the incident. + +For {swimlane} connectors, specify: + +`caseId`::: +(Required, string) The case ID. +-- + +`id`:: +(Required, string) The identifier for the connector. To create a case without a +connector, use `none`. +//To retrieve connector IDs, use <>). + +`name`:: +(Required, string) The name of the connector. To create a case without a +connector, use `none`. + +`type`:: +(Required, string) The type of the connector. Valid values are: `.jira`, `.none`, +`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`. To create a case +without a connector, use `.none`. +==== + +`description`:: +(Required, string) The description for the case. + +`owner`:: +(Required, string) The application that owns the case. Valid values are: +`cases`, `observability`, or `securitySolution`. This value affects +whether the case is visible in the {stack-manage-app}, {observability}, or +{security-app}. + +`settings`:: +(Required, object) +An object that contains the case settings. ++ +.Properties of `settings` +[%collapsible%open] +==== +`syncAlerts`:: +(Required, boolean) Turns alert syncing on or off. +==== + +`tags`:: +(Required, string array) The words and phrases that help +categorize cases. It can be an empty array. + +`title`:: +(Required, string) A title for the case. + +=== Response code + +`200`:: + Indicates a successful call. + +=== Example + +[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" + ], + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "priority": "High", + "parent": null + } + }, + "settings": { + "syncAlerts": true + }, + "owner": "securitySolution" +} +-------------------------------------------------- +// KIBANA + +The API returns a JSON object that includes the user who created the case and +the case identifier, version, and creation time. For example: + +[source,json] +-------------------------------------------------- +{ + "id": "66b9aa00-94fa-11ea-9f74-e7e108796192", <1> + "version": "WzUzMiwxXQ==", + "comments": [], + "totalComment": 0, + "totalAlerts": 0, + "title": "This case will self-destruct in 5 seconds", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ], + "settings": { + "syncAlerts": true + }, + "owner": "securitySolution", + "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", + "closed_at": null, + "closed_by": null, + "created_at": "2022-05-13T09:16:17.416Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "status": "open", + "updated_at": null, + "updated_by": null, + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", <2> + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "parent": null, + "priority": "High" + } + }, + "external_service": null <3> +} +-------------------------------------------------- + +<1> The case identifier is also its saved object ID (`savedObjectId`), which is +used when pushing cases to external systems. +<2> The default connector used to push cases to external services. +<3> The `external_service` object stores information about the incident after it +is pushed to an external incident management system. \ No newline at end of file diff --git a/docs/api/cases/cases-api-update.asciidoc b/docs/api/cases/cases-api-update.asciidoc new file mode 100644 index 0000000000000..ed0ef069e15f4 --- /dev/null +++ b/docs/api/cases/cases-api-update.asciidoc @@ -0,0 +1,271 @@ +[[cases-api-update]] +== Update cases API +++++ +Update cases +++++ + +Updates one or more cases. + +=== Request + +`PATCH :/api/cases` + +`PATCH :/s//api/cases` + +=== Prerequisite + +You must have `all` privileges for the *Cases* feature in the *Management*, +*{observability}*, or *Security* section of the +<>, depending on the +`owner` of the cases you're updating. + +=== Path parameters + +``:: +(Optional, string) An identifier for the space. If it is not specified, the +default space is used. + +=== Request body + +`cases`:: +(Required, array of objects) Array containing one or more case objects. ++ +.Properties of `cases` objects +[%collapsible%open] +==== +`connector`:: +(Optional, object) An object that contains the connector configuration. ++ +.Properties of `connector` +[%collapsible%open] +===== +`fields`:: +(Required, object) An object containing the connector fields. ++ +-- +To remove the connector, specify `null`. If you want to omit any individual +field, specify `null` as its value. + +For {ibm-r} connectors, specify: + +`issueTypes`::: +(Required, array of numbers) The issue types of the issue. + +`severityCode`::: +(Required, number) The severity code of the issue. + +For {jira} connectors, specify: + +`issueType`::: +(Required, string) The issue type of the issue. + +`parent`::: +(Required, string) The key of the parent issue, when the issue type is +`Sub-task`. + +`priority`::: +(Required, string) The priority of the issue. + +For {sn-itsm} connectors, specify: + +`category`::: +(Required, string) The category of the incident. + +`impact`::: +(Required, string) The effect an incident had on business. + +`severity`::: +(Required, string) The severity of the incident. + +`subcategory`::: +(Required, string) The subcategory of the incident. + +`urgency`::: +(Required, string) The extent to which the incident resolution can be delayed. + +For {sn-sir} connectors, specify: + +`category`::: +(Required, string) The category of the incident. + +`destIp`::: +(Required, string) A comma separated list of destination IPs. + +`malwareHash`::: +(Required, string) A comma separated list of malware hashes. + +`malwareUrl`::: +(Required, string) A comma separated list of malware URLs. + +`priority`::: +(Required, string) The priority of the incident. + +`sourceIp`::: +(Required, string) A comma separated list of source IPs. + +`subcategory`::: +(Required, string) The subcategory of the incident. + +For {swimlane} connectors, specify: + +`caseId`::: +(Required, string) The identifier for the case. +-- + +`id`:: +(Required, string) The identifier for the connector. To remove the connector, +use `none`. +//To retrieve connector IDs, use <>). + +`name`:: +(Required, string) The name of the connector. To remove the connector, use +`none`. + +`type`:: +(Required, string) The type of the connector. Valid values are: `.jira`, `.none`, +`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`. To remove the +connector, use `.none`. + +===== + +`description`:: +(Optional, string) The updated case description. + +`id`:: +(Required, string) The identifier for the case. + +`settings`:: +(Optional, object) +An object that contains the case settings. ++ +.Properties of `settings` +[%collapsible%open] +===== +`syncAlerts`:: +(Required, boolean) Turn on or off synching with alerts. +===== + +`status`:: +(Optional, string) The case status. Valid values are: `closed`, `in-progress`, +and `open`. + +`tags`:: +(Optional, string array) The words and phrases that help categorize cases. + +`title`:: +(Optional, string) A title for the case. + +`version`:: +(Required, string) The current version of the case. +//To determine this value, use <> or <> +==== + +=== Response code + +`200`:: + Indicates a successful call. + +=== Example + +Update the description, tags, and connector of case ID +`a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`: + +[source,sh] +-------------------------------------------------- +PATCH api/cases +{ + "cases": [ + { + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "WzIzLDFd", + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "priority": null, + "parent": null + } + }, + "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" + ], + "settings": { + "syncAlerts": true + } + } + ] +} +-------------------------------------------------- +// KIBANA + +The API returns the updated case with a new `version` value. For example: + +[source,json] +-------------------------------------------------- +[ + { + "id": "66b9aa00-94fa-11ea-9f74-e7e108796192", + "version": "WzU0OCwxXQ==", + "comments": [], + "totalComment": 0, + "totalAlerts": 0, + "title": "This case will self-destruct in 5 seconds", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ], + "settings": { + "syncAlerts": true + }, + "owner": "securitySolution", + "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!", + "closed_at": null, + "closed_by": null, + "created_at": "2022-05-13T09:16:17.416Z", + "created_by": { + "email": "ahunley@imf.usa.gov", + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "status": "open", + "updated_at": "2022-05-13T09:48:33.043Z", + "updated_by": { + "email": "classified@hms.oo.gov.uk", + "full_name": "Classified", + "username": "M" + }, + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "parent": null, + "priority": null, + } + }, + "external_service": { + "external_title": "IS-4", + "pushed_by": { + "full_name": "Classified", + "email": "classified@hms.oo.gov.uk", + "username": "M" + }, + "external_url": "https://hms.atlassian.net/browse/IS-4", + "pushed_at": "2022-05-13T09:20:40.672Z", + "connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8", + "external_id": "10003", + "connector_name": "Jira" + } + } +] +--------------------------------------------------