Skip to content

Commit 964419c

Browse files
benskelkerbenskelker
authored
[SIEM] [Docs] Cases API (#761) (#977)
* intial case api docs * starts updating the api * updates patch comments * api updates * starts conf api * more conf api stuff * minor fixes * more updates * proofing * typo * formatting * gets rid of me * adds delete all comments method * corrections after feedback * corrections 2 * corrections continued * cmore corrections * and more corrections * even more * rebase * adds reporters to find * corrections * corrections II * connector corrections * final corrections
1 parent c620169 commit 964419c

24 files changed

+2036
-0
lines changed

‎docs/en/siem/case-api-update-connector.asciidoc

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
[[case-api-update-connector]]
2+
=== Update case configurations
3+
4+
Updates the connector's case closure settings.
5+
6+
Connectors are used to interface with external systems. You can only call this
7+
method after you have created a connector (see <<register-connector>>). After a
8+
connector has been created and assigned, call <<cases-actions-api-execute>> to
9+
send cases to the external system.
10+
11+
==== Request URL
12+
13+
`PATCH <kibana host>/<port>/api/cases/configure`
14+
15+
==== Request body
16+
17+
A JSON object with these fields:
18+
19+
|==============================================
20+
|Name |Type |Description |Required
21+
22+
|`connector_id` |String |The ID of the connector you want to use for sending
23+
cases to external systems. |No
24+
|`connector_name` |String |The connector name. |No
25+
|`closure_type` |String a|Determines whether a case is automatically closed in
26+
the {siem-app} when it is pushed to {sn}. Valid values are:
27+
28+
* `close-by-pushing`: {siem-app} cases are automatically closed when they
29+
are pushed to {sn}.
30+
* `close-by-user`: {siem-app} cases are not automatically closed.
31+
32+
|No
33+
34+
|`version` |String |The connector version. |Yes
35+
|==============================================
36+
37+
NOTE: Call <<cases-get-connector>> to retrieve the version value, and
38+
<<cases-api-find-connectors>> to retrieve connector IDs.
39+
40+
===== Example request
41+
42+
Changes the connector's case closure option:
43+
44+
[source,sh]
45+
--------------------------------------------------
46+
PATCH api/cases/configure
47+
{
48+
"connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
49+
"closure_type": "close-by-pushing",
50+
"version": "WzIwMiwxXQ=="
51+
}
52+
--------------------------------------------------
53+
// KIBANA
54+
55+
==== Response code
56+
57+
`200`::
58+
Indicates a successful call.
59+
60+
===== Example response
61+
62+
[source,json]
63+
--------------------------------------------------
64+
{
65+
"connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
66+
"closure_type": "close-by-pushing",
67+
"connector_name": "ServiceNow",
68+
"created_at": "2020-03-30T13:31:38.083Z",
69+
"created_by": {
70+
"email": "[email protected]",
71+
"full_name": "Ms Admin",
72+
"username": "admin"
73+
},
74+
"updated_at": "2020-03-31T06:21:35.759Z",
75+
"updated_by": {
76+
"email": "[email protected]",
77+
"full_name": "Ms Admin",
78+
"username": "admin"
79+
},
80+
"version": "WzIwMywxXQ=="
81+
}
82+
--------------------------------------------------
83+

‎docs/en/siem/cases-api-add-comment.asciidoc

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
[[cases-api-add-comment]]
2+
=== Add comment
3+
4+
Adds a comment to an existing case.
5+
6+
==== Request URL
7+
8+
`POST <kibana host>/<port>/api/cases/<case ID>/comments`
9+
10+
===== URL parts
11+
12+
The URL must include the `case ID` of the case to which you are adding a
13+
comment. Call <<cases-api-find-cases>> to retrieve case IDs.
14+
15+
==== Request body
16+
17+
A JSON object with a `comment` field:
18+
19+
[width="100%",options="header"]
20+
|==============================================
21+
|Name |Type |Description |Required
22+
23+
|`comment` |String |The case's new comment. |Yes
24+
|==============================================
25+
26+
===== Example request
27+
28+
Adds a comment to case ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`:
29+
30+
[source,sh]
31+
--------------------------------------------------
32+
POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
33+
{
34+
"comment": "That is nothing - Ethan Hunt answered a targeted social
35+
media campaign promoting phishy pension schemes to IMF operatives."
36+
}
37+
--------------------------------------------------
38+
// KIBANA
39+
40+
==== Response code
41+
42+
`200`::
43+
Indicates a successful call.
44+
45+
==== Response payload
46+
47+
The updated JSON case object with the new comment, the user who created the
48+
comment, and the comment's ID, version, and creation time.
49+
50+
===== Example response
51+
52+
[source,json]
53+
--------------------------------------------------
54+
55+
"id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
56+
"version": "WzIwNDMyLDFd",
57+
"comments": [
58+
{
59+
"id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
60+
"version": "WzIwNDMxLDFd",
61+
"comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
62+
"created_at": "2020-04-02T15:28:03.034Z",
63+
"created_by": {
64+
"email": "[email protected]",
65+
"full_name": "Ms Moneypenny",
66+
"username": "moneypenny"
67+
},
68+
"pushed_at": null,
69+
"pushed_by": null,
70+
"updated_at": null,
71+
"updated_by": null
72+
}
73+
],
74+
"totalComment": 0,
75+
"title": "This case will self-destruct in 5 seconds",
76+
"tags": [
77+
"phishing",
78+
"social engineering"
79+
],
80+
"description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
81+
"closed_at": null,
82+
"closed_by": null,
83+
"created_at": "2020-04-02T15:25:19.088Z",
84+
"created_by": {
85+
"email": "[email protected]",
86+
"full_name": "Alan Hunley",
87+
"username": "ahunley"
88+
},
89+
"external_service": null,
90+
"status": "open",
91+
"updated_at": "2020-04-02T15:28:03.034Z",
92+
"updated_by": {
93+
"email": "[email protected]",
94+
"full_name": "Ms Moneypenny",
95+
"username": "moneypenny"
96+
}
97+
}
98+
--------------------------------------------------

‎docs/en/siem/cases-api-assign-connector.asciidoc

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
[[assign-connector]]
2+
=== Set connector
3+
4+
Sets the default connector in the {siem-ui}.
5+
6+
Connectors are used to interface with external systems. You can only call this
7+
method after you have created a connector (see <<register-connector>>). After a
8+
connector has been created and assigned, call <<cases-actions-api-execute>> to
9+
send cases to the external system.
10+
11+
==== Request URL
12+
13+
`POST <kibana host>/<port>/api/cases/configure`
14+
15+
==== Request body
16+
17+
A JSON object with these fields:
18+
19+
[width="100%",options="header"]
20+
|==============================================
21+
|Name |Type |Description |Required
22+
23+
|`connector_id` |String |The connector ID. |Yes
24+
|`connector_name` |String |The connector name. |Yes
25+
|`closure_type` |String a|Determines whether a case is automatically closed in
26+
the {siem-app} when it is pushed to {sn}. Valid values are:
27+
28+
* `close-by-pushing`: {siem-app} cases are automatically closed when they
29+
are pushed to {sn}.
30+
* `close-by-user`: {siem-app} cases are not automatically closed.
31+
32+
|Yes
33+
|==============================================
34+
35+
NOTE: Call <<cases-api-find-connectors>> to retrieve connector IDs and names.
36+
37+
==== Example request
38+
39+
[source,sh]
40+
--------------------------------------------------
41+
POST api/cases/configure
42+
{
43+
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
44+
"closure_type": "close-by-user",
45+
"connector_name": "ServiceNow"
46+
}
47+
--------------------------------------------------
48+
49+
==== Response code
50+
51+
`200`::
52+
Indicates a successful call.
53+
54+
==== Example response
55+
56+
[source,json]
57+
--------------------------------------------------
58+
{
59+
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
60+
"closure_type": "close-by-user",
61+
"connector_name": "ServiceNow",
62+
"created_at": "2020-03-30T13:31:38.083Z",
63+
"created_by": {
64+
"email": "[email protected]",
65+
"full_name": "Ms Moneypenny",
66+
"username": "moneypenny"
67+
},
68+
"updated_at": null,
69+
"updated_by": null,
70+
"version": "WzE3NywxXQ=="
71+
}
72+
--------------------------------------------------

‎docs/en/siem/cases-api-associate-sn.asciidoc

+103
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
[[cases-api-associate-sn-incident]]
2+
=== Add external details to case
3+
4+
Adds the data returned from {sn} to the specified case.
5+
6+
After sending a new or updated case to {sn}, you must associate the returned
7+
{sn} incident fields with the case in the {siem-app}.
8+
9+
==== Request URL
10+
11+
`POST <kibana host>/<port>/api/cases/<case ID>/_push`
12+
13+
===== URL parts
14+
15+
The URL must include the `case ID` of the case you are updating. Call
16+
<<cases-api-find-cases>> to retrieve case IDs.
17+
18+
==== Request body
19+
20+
A JSON object with the data returned from {sn}:
21+
22+
[width="100%",options="header"]
23+
|==============================================
24+
|Name |Type |Description |Required
25+
26+
|`connector_id` |String |The ID of the connector used to send the case to {sn}.
27+
|Yes
28+
|`connector_name` |String |The ID of the connector used to send the case to
29+
{sn}. |Yes
30+
|`external_id` |String |The `incidentId` returned when calling
31+
<<cases-actions-api-execute>>. |Yes
32+
|`external_title` |String |The `number` returned when calling
33+
<<cases-actions-api-execute>>. |Yes
34+
|`external_url` |String |The `url` returned when calling
35+
<<cases-actions-api-execute>>. |Yes
36+
|==============================================
37+
38+
===== Example request
39+
40+
[source,sh]
41+
--------------------------------------------------
42+
POST api/cases/718265d0-733a-11ea-a0b2-c51ea50a58e2/_push
43+
44+
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
45+
"connector_name": "ServiceNow",
46+
"external_id": "74c15d07dbb300106ba884da0b9619a0",
47+
"external_title": "INC0010016",
48+
"external_url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=74c15d07dbb300106ba884da0b9619a0"
49+
}
50+
--------------------------------------------------
51+
// KIBANA
52+
53+
==== Response code
54+
55+
`200`::
56+
Indicates a successful call.
57+
58+
==== Response payload
59+
60+
The updated JSON case object.
61+
62+
===== Example response
63+
64+
[source,json]
65+
--------------------------------------------------
66+
{
67+
"id": "718265d0-733a-11ea-a0b2-c51ea50a58e2",
68+
"version": "WzMyNywxXQ==",
69+
"comments": [],
70+
"totalComment": 0,
71+
"closed_at": null,
72+
"closed_by": null,
73+
"created_at": "2020-03-31T10:29:03.781Z",
74+
"created_by": {
75+
"email": "[email protected]",
76+
"full_name": "Alan Hunley",
77+
"username": "ahunley"
78+
},
79+
"external_service": {
80+
"pushed_at": "2020-03-31T10:56:10.959Z",
81+
"pushed_by": {
82+
"username": "ahunley",
83+
"full_name": "Alan Hunley",
84+
"email": "[email protected]"
85+
},
86+
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
87+
"connector_name": "ServiceNow",
88+
"external_id": "74c15d07dbb300106ba884da0b9619a0",
89+
"external_title": "INC0010016",
90+
"external_url": "https://dev78437.service-now.com/nav_to.do?uri=incident.do?sys_id=74c15d07dbb300106ba884da0b9619a0"
91+
},
92+
"updated_at": "2020-03-31T10:56:10.959Z",
93+
"updated_by": {
94+
"username": "ahunley",
95+
"full_name": "Alan Hunley",
96+
"email": "[email protected]"
97+
},
98+
"title": "This case will self-destruct in 5 seconds",
99+
"tags": [],
100+
"description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
101+
"status": "open"
102+
}
103+
--------------------------------------------------

0 commit comments

Comments
 (0)