From 7877de695ee06ce58a3167f8a25b9eb3bd913433 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Mar 2022 12:53:44 -0700 Subject: [PATCH 1/6] [DOCS] Add create case API --- docs/api/cases.asciidoc | 4 +- docs/api/cases/cases-api-create.asciidoc | 213 +++++++++++++++++++++++ 2 files changed, 216 insertions(+), 1 deletion(-) create mode 100644 docs/api/cases/cases-api-create.asciidoc diff --git a/docs/api/cases.asciidoc b/docs/api/cases.asciidoc index 5e412c61926db..e731ddc5adbfc 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] @@ -26,3 +26,5 @@ these APIs: * {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 diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc new file mode 100644 index 0000000000000..49e966ef4a333 --- /dev/null +++ b/docs/api/cases/cases-api-create.asciidoc @@ -0,0 +1,213 @@ +[[cases-api-create]] +== Create case API +++++ +Create case +++++ + +Creates a case. + +=== Request + +`POST :/api/cases` + +=== 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. ++ +-- +For {sn-itsm} connectors, refer to <>. For example: + +* `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-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. +//// +* `priority` (string \| null): The priority of the incident. +* `category` (string \| null): The category of the incident. +* `subcategory` (string \| null): 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`). + +For {ibm-r} connectors, refer to <>. For example: + +* `issueTypes` (number[]): The type of the incident. +* `severityCode` (number): The severity code of the incident. + +For {swimlane} connectors, refer to <>. For example: + +* `caseId` (string \| null): The case ID. +//TBD: Is this correct or should it be comments and severity? +-- + +`id`:: +(Required, string) The identifier for the connector. +//To retrieve connector IDs, use <>). + +`name`:: +(Required, string) The name of the connector. + +`type`:: +(Required, string) The type of the connector. Valid values are: `.jira`, `.none`, +`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`. +==== + +`description`:: +(Required, string) The case's description. + +`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", + } + }, + "settings": { + "syncAlerts": true + }, + "owner": "securitySolution" +} +-------------------------------------------------- +// 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: + +[source,json] +-------------------------------------------------- +{ + "id": "66b9aa00-94fa-11ea-9f74-e7e108796192", + "version": "WzUzMiwxXQ==", + "comments": [], + "totalComment": 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" + ], + "closed_at": null, + "closed_by": null, + "created_at": "2020-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> + "name": "My connector", + "type": ".jira", + "fields": { + "issueType": "10006", + "priority": "High", + } + }, + "settings": { + "syncAlerts": true + }, + "owner": "securitySolution", +} +-------------------------------------------------- + +<1> 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. From 23d608bee391ba92adc4b8b916b337fa8df5263c Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 16 Mar 2022 19:07:58 -0700 Subject: [PATCH 2/6] [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" + } + } +] +-------------------------------------------------- From 7a471c994c1997f5ea3284dbd659d669c9ab66b3 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Mar 2022 09:02:11 -0700 Subject: [PATCH 3/6] [DOCS] Add space id path parameter --- docs/api/cases/cases-api-create.asciidoc | 26 +++++++++++++++--------- docs/api/cases/cases-api-update.asciidoc | 8 +++++++- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc index 0356d22addf5c..c5d74293af185 100644 --- a/docs/api/cases/cases-api-create.asciidoc +++ b/docs/api/cases/cases-api-create.asciidoc @@ -8,7 +8,7 @@ Creates a case. === Request -`POST :/api/cases` +`POST :/s//api/cases` === Prerequisite @@ -16,6 +16,12 @@ You must have `all` privileges for the *Cases* feature in the *Management*, *{observability}*, or *Security* section of the <>. +=== Path parameters + +``:: +(Optional, string) An identifier for the space. If it is not specified, the +default space is used. + === Request body `connector`:: @@ -150,14 +156,12 @@ POST api/cases // KIBANA 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: +the case identifier, version, and creation time. For example: [source,json] -------------------------------------------------- { - "id": "66b9aa00-94fa-11ea-9f74-e7e108796192", + "id": "66b9aa00-94fa-11ea-9f74-e7e108796192", <1> "version": "WzUzMiwxXQ==", "comments": [], "totalComment": 0, @@ -185,7 +189,7 @@ systems. For example: "updated_at": null, "updated_by": null, "connector": { - "id": "131d4448-abe0-4789-939d-8ef60680b498", <1> + "id": "131d4448-abe0-4789-939d-8ef60680b498", <2> "name": "My connector", "type": ".jira", "fields": { @@ -194,10 +198,12 @@ systems. For example: "priority": "High" } }, - "external_service": null <2> + "external_service": null <3> } -------------------------------------------------- -<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. +<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 when the case is pushed to +external systems. \ No newline at end of file diff --git a/docs/api/cases/cases-api-update.asciidoc b/docs/api/cases/cases-api-update.asciidoc index 7db10ac7da2b9..6f9cb3f68f769 100644 --- a/docs/api/cases/cases-api-update.asciidoc +++ b/docs/api/cases/cases-api-update.asciidoc @@ -8,7 +8,7 @@ Updates one or more cases. === Request -`PATCH :/api/cases` +`PATCH :/s//api/cases` === Prerequisite @@ -16,6 +16,12 @@ You must have `all` privileges for the *Cases* feature in the *Management*, *{observability}*, or *Security* section of the <>. +=== Path parameters + +``:: +(Optional, string) An identifier for the space. If it is not specified, the +default space is used. + === Request body `cases`:: From 17d643b818c8b4d9a020e3bf2b428761cdc30348 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Mar 2022 10:04:33 -0700 Subject: [PATCH 4/6] [DOCS] Addresses more feedback --- docs/api/cases/cases-api-create.asciidoc | 6 +++--- docs/api/cases/cases-api-update.asciidoc | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc index c5d74293af185..459e4be182139 100644 --- a/docs/api/cases/cases-api-create.asciidoc +++ b/docs/api/cases/cases-api-create.asciidoc @@ -40,7 +40,7 @@ individual field, specify `null` as its value. For {sn-itsm} connectors, refer to <>. For example: -* `urgency`: The extent to which the incident resolution can delay. +* `urgency`: The extent to which the incident resolution can be delayed. * `severity`: The severity of the incident. * `impact`: The effect an incident had on business. * `category`: The category of the incident. @@ -205,5 +205,5 @@ the case identifier, version, and creation time. For example: <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 when the case is pushed to -external systems. \ No newline at end of file +<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 index 6f9cb3f68f769..261cea77517dd 100644 --- a/docs/api/cases/cases-api-update.asciidoc +++ b/docs/api/cases/cases-api-update.asciidoc @@ -46,9 +46,9 @@ field, specify `null` as its value. For {sn-itsm} connectors, refer to <>. For example: -* `urgency`: The urgency of the incident. +* `urgency`: The extent to which the incident resolution can be delayed. * `severity`: The severity of the incident. -* `impact`: The impact of the incident. +* `impact`: The effect an incident had on business. * `category`: The category of the incident. * `subcategory`: The subcategory of the incident. @@ -146,6 +146,8 @@ PATCH api/cases { "cases": [ { + "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2", + "version": "WzIzLDFd", "connector": { "id": "131d4448-abe0-4789-939d-8ef60680b498", "name": "My connector", @@ -156,7 +158,6 @@ PATCH api/cases "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 @@ -168,8 +169,7 @@ PATCH api/cases ], "settings": { "syncAlerts": true - }, - "version": "WzIzLDFd" + } } ] } From d43bd40dc6f78363a2bcb329e08c47f6787c7258 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 17 Mar 2022 19:31:23 -0700 Subject: [PATCH 5/6] [DOCS] Fixes field descriptions --- docs/api/cases/cases-api-create.asciidoc | 83 +++++++++++++++--------- docs/api/cases/cases-api-update.asciidoc | 83 ++++++++++++++++-------- 2 files changed, 109 insertions(+), 57 deletions(-) diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc index 459e4be182139..b486c7f9e5045 100644 --- a/docs/api/cases/cases-api-create.asciidoc +++ b/docs/api/cases/cases-api-create.asciidoc @@ -37,44 +37,69 @@ default space is used. To create a case without a connector, specify `null`. If you want to omit any individual field, specify `null` as its value. -For {sn-itsm} connectors, refer to <>. For -example: +For {ibm-r} connectors, specify: -* `urgency`: The extent to which the incident resolution can be delayed. -* `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. +`issueTypes`::: +(Required, array of numbers) The type of the incident. -For {sn-sir} connectors, refer to <>. For example: +`severityCode`::: +(Required, number) The severity code of the incident. -//// -//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, specify: -For {jira} connectors, refer to <>. For example: +`issueType`::: +(Required, string) The type of the issue. -* `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`). +`parent`::: +(Required, string) The key of the parent issue, when the issue type is `Sub-task`. -For {ibm-r} connectors, refer to <>. For example: +`priority`::: +(Required, string) The priority of the issue. -* `issueTypes`: The type of the incident. -* `severityCode`: The severity code of the incident. +For {sn-itsm} connectors, specify: -For {swimlane} connectors, refer to <>. For -example: +`category`::: +(Required, string) The category of the incident. -* `caseId`: The case ID. -//TBD: Is this correct or should it be comments and severity? +`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`:: diff --git a/docs/api/cases/cases-api-update.asciidoc b/docs/api/cases/cases-api-update.asciidoc index 261cea77517dd..588e102622ae7 100644 --- a/docs/api/cases/cases-api-update.asciidoc +++ b/docs/api/cases/cases-api-update.asciidoc @@ -43,43 +43,70 @@ default space is used. 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: +For {ibm-r} connectors, specify: -* `urgency`: The extent to which the incident resolution can be delayed. -* `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. +`issueTypes`::: +(Required, array of numbers) The issue types of the issue. -For {sn-sir} connectors, refer to <>. For example: +`severityCode`::: +(Required, number) The severity code of the issue. -//// -//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, specify: -For {jira} connectors, refer to <>. For example: +`issueType`::: +(Required, string) The issue type of the issue. -* `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`). +`parent`::: +(Required, string) The key of the parent issue, when the issue type is +`Sub-task`. -For {ibm-r} connectors, refer to <>. For example: +`priority`::: +(Required, string) The priority of the issue. -* `issueTypes`: The issue types of the issue. -* `severityCode`: The severity code of the issue. +For {sn-itsm} connectors, specify: -For {swimlane} connectors, refer to <>. For example: +`category`::: +(Required, string) The category of the incident. -* `caseId`: The case ID. -//TBD: Is this correct or should it be comments and severity? +`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`:: From 0cfb1fab28ae261de027ab7416387891fbfe1e26 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 18 Mar 2022 10:18:47 -0700 Subject: [PATCH 6/6] [DOCS] Clarify URL and prereqs --- docs/api/cases/cases-api-create.asciidoc | 5 ++++- docs/api/cases/cases-api-update.asciidoc | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/api/cases/cases-api-create.asciidoc b/docs/api/cases/cases-api-create.asciidoc index b486c7f9e5045..f08b69998321f 100644 --- a/docs/api/cases/cases-api-create.asciidoc +++ b/docs/api/cases/cases-api-create.asciidoc @@ -8,13 +8,16 @@ 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 diff --git a/docs/api/cases/cases-api-update.asciidoc b/docs/api/cases/cases-api-update.asciidoc index 588e102622ae7..ed0ef069e15f4 100644 --- a/docs/api/cases/cases-api-update.asciidoc +++ b/docs/api/cases/cases-api-update.asciidoc @@ -8,13 +8,16 @@ 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