From 23d608bee391ba92adc4b8b916b337fa8df5263c Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Mar 2022 19:07:58 -0700 Subject: [PATCH] [DOCS] Add update case API --- docs/api/cases.asciidoc | 5 +- docs/api/cases/cases-api-create.asciidoc | 122 ++++++------ docs/api/cases/cases-api-update.asciidoc | 235 +++++++++++++++++++++++ 3 files changed, 294 insertions(+), 68 deletions(-) create mode 100644 docs/api/cases/cases-api-update.asciidoc diff --git a/docs/api/cases.asciidoc b/docs/api/cases.asciidoc index e731ddc5adbfc..00fbedc2d1299 100644 --- a/docs/api/cases.asciidoc +++ b/docs/api/cases.asciidoc @@ -24,7 +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] \ No newline at end of file +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 index 49e966ef4a333..0356d22addf5c 100644 --- a/docs/api/cases/cases-api-create.asciidoc +++ b/docs/api/cases/cases-api-create.asciidoc @@ -10,6 +10,12 @@ Creates a case. `POST :/api/cases` +=== Prerequisite + +You must have `all` privileges for the *Cases* feature in the *Management*, +*{observability}*, or *Security* section of the +<>. + === Request body `connector`:: @@ -22,58 +28,66 @@ Creates a case. (Required, object) An object containing the connector fields. + -- -For {sn-itsm} connectors, refer to <>. For example: +To create a case without a connector, specify `null`. If you want to omit any +individual field, specify `null` as its value. -* `urgency` (string \| null): The extent to which the incident resolution can delay. -* `severity` (string \| null): The severity of the incident. -* `impact` (string \| null): The effect an incident had on business. -* `category` (string \| null): The category of the incident. -* `subcategory` (string \| null): The subcategory of the incident. +For {sn-itsm} connectors, refer to <>. For +example: + +* `urgency`: The extent to which the incident resolution can delay. +* `severity`: The severity of the incident. +* `impact`: The effect an incident had on business. +* `category`: The category of the incident. +* `subcategory`: The subcategory of the incident. For {sn-sir} connectors, refer to <>. For example: //// //TBD: Are these valid? They don't appear in the action docs -* `destIp` (string \| null): A comma separated list of destination IPs. -* `malwareHash` (string \| null): A comma separated list of malware hashes. -* `malwareUrl` (string \| null): A comma separated list of malware URLs. -* `sourceIp` (string \| null): A comma separated list of source IPs. +* `destIp`: A comma separated list of destination IPs. +* `malwareHash`: A comma separated list of malware hashes. +* `malwareUrl`: A comma separated list of malware URLs. +* `sourceIp`: A comma separated list of source IPs. //// -* `priority` (string \| null): The priority of the incident. -* `category` (string \| null): The category of the incident. -* `subcategory` (string \| null): The subcategory of the incident. +* `priority`: The priority of the incident. +* `category`: The category of the incident. +* `subcategory`: The subcategory of the incident. For {jira} connectors, refer to <>. For example: -* `issueType` (string): The type of the issue. -* `priority` (string \| null): The priority of the issue. -* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`). +* `issueType`: The type of the issue. +* `priority`: The priority of the issue. +* `parent`: The key of the parent issue (Valid when the issue type is `Sub-task`). For {ibm-r} connectors, refer to <>. For example: -* `issueTypes` (number[]): The type of the incident. -* `severityCode` (number): The severity code of the incident. +* `issueTypes`: The type of the incident. +* `severityCode`: The severity code of the incident. -For {swimlane} connectors, refer to <>. For example: +For {swimlane} connectors, refer to <>. For +example: -* `caseId` (string \| null): The case ID. +* `caseId`: The case ID. //TBD: Is this correct or should it be comments and severity? -- `id`:: -(Required, string) The identifier for the connector. +(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. +(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`. +`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`. To create a case +without a connector, use `.none`. ==== `description`:: -(Required, string) The case's description. +(Required, string) The description for the case. `owner`:: (Required, string) The application that owns the case. Valid values are: @@ -124,6 +138,7 @@ POST api/cases "fields": { "issueType": "10006", "priority": "High", + "parent": null } }, "settings": { @@ -134,37 +149,10 @@ POST api/cases -------------------------------------------------- // KIBANA -Creates a case with no connector: - -[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": "none", - "name": "none", - "type": ".none", - "fields": null - }, - "settings": { - "syncAlerts": true - }, - "owner": "securitySolution" -} --------------------------------------------------- -// KIBANA - -The API returns an JSON object that includes the user who created the case and -the case's ID, version, and creation time. The case's ID is also its saved -object ID (`savedObjectId`), used when pushing cases to external systems. For -example: +The API returns a JSON object that includes the user who created the case and +the case identifier, version, and creation time. The case ID is also its saved +object ID (`savedObjectId`), which is used when pushing cases to external +systems. For example: [source,json] -------------------------------------------------- @@ -173,41 +161,43 @@ example: "version": "WzUzMiwxXQ==", "comments": [], "totalComment": 0, + "totalAlerts": 0, "title": "This case will self-destruct in 5 seconds", - "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 + }, + "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": "2020-05-13T09:16:17.416Z", + "created_at": "2022-05-13T09:16:17.416Z", "created_by": { "email": "ahunley@imf.usa.gov", "full_name": "Alan Hunley", "username": "ahunley" }, - "external_service": null, <1> "status": "open", "updated_at": null, "updated_by": null, "connector": { - "id": "131d4448-abe0-4789-939d-8ef60680b498", <2> + "id": "131d4448-abe0-4789-939d-8ef60680b498", <1> "name": "My connector", "type": ".jira", "fields": { "issueType": "10006", - "priority": "High", + "parent": null, + "priority": "High" } }, - "settings": { - "syncAlerts": true - }, - "owner": "securitySolution", + "external_service": null <2> } -------------------------------------------------- -<1> The `external_service` object stores information when the case is pushed to +<1> The default connector used to push cases to external services. +<2> The `external_service` object stores information when the case is pushed to external systems. -<2> The default connector used to push cases to external services. diff --git a/docs/api/cases/cases-api-update.asciidoc b/docs/api/cases/cases-api-update.asciidoc new file mode 100644 index 0000000000000..7db10ac7da2b9 --- /dev/null +++ b/docs/api/cases/cases-api-update.asciidoc @@ -0,0 +1,235 @@ +[[cases-api-update]] +== Update cases API +++++ +Update cases +++++ + +Updates one or more cases. + +=== Request + +`PATCH :/api/cases` + +=== Prerequisite + +You must have `all` privileges for the *Cases* feature in the *Management*, +*{observability}*, or *Security* section of the +<>. + +=== 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 {sn-itsm} connectors, refer to <>. For +example: + +* `urgency`: The urgency of the incident. +* `severity`: The severity of the incident. +* `impact`: The impact of the incident. +* `category`: The category of the incident. +* `subcategory`: The subcategory of the incident. + +For {sn-sir} connectors, refer to <>. For example: + +//// +//TBD: Are these valid? They don't appear in the action docs +* `destIp`: A comma separated list of destination IPs. +* `malwareHash`: A comma separated list of malware hashes. +* `malwareUrl`: A comma separated list of malware URLs. +* `sourceIp`: A comma separated list of source IPs. +//// +* `priority`: The priority of the incident. +* `category`: The category of the incident. +* `subcategory`: The subcategory of the incident. + +For {jira} connectors, refer to <>. For example: + +* `issueType`: The issue type of the issue. +* `priority`: The priority of the issue. +* `parent`: The key of the parent issue (Valid when the issue type is `Sub-task`). + +For {ibm-r} connectors, refer to <>. For example: + +* `issueTypes`: The issue types of the issue. +* `severityCode`: The severity code of the issue. + +For {swimlane} connectors, refer to <>. For example: + +* `caseId`: The case ID. +//TBD: Is this correct or should it be comments and severity? +-- + +`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": [ + { + "connector": { + "id": "131d4448-abe0-4789-939d-8ef60680b498", + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "priority": null, + "parent": null + } + }, + "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" + ], + "settings": { + "syncAlerts": true + }, + "version": "WzIzLDFd" + } + ] +} +-------------------------------------------------- +// 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" + } + } +] +--------------------------------------------------