detectl 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- detectl/__init__.py +11 -0
- detectl/__main__.py +4 -0
- detectl/adapters/__init__.py +32 -0
- detectl/adapters/base.py +160 -0
- detectl/adapters/chronicle.py +298 -0
- detectl/adapters/crowdstrike.py +417 -0
- detectl/adapters/elastic.py +275 -0
- detectl/adapters/qradar.py +236 -0
- detectl/adapters/sentinel.py +356 -0
- detectl/adapters/splunk.py +272 -0
- detectl/adapters/sumologic.py +329 -0
- detectl/cli.py +449 -0
- detectl/config.py +121 -0
- detectl/exceptions.py +37 -0
- detectl/models.py +57 -0
- detectl-0.2.0.dist-info/METADATA +318 -0
- detectl-0.2.0.dist-info/RECORD +21 -0
- detectl-0.2.0.dist-info/WHEEL +5 -0
- detectl-0.2.0.dist-info/entry_points.txt +2 -0
- detectl-0.2.0.dist-info/licenses/LICENSE +21 -0
- detectl-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
"""Microsoft Sentinel adapter.
|
|
2
|
+
|
|
3
|
+
Maps detectl's canonical resources onto Sentinel's real Azure Resource
|
|
4
|
+
Manager (ARM) surface plus the separate Log Analytics query API:
|
|
5
|
+
|
|
6
|
+
- Rules -> Scheduled Analytics Rules
|
|
7
|
+
(Microsoft.SecurityInsights/alertRules)
|
|
8
|
+
- Lists -> Watchlists
|
|
9
|
+
(Microsoft.SecurityInsights/watchlists, .../watchlistItems)
|
|
10
|
+
- Alerts -> Incidents
|
|
11
|
+
(Microsoft.SecurityInsights/incidents)
|
|
12
|
+
- run_query -> Log Analytics workspace query API (KQL), a completely
|
|
13
|
+
separate host/token scope from the ARM management API --
|
|
14
|
+
both are OAuth2 client-credentials tokens against the same
|
|
15
|
+
Azure AD app registration, just for different resources.
|
|
16
|
+
|
|
17
|
+
ARM resources are managed via idempotent PUT (create == update, matching
|
|
18
|
+
Azure's own convention), except partial updates like status/enabled toggles
|
|
19
|
+
which use PATCH where the API supports it.
|
|
20
|
+
"""
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import time
|
|
24
|
+
import uuid
|
|
25
|
+
from typing import Any, Dict, List, Optional
|
|
26
|
+
|
|
27
|
+
import requests
|
|
28
|
+
|
|
29
|
+
from ..exceptions import AuthenticationError
|
|
30
|
+
from ..models import Alert, ListObject, QueryResult, Rule
|
|
31
|
+
from .base import SIEMAdapter
|
|
32
|
+
|
|
33
|
+
_API_VERSION = "2023-11-01"
|
|
34
|
+
_LOGIN_BASE = "https://login.microsoftonline.com"
|
|
35
|
+
_LOGANALYTICS_BASE = "https://api.loganalytics.io"
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class SentinelAdapter(SIEMAdapter):
|
|
39
|
+
name = "sentinel"
|
|
40
|
+
|
|
41
|
+
def __init__(
|
|
42
|
+
self,
|
|
43
|
+
tenant_id: str,
|
|
44
|
+
client_id: str,
|
|
45
|
+
client_secret: str,
|
|
46
|
+
subscription_id: str,
|
|
47
|
+
resource_group: str,
|
|
48
|
+
workspace_name: str,
|
|
49
|
+
workspace_id: str,
|
|
50
|
+
base_url: str = "https://management.azure.com",
|
|
51
|
+
session: Optional[requests.Session] = None,
|
|
52
|
+
):
|
|
53
|
+
self.tenant_id = tenant_id
|
|
54
|
+
self.client_id = client_id
|
|
55
|
+
self.client_secret = client_secret
|
|
56
|
+
self.subscription_id = subscription_id
|
|
57
|
+
self.resource_group = resource_group
|
|
58
|
+
self.workspace_name = workspace_name
|
|
59
|
+
self.workspace_id = workspace_id
|
|
60
|
+
self.base_url = base_url.rstrip("/")
|
|
61
|
+
self.session = session or requests.Session()
|
|
62
|
+
self._tokens: Dict[str, Dict[str, Any]] = {}
|
|
63
|
+
|
|
64
|
+
# -- auth ------------------------------------------------------------
|
|
65
|
+
def _get_token(self, scope: str) -> str:
|
|
66
|
+
cached = self._tokens.get(scope)
|
|
67
|
+
if cached and cached["expires_at"] > time.time() + 30:
|
|
68
|
+
return cached["access_token"]
|
|
69
|
+
|
|
70
|
+
resp = self.session.post(
|
|
71
|
+
f"{_LOGIN_BASE}/{self.tenant_id}/oauth2/v2.0/token",
|
|
72
|
+
data={
|
|
73
|
+
"grant_type": "client_credentials",
|
|
74
|
+
"client_id": self.client_id,
|
|
75
|
+
"client_secret": self.client_secret,
|
|
76
|
+
"scope": scope,
|
|
77
|
+
},
|
|
78
|
+
timeout=self.timeout,
|
|
79
|
+
)
|
|
80
|
+
if resp.status_code >= 400:
|
|
81
|
+
raise AuthenticationError(f"token exchange for scope {scope} failed: {resp.status_code} {resp.text}")
|
|
82
|
+
payload = resp.json()
|
|
83
|
+
self._tokens[scope] = {
|
|
84
|
+
"access_token": payload["access_token"],
|
|
85
|
+
"expires_at": time.time() + int(payload.get("expires_in", 3600)),
|
|
86
|
+
}
|
|
87
|
+
return payload["access_token"]
|
|
88
|
+
|
|
89
|
+
def _mgmt_headers(self) -> Dict[str, str]:
|
|
90
|
+
return {"Authorization": f"Bearer {self._get_token('https://management.azure.com/.default')}"}
|
|
91
|
+
|
|
92
|
+
def _loganalytics_headers(self) -> Dict[str, str]:
|
|
93
|
+
return {"Authorization": f"Bearer {self._get_token(f'{_LOGANALYTICS_BASE}/.default')}"}
|
|
94
|
+
|
|
95
|
+
@property
|
|
96
|
+
def _workspace_path(self) -> str:
|
|
97
|
+
return (
|
|
98
|
+
f"/subscriptions/{self.subscription_id}/resourceGroups/{self.resource_group}"
|
|
99
|
+
f"/providers/Microsoft.OperationalInsights/workspaces/{self.workspace_name}"
|
|
100
|
+
f"/providers/Microsoft.SecurityInsights"
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
def _list_all_pages(self, url: str) -> List[Dict[str, Any]]:
|
|
104
|
+
items: List[Dict[str, Any]] = []
|
|
105
|
+
params = {"api-version": _API_VERSION}
|
|
106
|
+
headers = self._mgmt_headers()
|
|
107
|
+
while url:
|
|
108
|
+
data = self._request_json("GET", url, headers=headers, params=params)
|
|
109
|
+
items.extend(data.get("value", []))
|
|
110
|
+
url = data.get("nextLink")
|
|
111
|
+
params = {} # nextLink is already a fully-qualified URL with its own query string
|
|
112
|
+
return items
|
|
113
|
+
|
|
114
|
+
# -- connectivity --------------------------------------------------
|
|
115
|
+
def test_connection(self) -> bool:
|
|
116
|
+
self._get_token("https://management.azure.com/.default")
|
|
117
|
+
return True
|
|
118
|
+
|
|
119
|
+
# -- rules (analytics rules) -------------------------------------------
|
|
120
|
+
def _rule_from_item(self, item: Dict[str, Any]) -> Rule:
|
|
121
|
+
props = item.get("properties", {})
|
|
122
|
+
return Rule(
|
|
123
|
+
id=item["name"],
|
|
124
|
+
name=props.get("displayName", ""),
|
|
125
|
+
query=props.get("query", ""),
|
|
126
|
+
description=props.get("description", ""),
|
|
127
|
+
severity=props.get("severity", "Medium").lower(),
|
|
128
|
+
enabled=props.get("enabled", True),
|
|
129
|
+
tags=props.get("tactics", []),
|
|
130
|
+
raw=item,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
def list_rules(self, **filters: Any) -> List[Rule]:
|
|
134
|
+
items = self._list_all_pages(f"{self.base_url}{self._workspace_path}/alertRules")
|
|
135
|
+
return [self._rule_from_item(i) for i in items]
|
|
136
|
+
|
|
137
|
+
def get_rule(self, rule_id: str) -> Rule:
|
|
138
|
+
item = self._request_json(
|
|
139
|
+
"GET",
|
|
140
|
+
f"{self.base_url}{self._workspace_path}/alertRules/{rule_id}",
|
|
141
|
+
headers=self._mgmt_headers(),
|
|
142
|
+
params={"api-version": _API_VERSION},
|
|
143
|
+
)
|
|
144
|
+
return self._rule_from_item(item)
|
|
145
|
+
|
|
146
|
+
def _put_rule(self, rule_id: str, rule: Rule, enabled: Optional[bool] = None) -> Rule:
|
|
147
|
+
body = {
|
|
148
|
+
"kind": "Scheduled",
|
|
149
|
+
"properties": {
|
|
150
|
+
"displayName": rule.name,
|
|
151
|
+
"description": rule.description,
|
|
152
|
+
"severity": rule.severity.capitalize(),
|
|
153
|
+
"enabled": rule.enabled if enabled is None else enabled,
|
|
154
|
+
"query": rule.query,
|
|
155
|
+
"queryFrequency": "PT1H",
|
|
156
|
+
"queryPeriod": "PT1H",
|
|
157
|
+
"triggerOperator": "GreaterThan",
|
|
158
|
+
"triggerThreshold": 0,
|
|
159
|
+
"tactics": rule.tags,
|
|
160
|
+
},
|
|
161
|
+
}
|
|
162
|
+
item = self._request_json(
|
|
163
|
+
"PUT",
|
|
164
|
+
f"{self.base_url}{self._workspace_path}/alertRules/{rule_id}",
|
|
165
|
+
headers=self._mgmt_headers(),
|
|
166
|
+
params={"api-version": _API_VERSION},
|
|
167
|
+
json=body,
|
|
168
|
+
)
|
|
169
|
+
return self._rule_from_item(item)
|
|
170
|
+
|
|
171
|
+
def create_rule(self, rule: Rule) -> Rule:
|
|
172
|
+
rule_id = rule.id or str(uuid.uuid4())
|
|
173
|
+
return self._put_rule(rule_id, rule)
|
|
174
|
+
|
|
175
|
+
def update_rule(self, rule_id: str, rule: Rule) -> Rule:
|
|
176
|
+
return self._put_rule(rule_id, rule)
|
|
177
|
+
|
|
178
|
+
def delete_rule(self, rule_id: str) -> None:
|
|
179
|
+
self._request(
|
|
180
|
+
"DELETE",
|
|
181
|
+
f"{self.base_url}{self._workspace_path}/alertRules/{rule_id}",
|
|
182
|
+
headers=self._mgmt_headers(),
|
|
183
|
+
params={"api-version": _API_VERSION},
|
|
184
|
+
)
|
|
185
|
+
|
|
186
|
+
def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
|
|
187
|
+
current = self.get_rule(rule_id)
|
|
188
|
+
return self._put_rule(rule_id, current, enabled=enabled)
|
|
189
|
+
|
|
190
|
+
# -- lists (watchlists) ------------------------------------------------
|
|
191
|
+
def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
|
|
192
|
+
if kind not in (None, "watchlist"):
|
|
193
|
+
return []
|
|
194
|
+
items = self._list_all_pages(f"{self.base_url}{self._workspace_path}/watchlists")
|
|
195
|
+
return [
|
|
196
|
+
ListObject(
|
|
197
|
+
id=i["name"],
|
|
198
|
+
name=i.get("properties", {}).get("displayName", i["name"]),
|
|
199
|
+
kind="watchlist",
|
|
200
|
+
description=i.get("properties", {}).get("description", ""),
|
|
201
|
+
items=[],
|
|
202
|
+
raw=i,
|
|
203
|
+
)
|
|
204
|
+
for i in items
|
|
205
|
+
]
|
|
206
|
+
|
|
207
|
+
def get_list(self, list_id: str) -> ListObject:
|
|
208
|
+
container = self._request_json(
|
|
209
|
+
"GET",
|
|
210
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}",
|
|
211
|
+
headers=self._mgmt_headers(),
|
|
212
|
+
params={"api-version": _API_VERSION},
|
|
213
|
+
)
|
|
214
|
+
raw_items = self._list_all_pages(f"{self.base_url}{self._workspace_path}/watchlists/{list_id}/watchlistItems")
|
|
215
|
+
items = [str((i.get("properties", {}).get("itemsKeyValue", {}) or {}).get("value", i)) for i in raw_items]
|
|
216
|
+
props = container.get("properties", {})
|
|
217
|
+
return ListObject(
|
|
218
|
+
id=list_id,
|
|
219
|
+
name=props.get("displayName", list_id),
|
|
220
|
+
kind="watchlist",
|
|
221
|
+
description=props.get("description", ""),
|
|
222
|
+
items=items,
|
|
223
|
+
raw=container,
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
def create_list(self, list_obj: ListObject) -> ListObject:
|
|
227
|
+
list_id = list_obj.id or list_obj.name.lower().replace(" ", "-")
|
|
228
|
+
body = {
|
|
229
|
+
"properties": {
|
|
230
|
+
"displayName": list_obj.name,
|
|
231
|
+
"description": list_obj.description,
|
|
232
|
+
"provider": "detectl",
|
|
233
|
+
"source": "Local file",
|
|
234
|
+
"itemsSearchKey": "value",
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
self._request(
|
|
238
|
+
"PUT",
|
|
239
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}",
|
|
240
|
+
headers=self._mgmt_headers(),
|
|
241
|
+
params={"api-version": _API_VERSION},
|
|
242
|
+
json=body,
|
|
243
|
+
)
|
|
244
|
+
if list_obj.items:
|
|
245
|
+
self.add_list_items(list_id, list_obj.items)
|
|
246
|
+
return self.get_list(list_id)
|
|
247
|
+
|
|
248
|
+
def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
|
|
249
|
+
body = {
|
|
250
|
+
"properties": {
|
|
251
|
+
"displayName": list_obj.name,
|
|
252
|
+
"description": list_obj.description,
|
|
253
|
+
"provider": "detectl",
|
|
254
|
+
"source": "Local file",
|
|
255
|
+
"itemsSearchKey": "value",
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
self._request(
|
|
259
|
+
"PUT",
|
|
260
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}",
|
|
261
|
+
headers=self._mgmt_headers(),
|
|
262
|
+
params={"api-version": _API_VERSION},
|
|
263
|
+
json=body,
|
|
264
|
+
)
|
|
265
|
+
existing = self.get_list(list_id)
|
|
266
|
+
if existing.items:
|
|
267
|
+
self.remove_list_items(list_id, existing.items)
|
|
268
|
+
if list_obj.items:
|
|
269
|
+
self.add_list_items(list_id, list_obj.items)
|
|
270
|
+
return self.get_list(list_id)
|
|
271
|
+
|
|
272
|
+
def delete_list(self, list_id: str) -> None:
|
|
273
|
+
self._request(
|
|
274
|
+
"DELETE",
|
|
275
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}",
|
|
276
|
+
headers=self._mgmt_headers(),
|
|
277
|
+
params={"api-version": _API_VERSION},
|
|
278
|
+
)
|
|
279
|
+
|
|
280
|
+
def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
281
|
+
for value in items:
|
|
282
|
+
item_id = str(uuid.uuid4())
|
|
283
|
+
self._request(
|
|
284
|
+
"PUT",
|
|
285
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}/watchlistItems/{item_id}",
|
|
286
|
+
headers=self._mgmt_headers(),
|
|
287
|
+
params={"api-version": _API_VERSION},
|
|
288
|
+
json={"properties": {"itemsKeyValue": {"value": value}}},
|
|
289
|
+
)
|
|
290
|
+
return self.get_list(list_id)
|
|
291
|
+
|
|
292
|
+
def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
293
|
+
raw_items = self._list_all_pages(f"{self.base_url}{self._workspace_path}/watchlists/{list_id}/watchlistItems")
|
|
294
|
+
to_remove = set(items)
|
|
295
|
+
for entry in raw_items:
|
|
296
|
+
value = (entry.get("properties", {}).get("itemsKeyValue", {}) or {}).get("value")
|
|
297
|
+
if str(value) in to_remove:
|
|
298
|
+
self._request(
|
|
299
|
+
"DELETE",
|
|
300
|
+
f"{self.base_url}{self._workspace_path}/watchlists/{list_id}/watchlistItems/{entry['name']}",
|
|
301
|
+
headers=self._mgmt_headers(),
|
|
302
|
+
params={"api-version": _API_VERSION},
|
|
303
|
+
)
|
|
304
|
+
return self.get_list(list_id)
|
|
305
|
+
|
|
306
|
+
# -- alerts (incidents) ------------------------------------------------
|
|
307
|
+
def _alert_from_item(self, item: Dict[str, Any]) -> Alert:
|
|
308
|
+
props = item.get("properties", {})
|
|
309
|
+
return Alert(
|
|
310
|
+
id=item["name"],
|
|
311
|
+
title=props.get("title", ""),
|
|
312
|
+
severity=props.get("severity", "Medium").lower(),
|
|
313
|
+
status=props.get("status", "New"),
|
|
314
|
+
rule_id=None,
|
|
315
|
+
timestamp=props.get("createdTimeUtc"),
|
|
316
|
+
raw=item,
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
def list_alerts(self, **filters: Any) -> List[Alert]:
|
|
320
|
+
items = self._list_all_pages(f"{self.base_url}{self._workspace_path}/incidents")
|
|
321
|
+
return [self._alert_from_item(i) for i in items]
|
|
322
|
+
|
|
323
|
+
def get_alert(self, alert_id: str) -> Alert:
|
|
324
|
+
item = self._request_json(
|
|
325
|
+
"GET",
|
|
326
|
+
f"{self.base_url}{self._workspace_path}/incidents/{alert_id}",
|
|
327
|
+
headers=self._mgmt_headers(),
|
|
328
|
+
params={"api-version": _API_VERSION},
|
|
329
|
+
)
|
|
330
|
+
return self._alert_from_item(item)
|
|
331
|
+
|
|
332
|
+
def set_alert_status(self, alert_id: str, status: str) -> Alert:
|
|
333
|
+
item = self._request_json(
|
|
334
|
+
"PATCH",
|
|
335
|
+
f"{self.base_url}{self._workspace_path}/incidents/{alert_id}",
|
|
336
|
+
headers=self._mgmt_headers(),
|
|
337
|
+
params={"api-version": _API_VERSION},
|
|
338
|
+
json={"properties": {"status": status}},
|
|
339
|
+
)
|
|
340
|
+
return self._alert_from_item(item)
|
|
341
|
+
|
|
342
|
+
# -- events / raw queries (Log Analytics KQL) --------------------------
|
|
343
|
+
def run_query(self, query: str, limit: int = 100, **kwargs: Any) -> QueryResult:
|
|
344
|
+
resp = self._request_json(
|
|
345
|
+
"POST",
|
|
346
|
+
f"{_LOGANALYTICS_BASE}/v1/workspaces/{self.workspace_id}/query",
|
|
347
|
+
headers=self._loganalytics_headers(),
|
|
348
|
+
json={"query": query},
|
|
349
|
+
)
|
|
350
|
+
tables = resp.get("tables", [])
|
|
351
|
+
if not tables:
|
|
352
|
+
return QueryResult(columns=[], rows=[], raw=resp)
|
|
353
|
+
table = tables[0]
|
|
354
|
+
columns = [c["name"] for c in table.get("columns", [])]
|
|
355
|
+
rows = [dict(zip(columns, row)) for row in table.get("rows", [])[:limit]]
|
|
356
|
+
return QueryResult(columns=columns, rows=rows, raw=resp)
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
"""Splunk adapter.
|
|
2
|
+
|
|
3
|
+
Maps detectl's canonical resources onto real Splunk REST API endpoints:
|
|
4
|
+
|
|
5
|
+
- Rules -> Saved Searches / correlation searches
|
|
6
|
+
(servicesNS/{owner}/{app}/saved/searches)
|
|
7
|
+
- Lists -> KV Store collections
|
|
8
|
+
(servicesNS/{owner}/{app}/storage/collections/{config,data})
|
|
9
|
+
- Alerts -> Fired alerts
|
|
10
|
+
(servicesNS/{owner}/{app}/alerts/fired_alerts)
|
|
11
|
+
- run_query -> a blocking search job (search/jobs, exec_mode=blocking)
|
|
12
|
+
followed by a results fetch -- the standard pattern for
|
|
13
|
+
synchronous, script-driven Splunk searches.
|
|
14
|
+
|
|
15
|
+
Every request goes through HttpMixin._request[_json], which centralizes
|
|
16
|
+
auth/HTTP error translation. All endpoints are called with output_mode=json.
|
|
17
|
+
"""
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from typing import Any, Dict, List, Optional
|
|
21
|
+
|
|
22
|
+
import requests
|
|
23
|
+
|
|
24
|
+
from ..exceptions import NotFoundError, UnsupportedOperationError
|
|
25
|
+
from ..models import Alert, ListObject, QueryResult, Rule
|
|
26
|
+
from .base import SIEMAdapter
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class SplunkAdapter(SIEMAdapter):
|
|
30
|
+
name = "splunk"
|
|
31
|
+
|
|
32
|
+
def __init__(
|
|
33
|
+
self,
|
|
34
|
+
base_url: str,
|
|
35
|
+
token: str,
|
|
36
|
+
owner: str = "nobody",
|
|
37
|
+
app: str = "search",
|
|
38
|
+
verify_ssl: bool = True,
|
|
39
|
+
session: Optional[requests.Session] = None,
|
|
40
|
+
):
|
|
41
|
+
self.base_url = base_url.rstrip("/")
|
|
42
|
+
self.owner = owner
|
|
43
|
+
self.app = app
|
|
44
|
+
self.session = session or requests.Session()
|
|
45
|
+
self.session.headers.setdefault("Authorization", f"Splunk {token}")
|
|
46
|
+
self.session.verify = verify_ssl
|
|
47
|
+
|
|
48
|
+
# -- helpers -----------------------------------------------------
|
|
49
|
+
@property
|
|
50
|
+
def _ns(self) -> str:
|
|
51
|
+
return f"{self.base_url}/servicesNS/{self.owner}/{self.app}"
|
|
52
|
+
|
|
53
|
+
@staticmethod
|
|
54
|
+
def _normalize_search(query: str) -> str:
|
|
55
|
+
q = query.strip()
|
|
56
|
+
if q.startswith("search ") or q.startswith("|") or q.startswith("search\n"):
|
|
57
|
+
return q
|
|
58
|
+
return f"search {q}"
|
|
59
|
+
|
|
60
|
+
def _rule_from_entry(self, entry: Dict[str, Any]) -> Rule:
|
|
61
|
+
content = entry.get("content", {})
|
|
62
|
+
return Rule(
|
|
63
|
+
id=entry["name"],
|
|
64
|
+
name=entry["name"],
|
|
65
|
+
query=content.get("search", ""),
|
|
66
|
+
description=content.get("description", "") or "",
|
|
67
|
+
severity=content.get("alert_severity", "medium"),
|
|
68
|
+
enabled=not bool(int(content.get("disabled", 0))),
|
|
69
|
+
tags=[],
|
|
70
|
+
raw=entry,
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
# -- connectivity --------------------------------------------------
|
|
74
|
+
def test_connection(self) -> bool:
|
|
75
|
+
self._request_json("GET", f"{self.base_url}/services/server/info", params={"output_mode": "json"})
|
|
76
|
+
return True
|
|
77
|
+
|
|
78
|
+
# -- rules -----------------------------------------------------------
|
|
79
|
+
def list_rules(self, **filters: Any) -> List[Rule]:
|
|
80
|
+
data = self._request_json(
|
|
81
|
+
"GET", f"{self._ns}/saved/searches", params={"output_mode": "json", "count": 0}
|
|
82
|
+
)
|
|
83
|
+
return [self._rule_from_entry(e) for e in data.get("entry", [])]
|
|
84
|
+
|
|
85
|
+
def get_rule(self, rule_id: str) -> Rule:
|
|
86
|
+
data = self._request_json(
|
|
87
|
+
"GET", f"{self._ns}/saved/searches/{rule_id}", params={"output_mode": "json"}
|
|
88
|
+
)
|
|
89
|
+
return self._rule_from_entry(data["entry"][0])
|
|
90
|
+
|
|
91
|
+
def create_rule(self, rule: Rule) -> Rule:
|
|
92
|
+
payload = {
|
|
93
|
+
"name": rule.name,
|
|
94
|
+
"search": rule.query,
|
|
95
|
+
"description": rule.description,
|
|
96
|
+
"disabled": 0 if rule.enabled else 1,
|
|
97
|
+
}
|
|
98
|
+
self._request("POST", f"{self._ns}/saved/searches", data=payload, params={"output_mode": "json"})
|
|
99
|
+
return self.get_rule(rule.name)
|
|
100
|
+
|
|
101
|
+
def update_rule(self, rule_id: str, rule: Rule) -> Rule:
|
|
102
|
+
payload = {
|
|
103
|
+
"search": rule.query,
|
|
104
|
+
"description": rule.description,
|
|
105
|
+
"disabled": 0 if rule.enabled else 1,
|
|
106
|
+
}
|
|
107
|
+
self._request(
|
|
108
|
+
"POST", f"{self._ns}/saved/searches/{rule_id}", data=payload, params={"output_mode": "json"}
|
|
109
|
+
)
|
|
110
|
+
return self.get_rule(rule_id)
|
|
111
|
+
|
|
112
|
+
def delete_rule(self, rule_id: str) -> None:
|
|
113
|
+
self._request("DELETE", f"{self._ns}/saved/searches/{rule_id}", params={"output_mode": "json"})
|
|
114
|
+
|
|
115
|
+
def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
|
|
116
|
+
action = "enable" if enabled else "disable"
|
|
117
|
+
self._request(
|
|
118
|
+
"POST", f"{self._ns}/saved/searches/{rule_id}/{action}", params={"output_mode": "json"}
|
|
119
|
+
)
|
|
120
|
+
return self.get_rule(rule_id)
|
|
121
|
+
|
|
122
|
+
# -- lists (KV Store collections) -------------------------------------
|
|
123
|
+
def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
|
|
124
|
+
if kind not in (None, "kv_store"):
|
|
125
|
+
return []
|
|
126
|
+
data = self._request_json(
|
|
127
|
+
"GET",
|
|
128
|
+
f"{self._ns}/storage/collections/config",
|
|
129
|
+
params={"output_mode": "json", "count": 0},
|
|
130
|
+
)
|
|
131
|
+
return [
|
|
132
|
+
ListObject(id=e["name"], name=e["name"], kind="kv_store", items=[], raw=e)
|
|
133
|
+
for e in data.get("entry", [])
|
|
134
|
+
]
|
|
135
|
+
|
|
136
|
+
def get_list(self, list_id: str) -> ListObject:
|
|
137
|
+
cfg = self._request_json(
|
|
138
|
+
"GET", f"{self._ns}/storage/collections/config/{list_id}", params={"output_mode": "json"}
|
|
139
|
+
)
|
|
140
|
+
records = self._request_json(
|
|
141
|
+
"GET", f"{self._ns}/storage/collections/data/{list_id}", params={"output_mode": "json"}
|
|
142
|
+
)
|
|
143
|
+
items = [str(r.get("value", r)) for r in (records or [])]
|
|
144
|
+
return ListObject(id=list_id, name=list_id, kind="kv_store", items=items, raw=cfg["entry"][0])
|
|
145
|
+
|
|
146
|
+
def create_list(self, list_obj: ListObject) -> ListObject:
|
|
147
|
+
self._request(
|
|
148
|
+
"POST",
|
|
149
|
+
f"{self._ns}/storage/collections/config",
|
|
150
|
+
data={"name": list_obj.name},
|
|
151
|
+
params={"output_mode": "json"},
|
|
152
|
+
)
|
|
153
|
+
if list_obj.items:
|
|
154
|
+
self.add_list_items(list_obj.name, list_obj.items)
|
|
155
|
+
return self.get_list(list_obj.name)
|
|
156
|
+
|
|
157
|
+
def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
|
|
158
|
+
# KV Store collections have no "rename"/"replace description" concept
|
|
159
|
+
# via this API -- update semantics here mean "replace the item set".
|
|
160
|
+
self._request(
|
|
161
|
+
"DELETE", f"{self._ns}/storage/collections/data/{list_id}", params={"output_mode": "json"}
|
|
162
|
+
)
|
|
163
|
+
if list_obj.items:
|
|
164
|
+
self.add_list_items(list_id, list_obj.items)
|
|
165
|
+
return self.get_list(list_id)
|
|
166
|
+
|
|
167
|
+
def delete_list(self, list_id: str) -> None:
|
|
168
|
+
self._request(
|
|
169
|
+
"DELETE", f"{self._ns}/storage/collections/config/{list_id}", params={"output_mode": "json"}
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
173
|
+
for item in items:
|
|
174
|
+
self._request(
|
|
175
|
+
"POST",
|
|
176
|
+
f"{self._ns}/storage/collections/data/{list_id}",
|
|
177
|
+
json={"value": item},
|
|
178
|
+
params={"output_mode": "json"},
|
|
179
|
+
)
|
|
180
|
+
return self.get_list(list_id)
|
|
181
|
+
|
|
182
|
+
def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
183
|
+
records = self._request_json(
|
|
184
|
+
"GET", f"{self._ns}/storage/collections/data/{list_id}", params={"output_mode": "json"}
|
|
185
|
+
)
|
|
186
|
+
to_remove = set(items)
|
|
187
|
+
for record in records or []:
|
|
188
|
+
if str(record.get("value")) in to_remove and "_key" in record:
|
|
189
|
+
self._request(
|
|
190
|
+
"DELETE",
|
|
191
|
+
f"{self._ns}/storage/collections/data/{list_id}/{record['_key']}",
|
|
192
|
+
params={"output_mode": "json"},
|
|
193
|
+
)
|
|
194
|
+
return self.get_list(list_id)
|
|
195
|
+
|
|
196
|
+
# -- alerts (fired alerts) -------------------------------------------
|
|
197
|
+
def list_alerts(self, **filters: Any) -> List[Alert]:
|
|
198
|
+
data = self._request_json(
|
|
199
|
+
"GET", f"{self._ns}/alerts/fired_alerts", params={"output_mode": "json", "count": 0}
|
|
200
|
+
)
|
|
201
|
+
alerts: List[Alert] = []
|
|
202
|
+
for group in data.get("entry", []):
|
|
203
|
+
group_name = group["name"]
|
|
204
|
+
instances = self._request_json(
|
|
205
|
+
"GET", f"{self._ns}/alerts/fired_alerts/{group_name}", params={"output_mode": "json"}
|
|
206
|
+
)
|
|
207
|
+
for inst in instances.get("entry", []):
|
|
208
|
+
content = inst.get("content", {})
|
|
209
|
+
alerts.append(
|
|
210
|
+
Alert(
|
|
211
|
+
id=f"{group_name}:{inst['name']}",
|
|
212
|
+
title=group_name,
|
|
213
|
+
severity=content.get("severity", "unknown"),
|
|
214
|
+
status="fired",
|
|
215
|
+
rule_id=group_name,
|
|
216
|
+
timestamp=content.get("trigger_time"),
|
|
217
|
+
raw=inst,
|
|
218
|
+
)
|
|
219
|
+
)
|
|
220
|
+
return alerts
|
|
221
|
+
|
|
222
|
+
def get_alert(self, alert_id: str) -> Alert:
|
|
223
|
+
group_name, _, instance_name = alert_id.partition(":")
|
|
224
|
+
instances = self._request_json(
|
|
225
|
+
"GET", f"{self._ns}/alerts/fired_alerts/{group_name}", params={"output_mode": "json"}
|
|
226
|
+
)
|
|
227
|
+
for inst in instances.get("entry", []):
|
|
228
|
+
if inst["name"] == instance_name:
|
|
229
|
+
content = inst.get("content", {})
|
|
230
|
+
return Alert(
|
|
231
|
+
id=alert_id,
|
|
232
|
+
title=group_name,
|
|
233
|
+
severity=content.get("severity", "unknown"),
|
|
234
|
+
status="fired",
|
|
235
|
+
rule_id=group_name,
|
|
236
|
+
timestamp=content.get("trigger_time"),
|
|
237
|
+
raw=inst,
|
|
238
|
+
)
|
|
239
|
+
raise NotFoundError(f"fired alert instance not found: {alert_id}")
|
|
240
|
+
|
|
241
|
+
def set_alert_status(self, alert_id: str, status: str) -> Alert:
|
|
242
|
+
# Splunk's fired_alerts API has no ack/close/status concept the way
|
|
243
|
+
# Elastic signals or Sentinel incidents do -- be honest about it.
|
|
244
|
+
raise UnsupportedOperationError(
|
|
245
|
+
"Splunk fired alerts have no settable status field via the REST API "
|
|
246
|
+
"(no ack/close concept, unlike Elastic signals or Sentinel incidents)."
|
|
247
|
+
)
|
|
248
|
+
|
|
249
|
+
# -- events / raw queries ---------------------------------------------
|
|
250
|
+
def run_query(self, query: str, start: Optional[str] = None, end: Optional[str] = None, limit: int = 100, **kwargs: Any) -> QueryResult:
|
|
251
|
+
job_payload: Dict[str, Any] = {
|
|
252
|
+
"search": self._normalize_search(query),
|
|
253
|
+
"exec_mode": "blocking",
|
|
254
|
+
}
|
|
255
|
+
if start:
|
|
256
|
+
job_payload["earliest_time"] = start
|
|
257
|
+
if end:
|
|
258
|
+
job_payload["latest_time"] = end
|
|
259
|
+
|
|
260
|
+
created = self._request_json(
|
|
261
|
+
"POST", f"{self._ns}/search/jobs", data=job_payload, params={"output_mode": "json"}
|
|
262
|
+
)
|
|
263
|
+
sid = created["sid"]
|
|
264
|
+
|
|
265
|
+
results = self._request_json(
|
|
266
|
+
"GET",
|
|
267
|
+
f"{self._ns}/search/jobs/{sid}/results",
|
|
268
|
+
params={"output_mode": "json", "count": limit},
|
|
269
|
+
)
|
|
270
|
+
rows = results.get("results", [])
|
|
271
|
+
columns = [f["name"] for f in results.get("fields", [])] or (list(rows[0].keys()) if rows else [])
|
|
272
|
+
return QueryResult(columns=columns, rows=rows, raw=results)
|