From 5f4619284bb829346b4d305c39ab6d1448b5d21c Mon Sep 17 00:00:00 2001 From: Ben Skelker Date: Tue, 17 Dec 2019 16:01:04 +0200 Subject: [PATCH] intial case api docs --- docs/en/siem/cases-api-add-comment.asciidoc | 65 +++++++++++ docs/en/siem/cases-api-create.asciidoc | 80 +++++++++++++ docs/en/siem/cases-api-delete-case.asciidoc | 27 +++++ .../en/siem/cases-api-delete-comment.asciidoc | 27 +++++ docs/en/siem/cases-api-get-all-cases.asciidoc | 108 ++++++++++++++++++ .../siem/cases-api-get-case-comments.asciidoc | 67 +++++++++++ docs/en/siem/cases-api-get-case.asciidoc | 66 +++++++++++ docs/en/siem/cases-api-get-comment.asciidoc | 49 ++++++++ .../en/siem/cases-api-update-comment.asciidoc | 58 ++++++++++ docs/en/siem/cases-api-update.asciidoc | 79 +++++++++++++ docs/en/siem/cases-api.asciidoc | 42 +++++++ docs/en/siem/cases-overview.asciidoc | 6 + docs/en/siem/index.asciidoc | 26 ++++- 13 files changed, 699 insertions(+), 1 deletion(-) create mode 100644 docs/en/siem/cases-api-add-comment.asciidoc create mode 100644 docs/en/siem/cases-api-create.asciidoc create mode 100644 docs/en/siem/cases-api-delete-case.asciidoc create mode 100644 docs/en/siem/cases-api-delete-comment.asciidoc create mode 100644 docs/en/siem/cases-api-get-all-cases.asciidoc create mode 100644 docs/en/siem/cases-api-get-case-comments.asciidoc create mode 100644 docs/en/siem/cases-api-get-case.asciidoc create mode 100644 docs/en/siem/cases-api-get-comment.asciidoc create mode 100644 docs/en/siem/cases-api-update-comment.asciidoc create mode 100644 docs/en/siem/cases-api-update.asciidoc create mode 100644 docs/en/siem/cases-api.asciidoc create mode 100644 docs/en/siem/cases-overview.asciidoc 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..6c387fa73f --- /dev/null +++ b/docs/en/siem/cases-api-add-comment.asciidoc @@ -0,0 +1,65 @@ +[[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 `c2ffcea0-57d0-11ea-95da-cb9f4a010e31`: + +[source,sh] +-------------------------------------------------- +POST api/cases/c2ffcea0-57d0-11ea-95da-cb9f4a010e31/comment +{ + "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 + +A JSON object that includes the user who created the comment and the comment's +ID, version, and creation time. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "comment_id": "f118e4a0-57e1-11ea-95da-cb9f4a010e31", + "version": "WzM1LDFd", + "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "created_at": "2020-02-25T15:17:31.057Z", + "created_by": { + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "updated_at": "2020-02-25T15:17:31.057Z" +} +-------------------------------------------------- \ 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..ea93c917ba --- /dev/null +++ b/docs/en/siem/cases-api-create.asciidoc @@ -0,0 +1,80 @@ +[[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 +|`state` |String a|Indicates whether the case is open or closed. Valid values +are: + +* `open` +* `closed` + +|No, defaults to `open`. +|`tags` |String[] |String array containing words and phrases that help categorize +cases. |No, defaults to 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", + "state": "open", + "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] +-------------------------------------------------- +{ + "case_id": "c2ffcea0-57d0-11ea-95da-cb9f4a010e31", + "version": "WzI4LDFd", + "comments": [], + "created_at": "2020-02-25T13:14:32.264Z", + "created_by": { + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "updated_at": "2020-02-25T13:14:32.264Z", + "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", + "state": "open", + "tags": [ + "phishing", + "social engineering" + ] +} +-------------------------------------------------- \ 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..748f718b81 --- /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,sh] +-------------------------------------------------- +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..4f6dd9d537 --- /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,sh] +-------------------------------------------------- +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..9cb939ec9b --- /dev/null +++ b/docs/en/siem/cases-api-get-all-cases.asciidoc @@ -0,0 +1,108 @@ +[[cases-api-get-all-cases]] +=== Get all cases + +Retrieves a paginated subset of cases. By default, the first page is returned +with 20 results per page. + +==== Request URL + +`GET /api/cases` + +===== 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`. + +|`filter` |String a|Filters the returned results according to the value of the +specified field, using the `case-workflow.attributes.:` syntax, where `` can be: + +* `state` +* `tags` + +|============================================== + +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?page=1&perPage=5&sortField=updatedAt&sortOrder=asc&filter=case-workflow.attributes.tags:phishing +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing all cases. + +===== Response example + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "per_page": 5, + "total": 2, + "cases": [ + { + "case_id": "c2ffcea0-57d0-11ea-95da-cb9f4a010e31", + "version": "WzQ2LDFd", + "comments": [], + "created_at": "2020-02-25T13:14:32.264Z", + "created_by": { + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "updated_at": "2020-02-26T15:46:48.716Z", + "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", + "state": "open", + "tags": [ + "phishing", + "social engineering", + "bubblegum" + ] + }, + { + "case_id": "e1c61e40-58af-11ea-910e-c9f06dd752a6", + "version": "WzUyLDFd", + "comments": [], + "created_at": "2020-02-26T15:51:41.669Z", + "created_by": { + "full_name": "Rat Hustler", + "username": "rhustler" + }, + "updated_at": "2020-02-26T16:21:16.693Z", + "title": "The Long Game", + "description": "Windows 95", + "tags": [ + "windows", + "phishing" + ], + "state": "open" + } + ] +} +-------------------------------------------------- \ 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..436ac2a491 --- /dev/null +++ b/docs/en/siem/cases-api-get-case-comments.asciidoc @@ -0,0 +1,67 @@ +[[cases-api-get-all-case-comments]] +=== Get all case comments + +Returns a paginated subset of 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 `c2ffcea0-57d0-11ea-95da-cb9f4a010e31`: + +[source,sh] +-------------------------------------------------- +GET api/cases/c2ffcea0-57d0-11ea-95da-cb9f4a010e31/comments +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +A JSON object listing comments for the specified case. + +===== Response example + +[source,json] +-------------------------------------------------- +{ + "page": 1, + "per_page": 20, + "total": 2, + "comments": [ + { + "comment_id": "0a846810-5940-11ea-bad4-61e6383623ca", + "version": "WzE1LDFd", + "comment": "Start operation bubblegum immediately! And chew fast!", + "created_at": "2020-02-27T09:03:37.554Z", + "created_by": { + "full_name": "Classified", + "username": "M" + }, + "updated_at": "2020-02-27T09:03:37.554Z" + }, + { + "comment_id": "f118e4a0-57e1-11ea-95da-cb9f4a010e31", + "version": "WzE3LDFd", + "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-02-25T15:17:31.057Z", + "created_by": { + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "updated_at": "2020-02-27T09:35:21.019Z" + } + ] +} +-------------------------------------------------- \ 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..bf7be4af06 --- /dev/null +++ b/docs/en/siem/cases-api-get-case.asciidoc @@ -0,0 +1,66 @@ +[[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 `c2ffcea0-57d0-11ea-95da-cb9f4a010e31` without comments: + +[source,sh] +-------------------------------------------------- +GET api/cases/c2ffcea0-57d0-11ea-95da-cb9f4a010e31?includeComments=false +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The requested case JSON object. + +===== Response example + +[source,json] +-------------------------------------------------- +{ + "case_id": "c2ffcea0-57d0-11ea-95da-cb9f4a010e31", + "version": "WzQsMV0=", + "comments": [], + "created_at": "2020-02-25T13:14:32.264Z", + "created_by": { + "full_name": "Alan Hunley", + "username": "ahunley" + }, + "updated_at": "2020-02-26T15:46:48.716Z", + "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", + "state": "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 0000000000..e49b373066 --- /dev/null +++ b/docs/en/siem/cases-api-get-comment.asciidoc @@ -0,0 +1,49 @@ +[[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 `f118e4a0-57e1-11ea-95da-cb9f4a010e31`: + +[source,sh] +-------------------------------------------------- +GET api/cases/comments/f118e4a0-57e1-11ea-95da-cb9f4a010e31 +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The requested comment JSON object. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "comment_id": "f118e4a0-57e1-11ea-95da-cb9f4a010e31", + "version": "WzMsMV0=", + "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.", + "created_at": "2020-02-25T15:17:31.057Z", + "created_by": { + "full_name": "Ms Moneypenny", + "username": "moneypenny" + }, + "updated_at": "2020-02-26T14:59:06.749Z" +} +-------------------------------------------------- \ 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..e3ebc8d79b --- /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 + +`PATCH /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 `f118e4a0-57e1-11ea-95da-cb9f4a010e3`: + +[source,sh] +-------------------------------------------------- +PATCH api/cases/comment/f118e4a0-57e1-11ea-95da-cb9f4a010e3 +{ + "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." +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The updated comment and its timestamp. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "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.", + "updated_at": "2020-02-27T09:33:39.803Z" +} +-------------------------------------------------- \ 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..9574e9eb67 --- /dev/null +++ b/docs/en/siem/cases-api-update.asciidoc @@ -0,0 +1,79 @@ +[[cases-api-update]] +=== Update case + +Updates an existing case. + +==== Request URL + +`PATCH /api/cases/` + +===== URL parts + +The URL must include the `case ID` of the case you are updating. + +==== Request body + +A JSON object containing: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`case` |Object a|Contains the updated case field values, which can be: + +* `title`: The case's title (string). +* `description`: The case's description (string). +* `state` Indicates whether the case is `open` or `closed`. +* `tags`: String array containing words and phrases that help categorize cases. + +|Yes +|`version` |String |The current case version (returned when calling +<> or <>) |Yes +|============================================== + +===== Example request + +Updates the `description` and `tags` fields of case ID +`c2ffcea0-57d0-11ea-95da-cb9f4a010e31`: + +[source,sh] +-------------------------------------------------- +PATCH api/cases/c2ffcea0-57d0-11ea-95da-cb9f4a010e31 +{ + "case":{ + "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": "WzI4LDFd" +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The updated case with a new `version` value. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "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" + ], + "updated_at": "2020-02-25T16:11:12.637Z", + "version": "WzQwLDFd" +} +-------------------------------------------------- \ 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 c8854cd9d5..cac2e6bd93 100644 --- a/docs/en/siem/index.asciidoc +++ b/docs/en/siem/index.asciidoc @@ -56,4 +56,28 @@ include::prebuilt-rules-reference.asciidoc[] include::rule-details/rule-desc-index.asciidoc[] -include::tune-rule-signals.asciidoc[] \ No newline at end of file +include::tune-rule-signals.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