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 0000000000..64f938ee15 --- /dev/null +++ b/docs/en/siem/cases-api-add-comment.asciidoc @@ -0,0 +1,69 @@ +[[cases-api-add-comment]] +=== Add comment + +Adds a comment to an existing case. + +==== Request URL + +`POST /api/cases//comment` + +===== URL parts + +The URL must include the `case ID` of the case to which you are adding a +comment. + +==== 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 `7125e150-2fb7-11ea-a3be-f96a1b9531f4`: + +[source,js] +-------------------------------------------------- +POST api/cases/7125e150-2fb7-11ea-a3be-f96a1b9531f4/comment +{ + "comment": "Start operation bubblegum immediately!" +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- +{ + "type": "case-workflow-comment", + "id": "0aa70f70-2fb8-11ea-a3be-f96a1b9531f4", + "attributes": { + "comment": "Start operation bubblegum immediately!", + "created_at": 1578227808536, + "created_by": { + "full_name": "Classified", + "username": "M" + } + }, + "references": [ + { + "type": "case-workflow", + "name": "associated-case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4" + } + ], + "updated_at": "2020-01-05T12:36:48.743Z", + "version": "WzQyLDFd" +} +-------------------------------------------------- \ 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 0000000000..5829884312 --- /dev/null +++ b/docs/en/siem/cases-api-create.asciidoc @@ -0,0 +1,85 @@ +[[cases-api-create]] +=== Create case + +Creates a new case. + +==== Request URL + +`POST /api/cases` + +==== Request body + +A JSON object with these fields: + +include::shared-content/case-schema.asciidoc[tag=cases-api-json-schema] + +===== 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": "Urgent phishing case - signal id #dd4fa2d4bd-804743795894438", + "state": "open", + "tags": [ + "phishing", + "social engineering" + ], + "case_type": "security", + "assignees": [ + { + "username": "M", + "full_name": "Classified" + }, + { + "username": "Q", + "full_name": "Quality Gadgets" + } + ] +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- +{ + "type": "case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4", + "attributes": { + "created_at": 1578227551012, + "created_by": { + "full_name": "Ms Moneypenny", + "username": "Moneypenny" + }, + "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants", + "title": "Urgent phishing case - signal id #dd4fa2d4bd-804743795894438", + "state": "open", + "tags": [ + "phishing", + "social engineering" + ], + "case_type": "security", + "assignees": [ + { + "username": "M", + "full_name": "Classified" + }, + { + "username": "Q", + "full_name": "Quality Gadgets" + } + ] + }, + "references": [], + "updated_at": "2020-01-05T12:32:31.205Z", + "version": "WzQxLDFd" +} +-------------------------------------------------- \ 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 0000000000..8c2dfd1812 --- /dev/null +++ b/docs/en/siem/cases-api-delete-case.asciidoc @@ -0,0 +1,27 @@ +[[cases-api-delete-case]] +=== Delete case + +Deletes the specified case and all associated comments. + +==== Request URL + +`DELETE /api/cases/` + +===== URL parts + +The URL must include the `case ID` of the case you are deleting. + +===== Example request + +Deletes case ID `0a0fa050-20e4-11ea-8f80-690fedc74682`: + +[source,js] +-------------------------------------------------- +DELETE api/cases/0a0fa050-20e4-11ea-8f80-690fedc74682 +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + 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 0000000000..e420711c35 --- /dev/null +++ b/docs/en/siem/cases-api-delete-comment.asciidoc @@ -0,0 +1,27 @@ +[[cases-api-delete-comment]] +=== Delete comment + +Deletes the specified comment. + +==== Request URL + +`DELETE /api/cases/comments/` + +===== URL parts + +The URL must include the `comment ID` of the comment you are deleting. + +===== Example request + +Deletes comment ID `669364c0-2174-11ea-87ed-69e2fb63d9ed`: + +[source,js] +-------------------------------------------------- +DELETE api/cases/comments/669364c0-2174-11ea-87ed-69e2fb63d9ed +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. \ No newline at end of file diff --git a/docs/en/siem/cases-api-get-all-cases.asciidoc b/docs/en/siem/cases-api-get-all-cases.asciidoc new file mode 100644 index 0000000000..190320df37 --- /dev/null +++ b/docs/en/siem/cases-api-get-all-cases.asciidoc @@ -0,0 +1,70 @@ +[[cases-api-get-all-cases]] +=== Get all cases + +Returns all cases. + +==== Request URL + +`GET /api/cases` + +===== Example request + +[source,js] +-------------------------------------------------- +GET api/cases +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing all cases: + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "per_page": 20, + "total": 007, + "saved_objects": [ + { + "type": "case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4", + "attributes": { + "created_at": 1578227551012, + "created_by": { + "full_name": "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. Repeat - operation bubblegum is now active", + "title": "Urgent phishing case - signal id #dd4fa2d4bd-804743795894438", + "state": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ], + "case_type": "security", + "assignees": [ + { + "username": "M", + "full_name": "Classified" + }, + { + "username": "Q", + "full_name": "Quality Gadgets" + } + ] + }, + "references": [], + "updated_at": "2020-01-05T13:13:58.167Z", + "version": "WzQ1LDFd" + }, + ... + ] +} +-------------------------------------------------- \ 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 0000000000..1e46eff9ea --- /dev/null +++ b/docs/en/siem/cases-api-get-case-comments.asciidoc @@ -0,0 +1,85 @@ +[[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. + +===== Example request + +Gets all comments for case ID `7125e150-2fb7-11ea-a3be-f96a1b9531f4`: + +[source,js] +-------------------------------------------------- +GET api/cases/7125e150-2fb7-11ea-a3be-f96a1b9531f4/comments +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing all comments for the specified case: + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "per_page": 20, + "total": 2, + "saved_objects": [ + { + "type": "case-workflow-comment", + "id": "0aa70f70-2fb8-11ea-a3be-f96a1b9531f4", + "attributes": { + "comment": "Start operation bubblegum immediately! And chew fast!", + "created_at": 1578227808536, + "created_by": { + "full_name": "Classified", + "username": "M" + } + }, + "references": [ + { + "type": "case-workflow", + "name": "associated-case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4" + } + ], + "updated_at": "2020-01-05T12:58:54.109Z", + "version": "WzQ0LDFd" + }, + { + "type": "case-workflow-comment", + "id": "0b5174b0-2fc2-11ea-a3be-f96a1b9531f4", + "attributes": { + "comment": "Started chewing.", + "created_at": 1578232104629, + "created_by": { + "full_name": "Ms Moneypenny", + "username": "Moneypenny" + } + }, + "references": [ + { + "type": "case-workflow", + "name": "associated-case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4" + } + ], + "updated_at": "2020-01-05T13:48:24.827Z", + "version": "WzQ2LDFd" + } + ] +} +-------------------------------------------------- \ 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 0000000000..b7c1d62bb9 --- /dev/null +++ b/docs/en/siem/cases-api-get-case.asciidoc @@ -0,0 +1,78 @@ +[[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. + +===== 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 `7125e150-2fb7-11ea-a3be-f96a1b9531f4` without comments: + +[source,js] +-------------------------------------------------- +GET api/cases/7125e150-2fb7-11ea-a3be-f96a1b9531f4?includeComments=false +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing the case: + +[source,json] +-------------------------------------------------- +{ + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4", + "type": "case-workflow", + "updated_at": "2020-01-05T13:13:58.167Z", + "version": "WzQ1LDFd", + "attributes": { + "created_at": 1578227551012, + "created_by": { + "full_name": "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. Repeat - operation bubblegum is now active", + "title": "Urgent phishing case - signal id #dd4fa2d4bd-804743795894438", + "state": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ], + "case_type": "security", + "assignees": [ + { + "username": "M", + "full_name": "Classified" + }, + { + "username": "Q", + "full_name": "Quality Gadgets" + } + ] + }, + "references": [] +} +-------------------------------------------------- \ 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 0000000000..96486c2c54 --- /dev/null +++ b/docs/en/siem/cases-api-get-comment.asciidoc @@ -0,0 +1,56 @@ +[[cases-api-get-comment]] +=== Get comment + +Gets the specified comment. + +==== Request URL + +`GET /api/cases/comment/` + +===== URL parts + +The URL must include the `comment ID` of the comment you are retrieving. To +retrieve all comment IDs, call <>. + +===== Example request + +Retrieves comment ID `0b5174b0-2fc2-11ea-a3be-f96a1b9531f4`, which is +associated with case ID `7125e150-2fb7-11ea-a3be-f96a1b9531f4`: + +[source,js] +-------------------------------------------------- +GET api/cases/comments/0b5174b0-2fc2-11ea-a3be-f96a1b9531f4 +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- +{ + "id": "0b5174b0-2fc2-11ea-a3be-f96a1b9531f4", + "type": "case-workflow-comment", + "updated_at": "2020-01-05T13:48:24.827Z", + "version": "WzQ2LDFd", + "attributes": { + "comment": "Started chewing.", + "created_at": 1578232104629, + "created_by": { + "full_name": "Ms Moneypenny", + "username": "Moneypenny" + } + }, + "references": [ + { + "type": "case-workflow", + "name": "associated-case-workflow", + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4" + } + ] +} +-------------------------------------------------- \ 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 0000000000..4b7abb8d01 --- /dev/null +++ b/docs/en/siem/cases-api-update-comment.asciidoc @@ -0,0 +1,58 @@ +[[cases-api-update-comment]] +=== Update comment + +Updates an existing comment. + +==== Request URL + +`POST /api/cases/comment/` + +===== URL parts + +The URL must include the `comment ID` of the comment you are updating. To +retrieve all comment IDs, call <>. + +==== Request body + +A JSON object with updated comment: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`comment` |String |The updated comment. |Yes +|============================================== + +===== Example request + +Updates comment ID `0aa70f70-2fb8-11ea-a3be-f96a1b9531f4`, which is associated +with case ID `7125e150-2fb7-11ea-a3be-f96a1b9531f4`: + +[source,js] +-------------------------------------------------- +POST api/cases/comment/0aa70f70-2fb8-11ea-a3be-f96a1b9531f4 +{ + "comment": "Start operation bubblegum immediately! And chew fast!" +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- +{ + "id": "0aa70f70-2fb8-11ea-a3be-f96a1b9531f4", + "type": "case-workflow-comment", + "updated_at": "2020-01-05T12:58:54.109Z", + "version": "WzQ0LDFd", + "attributes": { + "comment": "Start operation bubblegum immediately! And chew fast!" + } +} +-------------------------------------------------- \ 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 0000000000..a09a48cf6d --- /dev/null +++ b/docs/en/siem/cases-api-update.asciidoc @@ -0,0 +1,62 @@ +[[cases-api-update]] +=== Update case + +Updates an existing case. + +==== Request URL + +`POST /api/cases/` + +===== URL parts + +The URL must include the `case ID` of the case you are updating. + +==== Request body + +A JSON object with the fields you are updating: + +include::shared-content/case-schema.asciidoc[tag=cases-api-json-schema] + +===== Example request + +Updates the `description` and `tags` fields of case ID +`7125e150-2fb7-11ea-a3be-f96a1b9531f4`: + +[source,js] +-------------------------------------------------- +POST api/cases/7125e150-2fb7-11ea-a3be-f96a1b9531f4 +{ + "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" + ] +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- +{ + "id": "7125e150-2fb7-11ea-a3be-f96a1b9531f4", + "type": "case-workflow", + "updated_at": "2020-01-05T12:42:33.357Z", + "version": "WzQzLDFd", + "attributes": { + "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" + ] + } +} +-------------------------------------------------- \ 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 0000000000..88034bfa2b --- /dev/null +++ b/docs/en/siem/cases-api.asciidoc @@ -0,0 +1,42 @@ +[[cases-api-overview]] +[role="xpack"] +== Cases API + +The cases API is used to open action items about security issues for specific +people. + +The RESTful API endpoint is: + +`/api/cases` + +Where `` is the URL and port number of your Kibana instance. + +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-overview.asciidoc b/docs/en/siem/cases-overview.asciidoc new file mode 100644 index 0000000000..aa43789c53 --- /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 ae38bb1d23..df7ac0e481 100644 --- a/docs/en/siem/index.asciidoc +++ b/docs/en/siem/index.asciidoc @@ -54,4 +54,28 @@ include::rules-api-prebuilt.asciidoc[] include::prebuilt-rules-reference.asciidoc[] -include::rule-details/rule-desc-index.asciidoc[] \ No newline at end of file +include::rule-details/rule-desc-index.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-get-all-cases.asciidoc[] + +include::cases-api-get-case.asciidoc[] + +include::cases-api-get-case-comments.asciidoc[] + +include::cases-api-get-comment.asciidoc[] + +include::cases-api-delete-comment.asciidoc[] + +include::cases-api-delete-case.asciidoc[] \ No newline at end of file diff --git a/docs/en/siem/shared-content/case-schema.asciidoc b/docs/en/siem/shared-content/case-schema.asciidoc new file mode 100644 index 0000000000..2f11457cf4 --- /dev/null +++ b/docs/en/siem/shared-content/case-schema.asciidoc @@ -0,0 +1,29 @@ +// tag::cases-api-json-schema[] +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`title` |String |The case's title. |Yes +|`description` |String |The case's description. |Yes +|`case_type` |String |The type of case. For example, `security`. |Yes +|`state` |String a|Indicates whether the case is open or closed. Valid values +are: + +* `open` +* `closed` + +|No, defaults to `open`. +|assignees |Object[] a|Object containing string arrays for the names of people +assigned to the case: + +* `username` (String, required) - The username of the person assigned to the +case. +* `full_name` (String, optional) - The full name of the person assigned to the +object. + +|No, defaults to an empty array. + +|`tags` |String[] |String array containing words and phrases that help categorize +cases. |No, defaults to an empty array. +|============================================== +// end::cases-api-json-schema[]