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.
@@ -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)