forked from splunk-soar-connectors/splunk
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathreadme.html
More file actions
350 lines (343 loc) · 17.3 KB
/
Copy pathreadme.html
File metadata and controls
350 lines (343 loc) · 17.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
<!-- File: readme.html
Copyright (c) 2016-2022 Splunk Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language governing permissions
and limitations under the License.
-->
<html>
<head></head>
<body>
<p><h2>App's Token-Based Authentication Workflow</p></h2>
<ul>
<li> This app also supports API token based authentication.</li>
<li> Please follow the steps mentioned in this <a href="https://docs.splunk.com/Documentation/Splunk/9.0.0/Security/CreateAuthTokens" target="_blank">documentation</a> to generate an API token.</li>
<b>NOTE -</b>
If the username/password and API token are both provided then the API token will be given preference and a token-based authentication workflow will be used.
</ul>
<p>
<h2>Splunk-SDK</h2>
This app uses the Splunk-SDK module, which is licensed under the Apache Software License, Copyright (c) 2011-2019 Splunk, Inc.
</p>
<h2>State File Permissions</h2>
Please check the permissions for the state file as mentioned below.
<h4>State Filepath</h4>
<ul>
<li>For Non-NRI Instance: /opt/phantom/local_data/app_states/91883aa8-9c81-470b-97a1-5d8f7995f560/{asset_id}_state.json</li>
<li>For NRI Instance: /phantomcyber/local_data/app_states/91883aa8-9c81-470b-97a1-5d8f7995f560/{asset_id}_state.json</li>
</ul>
<h4>State File Permissions</h4>
<ul>
<li>File Rights: rw-rw-r-- (664) (The phantom user should have read and write access for the state file)</li>
<li>File Owner: appropriate phantom user</li>
</ul>
<h2> Asset Configuration Parameters </h2>
<ul>
<li>
container_name_prefix:
<ul>
<li>Name to give containers created via ingestion</li>
<li>User can select a field name from the events data</li>
<ul>
<li>If the provided field exists, then container_name_prefix will be the value against the provided field from the events data</li>
<li>If the provided field does not exist, then container_name_prefix will be the provided field name itself</li>
</ul>
<li>If the container_name_prefix parameter is not provided:</li>
<ul>
<li>If the event data contains '_time' field, then container_name_prefix will be 'Splunk Log Entry on <value of the _time field>'</li>
<li>If the event data does not contain '_time' field, then container_name_prefix will be 'Splunk Log Entry'</li>
</ul>
<li>Users can provide a string. Example: Test title
</ul>
</li>
<li>
container_name_values:
<ul>
<li>Values to append to the container name created via ingestion</li>
<li>User can provide CIM fields</li>
<li>If the container_name_values parameter is provided:</li>
<ul>
<li>If the provided field exists, then container_name_values will be the value against the provided CIM field or its CIM field mapping from the events data</li>
<li>If neither a CIM field mapping nor CIM field itself is present in the event data, then container_name_values will be the CIM field mapping or CIM field</li>
</ul>
<li>If the container_name_values parameter is not provided:</li>
<ul>
<li>If 'container_name_prefix' parameter is not provided, then container_name_values will be 'source'</li>
<li>If 'container_name_prefix' parameter is provided, then container_name_values will be empty</li>
</ul>
<li>Users can provide a comma-separated string. Example: test1, test2
</ul>
</li>
<li>
Container count to update the state file:
<ul>
<li>This parameter will allow the user to specify the number of containers and will only be used in scheduled or interval polling</li>
<li>Everytime the count of the containers reaches the count provided by the user, the "start_time" stored in the state file will be updated by the index time of that event</li>
<li>The default value is 100</li>
</ul>
</li>
<li>
splunk_app:
<ul>
<li>The app context of the namespace</li>
<li>As per Splunk SDK's documentation, if the splunk_app parameter is not provided, then "system" will be considered as splunk_app</li>
</ul>
</li>
<li>
splunk_owner:
<ul>
<li>The owner context of the namespace</li>
<li>As per Splunk SDK's documentation, if the splunk_owner parameter is not provided, then "nobody" will be considered as splunk_owner</li>
</ul>
</li>
<li>
retry_count:
<ul>
<li>Number of retries</li>
<li>To ask a query to the Splunk server using the splunklib library, first, the query asked by the user is to be parsed. Then, this parsed query is used to create a job and once this job is ready the results are ready to be fetched.
So while performing any of the above steps, if any exception occurs then, the code will retry that step for the number of retries provided in the "retry count" configuration parameter.</li>
<li>It will also be used if an error or an exception occurs while posting the data in the "post data" action or modifying the event in the "update event" action.</li>
</ul>
</li>
<li>
remove_empty_cef:
<ul>
<li>Remove CEF fields having empty values from the artifact</li>
<li>It allows the user to remove CEF fields having empty values from the artifact during ingestion. If the value of the parameter is 'true', CEF fields having empty values will be removed.</li>
</ul>
</li>
<li>
sleeptime_in_requests:
<ul>
<li>The time to wait for next REST call(max 120 seconds)</li>
<li>It allows the user to add sleep time between the REST calls while performing the "run_query",
"update_event", "get host events" and "on poll" action.</li>
</ul>
</li>
<li>
on_poll_display:
<ul>
<li>Fields to save with On Poll</li>
<li>Users can select the fields from the events which the user wants to ingest in the artifact</li>
<li>If the on_poll_display parameter is not provided, then all the fields that are extracted from the events will be ingested in the respective artifacts</li>
<li>Users can provide comma-separated field names. Example: field1, field2, field3</li>
</ul>
</li>
<li>
If the on_poll_query(query to use with On Poll) parameter is not provided, then an error message will be returned<br>
</li>
<li>
If the on_poll_command(command for the query to use with On Poll) parameter is not provided and the on_poll_query does not start with "|" or "search", then the "search" keyword is added at the beginning of the on_poll_query<br>
Example:
<ul>
<li>
on_poll_command: None<br>
on_poll_query: index = "main"<br>
Final query generated internally: search index = "main"
</li>
</ul>
</li>
<li>
If the on_poll_command parameter is not provided and the on_poll_query starts with "|" or "search", then the final query would be the same as the query provided in the on_poll_query parameter<br>
Example:
<ul>
<li>
on_poll_command: None<br>
on_poll_query: search index = "main"<br>
Final query generated internally: search index = "main"
</li>
</ul>
</li>
<li>
If on_poll_command parameter is provided, then query is formed as: {on_poll_command} {on_poll_query}<br>
Example:
<ul>
<li>
on_poll_command: search<br>
on_poll_query: index = "main"<br>
Final query generated internally: search index = "main"
</li>
</ul>
</li>
</ul>
<h2> Update Event </h2>
<ul>
<li>To execute this action successfully, the minimum role required is "ess_analyst", but the user can have other roles too.</li>
<li>If the <b>wait_for_confirmation</b> parameter is False (which is the default), it will be faster but there will be no confirmation that the notable ID corresponded with an actual notable event. Setting it to True will cause the action to take longer because it will require an SPL search, but it will provide more assurance that the update took place.</li>
<li>The action updates the event for the provided "event_id". If the <b>wait_for_confirmation</b> parameter is True, the action validates the "event_id" provided by the user using the search command: 'search `notable` | search event_id="<event_id>"'.</li>
<ul>
<li>If this search command returns more than 0 results, the action updates the event.</li>
<li>If this search command does not return any results then, the action fails with the message "Please provide a valid event ID".</li>
</ul>
<li>Use integer status field for custom status. Example: 1 For New, 2 for In progress, etc.</li>
</ul>
<h2> On Poll </h2>
<ul>
<li>There are two approaches to polling as mentioned below.</li>
<ul>
<li>POLL NOW (Manual polling)</li>
<ul>
<li>
It will fetch the data every time as per the corresponding asset configuration parameters. It doesn’t store the last run context of the fetched data.
</li>
</ul>
<li>Scheduled/Interval Polling</li>
<ul>
<li>The ingestion action will be triggered after each specified time interval. It stores the last run context of the fetched data and starts fetching new data based on the combination of the values of stored context for the previous ingestion run and the corresponding asset configuration parameters.</li>
</ul>
</ul>
<li>Notes</li>
<ul>
<li>
In case "on poll" returns any 4XX except 403, validate your search Query on Splunk
</li>
<li>
Sample "Query" to use with On Poll: index="_internal" | stats count by host, source, sourcetype | head 5 | rename host as h0st | rename source as devicehostname
</li>
<li>
Sample "Fields to save with On Poll" (if not provided, "on poll" will store all the fields): source,sourcetype,hostname
</li>
<li>
For the <b>on_poll_parse_only</b> parameter, if <b>True</b>, disables the expansion of search due to evaluation of sub-searches, time term expansion, lookups, tags, eventtypes, and sourcetype aliases. This parameter is used for the validation of the Splunk query before fetching the results
</li>
<li>
If multiple severities are returned for the incident in the "on poll" action, then the highest "severity" will be given priority. If the "severity" is not present in the incident, then the "urgency" of the incident will be considered. If the "urgency" is also not present, then the ingested container "severity" will be taken as "medium" by default.
</li>
</ul>
<br>
<li>Helpful examples to run on poll</li>
<ol>
<li>
The query will fetch top 10 events from the result of index = "main" search.
</li>
<ul>
<li>on_poll_command: "search"<br></li>
<li>on_poll_query: index = "main" | head 10<br></li>
<li>Final query generated internally: search index = "main" | head 10<br></li>
</ul>
<li>
The query will execute the query saved in the savedsearch named "Dashboard Views - Action History".
</li>
<ul>
<li>on_poll_command: "savedsearch"<br></li>
<li>on_poll_query: "Dashboard Views - Action History"<br></li>
<li>Final query generated internally: savedsearch "Dashboard Views - Action History"<br></li>
</ul>
<li>
The query will perform statistics for datamodel and will give total count of events fetched for datamodel = authentication.
</li>
<ul>
<li>on_poll_command: "tstats"<br></li>
<li>on_poll_query: "count from datamodel=Authentication"<br></li>
<li>Final query generated internally: "tstats count from datamodel=Authentication"<br></li>
</ul>
<li>
The query will display field "a" in table format for the results fetched from 'search index = "_internal"' search.
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index = "_internal" | table a<br></li>
<li>Final query generated internally: search index = "_internal" | table a<br></li>
</ul>
<li>
This query will fetch all the events with sourcetype = "modular_alerts:notable", app="phantom", and user="admin".
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index=* sourcetype="modular_alerts:notable" app="phantom" user="admin"<br></li>
<li>Final query generated internally: search index=* sourcetype="modular_alerts:notable" app="phantom" user="admin"<br></li>
</ul>
<li>
This query will get the count of the events that are indexed in index named "main".
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index="main" | stats count<br></li>
<li>Final query generated internally: search index="main" | stats count<br></li>
</ul>
<li>
This query will add a field with name = "a" and value = "abc" in all the events that are indexed in index named "main".
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index="main" | eval a = "abc"<br></li>
<li>Final query generated internally: search index="main" | eval a = "abc"<br></li>
</ul>
<li>
This query will fetch only the sourcetype of all the events that are indexed in index named "main".
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index="main" | fields sourcetype<br></li>
<li>Final query generated internally: search index="main" | fields sourcetype<br></li>
</ul>
<li>
This query will fetch all the events having tag = error and index = main.
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: index="_internal" tag=error<br></li>
<li>Final query generated internally: search index="_internal" tag="error"<br></li>
</ul>
<li>
This query will show the data of "ppf_action_history_searches" lookup.
</li>
<ul>
<li>on_poll_command: None<br></li>
<li>on_poll_query: |inputlookup ppf_action_history_searches<br></li>
<li>Final query generated internally: |inputlookup ppf_action_history_searches<br></li>
</ul>
</ol>
</ul>
<h2>Naming Ingested Containers</h2>
<p>
By default, the "source" field is used to name the ingested containers.
To customize the container names, use the two settings in the asset configuration.
For example, if a hostname is expected in the container name, the "Name to give containers created via ingestion" parameter
can be set to "Notable Splunk Event" and "Values to append to container name" parameter can be set to "host".
This will set the container name to "Notable Splunk Event, host=my.sample.host".
The appended values can be a comma-separated list.
</p>
<h2>Special characters present in the Splunk query can affect the output</h2>
<p>
The user must use appropriate special characters in the query according to individual use-case otherwise the query will end up providing unexpected results. Following is a list of several such special characters:
<ul>
<li>Non-breaking space</li>
<li>Soft hyphen</li>
<li>Micro symbol</li>
<li>Division symbol</li>
<li>Non-breaking hyphen</li>
<li>En dash</li>
<li>Em dash</li>
<li>Ellipsis</li>
</ul>
There can exist more such characters apart from the ones listed above.
</p>
<h2>Port Information</h2>
<p>
The app uses HTTP/ HTTPS protocol for communicating with the Splunk server. Below are the default ports used by Splunk SOAR.
<table>
<tr class=plain>
<th> SERVICE NAME</th>
<th>TRANSPORT PROTOCOL</th>
<th>PORT</th>
</tr>
<tr>
<td> http</td>
<td>tcp</td>
<td>80</td>
</tr>
<tr>
<td> https</td>
<td>tcp</td>
<td>443</td>
</tr>
</table>
</p>
8089 is the default port used by Splunk Server.
</body>
</html>