forked from splunk-soar-connectors/taniumrest
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.html
247 lines (241 loc) · 16.3 KB
/
readme.html
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
<!-- File: readme.html
Copyright (c) 2019-2021 Splunk Inc.
Licensed under Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0.txt)
-->
<h2>Playbook Backward Compatibility</h2>
<p>
<ul>
<li>The existing action parameters have been modified for the action given below. Hence, it is requested to the end-user to please update their existing playbooks by re-inserting | modifying | deleting the corresponding action blocks or by providing appropriate values to these action parameters to ensure the correct functioning of the playbooks created on the earlier versions of the app.</li>
<ul>
<li>Run Query - 3 new action parameters 'wait_for_results_processing', 'return_when_n_results_available', 'wait_for_n_results_available' are added which helps to limit the data fetched from the Tanium server.</li>
</ul>
<li> New action 'Get Question Results' has been added. Hence, it is requested to the end-user to please update their existing playbooks by inserting the corresponding action blocks for this action on the earlier versions of the app.</li>
</ul>
</p>
<h2>Asset Configuration</h2>
<li><b>Consider question results complete at (% out of 100)</b></li>
<ul>
<li>Consider Tanium question results complete at this value, a percentage out of 100. This parameter impacts the <b>run query</b> and <b>list processes</b> actions only.
Note that a similar value can be defined in Tanium user preferences – you might want to reflect the same value in your app asset configuration as you use in your Tanium user configuration.
The time spent returning your results is dependent on how much data you have on your Tanium instance and you may want your action to end with a certain percentage threshold instead of waiting for Tanium to return
100% of the results.</li>
</ul>
<h2>Permissions for Interacting with Tanium REST API</h2>
<li><b>Actions may fail if the account you are using to connect to Tanium does not have sufficient permissions.</b></li>
<br>
<ul>
<li>Computer Groups</li>
<ul>
<li>A component of Tanium permissions is the “Computer Groups” which an account can operate on.
Please ensure the account you used to configure the Tanium REST API app has access to any machines you run queries or actions on.</li>
</ul>
<br>
<li>Suggested Roles for Phantom Account in Tanium</li>
<ul>
<li>The following Tanium Roles shown below can be configured within Tanium and applied to the account used to connect to Phantom.
Note that these roles represent guidance by the Splunk Phantom team based on testing against Tanium 7.3.314.
<b>The permissions required in your environment may vary.</b></li>
<li>On Tanium 7.3.314, roles can be configured by selecting Permissions > Roles in the Tanium UI.
Roles can be applied to a user account by selecting Administration > Users > (View User) > Edit Roles in the Tanium UI.</li>
<li>Alternatively, you can <b>Import from XML</b> directly under Permissions > Roles in the Tanium UI. The XML files containing
the roles described below are attached to this app's folder.</li>
<br>
<code>
<b>Role #1 Name:</b> Phantom All Questions
<ul>
<li><b>Permissions:</b> Can Ask Question and Saved Question. Needed for run query and list processes actions. </li>
<li><b>Ask Dynamic Question:</b> Yes</li>
<li><b>Show Interact:</b> Yes</li>
<li><b>Advanced Permissions:</b> Read Sensor, Read Saved Question</li>
</ul>
<br>
<b>Role #2 Name:</b> Phantom Actions
<ul>
<li><b>Permissions:</b> Can execute actions only. Needed for execute action and terminate process.</li>
<li><b>Show Interact:</b> Yes</li>
<li><b>Advanced Permissions:</b> Read Action, Write Action, Read Package</li>
</ul>
</code>
</ul>
</ul>
<h2>Pagination</h2>
<ul>
<li>Pagination is not implemented in this release. So, the results for the actions mentioned below will be the results that are fetched in a single API call.</li>
<ul>
<li> List processes </li>
<li> List questions </li>
<li> Run query </li>
</ul>
</ul>
<h2>How to use Run Query Action</h2>
<ul>
<li>The <b>Run Query</b> action uses <b>Tanium's Interact Question Bar</b> to ask questions to retrieve information from endpoints. For example, you can ask a question that determines whether any endpoints are missing critical security patches.</li>
<li>Parameter Information:
<br>
These parameters modify questions asked using one of the two modes of operation specified below.
<ul>
<li><b>wait_for_results_processing:</b> Some long-running sensors return intermediate results with the contents "results currently unavailable", and then <a href="https://docs.tanium.com/interact/interact/results.html#:~:text=Results%20Currently%20Unavailable">later the sensor fills in the results</a>. This option instructs the App to wait until the results are returned to Tanium and only after that return the final results. The waiting is still time bounded by the <b>timeout_seconds</b> setting. </li>
<li><b>return_when_n_results_available:</b> When set, the Tanium REST App will return results to the playbook as soon as `N` results are returned, even if the <b>Consider question results complete at (% out of 100)</b> percentage has not been met. This is useful in scenarios where the playbook expects to get at most `N` results, and wants to return as soon as this occurs.</li>
<li><b>wait_for_n_results_available:</b> When set, the Tanium REST App will wait (up to the <b>timeout_seconds</b> timeout) until at least `N` results are returned. This is helpful in situations where the Tanium server is under high utilization. Sometimes the App will estimate that 100% of hosts have reported results, even when there are a few stragglers left. If the playbook author knows that it should be getting `N` results, this will wait past the <b>Consider question results complete at (% out of 100)</b> percentage.</li>
</ul>
</li>
<li>Two modes of operation are supported for the run query action:</li>
<br>
<ul>
<li>Manual Questions
<ul>
<li>Using Tanium question syntax, users can directly provide the question to be asked to the Tanium server in the <b>query_text</b> parameter.
For more information on Tanium's question syntax, <a href="https://docs.tanium.com/interact/interact/questions.html">click here.</a></li>
<li>Make sure the <b>is_saved_question</b> box is unchecked since you are providing a question from scratch.</li>
<li>Use the <b>group name</b> parameter to run your query on a particular computer group in your Tanium instance. Users can create a computer group with specific IP addresses/hostnames on the Tanium UI under Administration>Computer Groups.
For a guide on how to create/manage computer groups in Tanium, <a href="https://docs.tanium.com/platform_user/platform_user/console_computer_groups.html">click here.</a></li>
<ul>
<li>NOTE: If the <b>group_name</b> parameter is not provided, the query will be executed on all registered IP addresses/hostnames in your Tanium instance.</li>
</ul>
<br>
<li>Parameterized Query</li>
<ul>
<li>Users can provide the parameter(s) of a Parameterized query in square brackets([parameter-1, parameter-2, ..., parameter-n]).</li>
<ul>
<li>Example: Get Process Details["parameter-1","parameter-2"] from all machines with Computer Name contains localhost</li>
</ul>
<li>Users can ignore the parameter part in the query if they want the default value to be considered. Below are the 2 ways a user can achieve this:</li>
<ul>
<li>Query: Get Process Details from all machines with Computer Name contains localhost</li>
<li>Query: Get Process Details["",""] from all machines with Computer Name contains localhost</li>
</ul>
<li>If a user wants to add only one parameter out of two parameters, users can keep the parameter empty. Below are the examples:</li>
<ul>
<li>Example: Get Process Details["parameter-1",""] from all machines with Computer Name contains localhost</li>
<li>Example: Get Process Details["","parameter-2"] from all machines with Computer Name contains localhost</li>
</ul>
<li>For two or more sensors in a query, users can select one of the below:</li>
<ul>
<li>Provide value for all the parameters of all the sensors in the query</li>
<ul>
<li>Example: Get Child Processes["parameter-1"] and Process Details["parameter-2","parameter-3"] from all machines</li>
</ul>
<li>Do not provide value for any of the parameters of any of the sensors in the query</li>
<ul>
<li>Example: Get Child Processes and Process Details from all machines</li>
</ul>
<li>Provide value for the parameters you want to provide. The parameters for which you don't want to add value, please use double quotes("")</li>
<ul>
<li>Example: Get Child Processes[""] and Process Details["SHA1", ""] from all machines</li>
<li>Example: Get Child Processes["csrss.exe"] and Process Details["", ""] from all machines</li>
</ul>
</ul>
<br>
<li>Scenarios:</li>
<ol>
<li>If the Child Processes sensor expects 1 parameter and Process Details expects 2 parameters. But the user provides only 2 parameters instead of 3, then action will fail with a proper error message.</li>
<ul>
<li>Example: Get Child Processes["parameter-1"] and Process Details["parameter-2"] from all machines</li>
</ul>
<li>If the Child Processes sensor expects 1 parameter and Process Details expects 2 parameters. But the user provides more than 3 parameters, then action will fail with a proper error message.</li>
<ul>
<li>Example: Get Child Processes["parameter-1", "parameter-2"] and Process Details["parameter-3", "parameter-4"] from all machines</li>
</ul>
<li>If the Child Processes sensor expects 1 parameter and Process Details expects 2 parameters. But if the user does not provide any parameter in the Child Processes sensor and 3 parameters in Process Details sensor, then the first parameter from Process Details will be considered as the only parameter of the Child Processes sensor and the action will fetch the results accordingly.</li>
<ul>
<li>Query provided: Get Child Processes and Process Details["parameter-1", "parameter-2", "parameter-3"] from all machines</li>
<li>Query that will be executed because of API limitations: Get Child Processes["parameter-1"] and Process Details["parameter-2", "parameter-3"] from all machines</li>
</ul>
<li>If the Child Processes sensor expects 1 parameter and Process Details expects 2 parameters. But if the user provides 2 parameters in Child Processes sensor and 1 parameter in Process Details sensor, then the second parameter from Child Processes sensor will be considered as the first parameter of the Process Details sensor and the only parameter of the Process Details sensor will be considered as the second parameter of the same. The action will fetch the results accordingly.</li>
<ul>
<li>Query provided: Get Child Processes["parameter-1", "parameter-2"] and Process Details["parameter-3"] from all machines</li>
<li>Query that will be executed because of API limitations: Get Child Processes["parameter-1"] and Process Details["parameter-2", "parameter-3"] from all machines</li>
</ul>
</ol>
</ul>
<li>Example Run 1 - Get Computer Name:</li>
<ul>
<code>
<li><b>query text</b>: Get Computer Name from all machines</li>
<li><b>is saved question</b>: False</li>
<li><b>group name</b>: </li>
<li><b>timeout seconds</b>: 600</li><br>
</code>
</ul>
<li>Example Run 2 - Get Computer Name for Specified Computer Group:</li>
<ul>
<code>
<li><b>query text</b>: Get Computer Name from all machines</li>
<li><b>is saved question</b>: False</li>
<li><b>group name</b>: centos-computers</li>
<li><b>timeout seconds</b>: 600</li><br>
</code>
</ul>
<li>Example Run 3 - A Complex Query:</li>
<ul>
<code>
<li><b>query text</b>: Get Trace Executed Processes[1 month,1522723342293|1522726941293,0,0,10,0,rar.exe,"",-hp,"","",""] from all machines</li>
<li><b>is saved question</b>: False</li>
<li><b>group name</b>: </li>
<li><b>timeout seconds</b>: 600</li><br>
</code>
</ul>
<li>Example Run 4 - List Process Details for a Specified Device:</li>
<ul>
<code>
<li><b>query text</b>: Get Process Details["",""] from all machines with Computer Name contains localhost</li>
<li><b>is saved question</b>: False</li>
<li><b>group name</b>: centos-computers</li>
<li><b>timeout seconds</b>: 600</li><br>
</code>
</ul>
</ul>
<br>
<li>Saved Questions</li>
<ul>
<li>Users can create 'Saved Questions' on the Tanium UI under Content>Saved Questions and provide the name of that saved question in the <b>query_text</b> parameter to fetch appropriate results.
For a guide on how to create/manage the Saved Questions on your Tanium instance, <a href="https://docs.tanium.com/interact/interact/saving_questions.html">click here.</a></li>
<li>The <b>is_saved_question</b> box must be checked for this to work correctly.</li>
<br>
<li>Example Run:</li>
<ul>
<code>
<li><b>query text</b>: My Computers</li>
<li><b>is saved question</b>: True</li>
<li><b>timeout seconds</b>: 600</li><br>
</code>
</ul>
</ul>
</ul>
</ul>
<br>
<h2>How to use Terminate Process Action</h2>
<ul>
<li>Please follow the steps below to execute this action successfully:</li>
<ul>
<li>Create and save a package on the Tanium server with a meaningful package name and add a command to terminate the required process in the package's command section.</li>
<li>To terminate the process of particular computers, users can create a computer group with the IP address/hostname of the target computers and can specify that group name in the <b>group_name</b> parameter.</li>
<li>If the <b>group_name</b> parameter is not provided, then the terminate process action will be executed on all the registered IP addresses/hostnames.</li>
</ul>
</ul>
<br>
<h2>How to use Execute Action</h2>
<ul>
<li>The 'Execute Action' action will cause a specified Tanium Package to be executed on the specified group.</li>
<ul>
<li>Create and save a package on the Tanium server with a meaningful package name and add a command in the package's command section, or just use an existing package.</li>
<li>Any parameters required by the specified package must be supplied with a valid JSON via the <b>package_parameters</b> parameter. For example,
<code>
{"$1":"Standard_Collection", "$2":"SCP"}
</code></li>
<li>To execute this action on particular computers, users can create a computer group with the IP address/hostname of the target computers and can specify that group name in the <b>group_name</b> parameter.</li>
<li>If the <b>group_name</b> parameter is not provided, then the action will be executed on all the registered IP addresses/hostnames.</li>
<li>Example Run:</li>
<ul>
<code>
<li><b>action name</b>: Splunk Live Response Test</li>
<li><b>action group</b>: Default</li>
<li><b>package name</b>: Live Response - Linux</li>
<li><b>package parameters</b>: {"$1":"Standard_Collection", "$2":"SCP"}</li>
<li><b>group name</b>: centos-computers</li><br>
</code>
</ul>
</ul>
</ul>
</p>
<br>