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,329 @@
1
+ """Sumo Logic adapter.
2
+
3
+ Maps detectl's canonical resources onto real Sumo Logic REST APIs, which
4
+ span two distinct API families under one base URL:
5
+
6
+ - Auth -> HTTP Basic auth using an Access ID/Access Key pair (not a
7
+ bearer token) -- sent as a standard `Authorization: Basic
8
+ <base64(id:key)>` header.
9
+ - Rules -> the Monitors Library (`/v1/monitors`), Sumo's saved-query
10
+ + trigger + notification alerting primitive. Monitors live
11
+ in a folder tree, so `create_rule` requires a destination
12
+ folder id via `rule.raw["parent_id"]` (same convention as
13
+ the CrowdStrike adapter requiring `rule.raw["rule_group_id"]`
14
+ for Custom IOA rules). Updates need the monitor's current
15
+ `version` for optimistic concurrency, so `update_rule` and
16
+ `set_rule_enabled` do a read-modify-write.
17
+ - Lists -> Cloud SIEM Match Lists (`/sec/v1/match-lists` +
18
+ `/sec/v1/match-list-items`), Sumo's suppression/allow/
19
+ block-list primitive for Cloud SIEM. Match lists have a
20
+ required `targetColumn` (what kind of value the list holds
21
+ -- IP, Domain, FileHash, ...) instead of detectl's kind
22
+ vocabulary, so `kind` is stored as a `detectl_kind:{kind}`
23
+ tag in the list's `description` field (same convention the
24
+ QRadar adapter uses for Reference Sets). Removing items
25
+ needs match-list-item IDs, not raw values, so
26
+ `remove_list_items` reads the current items to resolve
27
+ value -> id first.
28
+ - Alerts -> Cloud SIEM Insights. This is the least-verified corner of
29
+ this adapter -- Sumo's public Insights REST surface isn't
30
+ as clearly documented as Monitors/Match Lists, so the
31
+ `sec/v2/insights` paths here are a best-effort match to
32
+ the same response-enveloping convention Match Lists uses
33
+ (`{"data": {...}}` / `{"data": {"objects": [...]}}`).
34
+ Verify against your deployment's `/docs/sec/` page before
35
+ relying on this in production.
36
+ - run_query -> the Search Job API (`/v1/search/jobs`): POST to start,
37
+ poll GET until the job reports "DONE GATHERING RESULTS",
38
+ then GET `/messages` for rows -- the same
39
+ create/poll/fetch shape as the CrowdStrike adapter's
40
+ Falcon LogScale queries and the QRadar adapter's Ariel
41
+ searches, reusing the same poll_interval/max_polls knobs.
42
+ """
43
+ from __future__ import annotations
44
+
45
+ import base64
46
+ import time
47
+ from typing import Any, Dict, List, Optional
48
+
49
+ import requests
50
+
51
+ from ..exceptions import NotFoundError
52
+ from ..models import Alert, ListObject, QueryResult, Rule
53
+ from .base import SIEMAdapter
54
+
55
+ _KIND_TAG_PREFIX = "detectl_kind:"
56
+
57
+
58
+ def _kind_from_description(description: str) -> str:
59
+ for part in (description or "").split():
60
+ if part.startswith(_KIND_TAG_PREFIX):
61
+ return part[len(_KIND_TAG_PREFIX):]
62
+ return "watchlist"
63
+
64
+
65
+ def _description_for(kind: str, description: str = "") -> str:
66
+ tag = f"{_KIND_TAG_PREFIX}{kind}"
67
+ return f"{description} {tag}".strip() if description else tag
68
+
69
+
70
+ class SumoLogicAdapter(SIEMAdapter):
71
+ name = "sumologic"
72
+
73
+ def __init__(
74
+ self,
75
+ access_id: str,
76
+ access_key: str,
77
+ base_url: str = "https://api.sumologic.com/api",
78
+ poll_interval: float = 1.0,
79
+ max_polls: int = 30,
80
+ session: Optional[requests.Session] = None,
81
+ ):
82
+ self.base_url = base_url.rstrip("/")
83
+ self.poll_interval = poll_interval
84
+ self.max_polls = max_polls
85
+ self.session = session or requests.Session()
86
+ token = base64.b64encode(f"{access_id}:{access_key}".encode()).decode()
87
+ self.session.headers.setdefault("Authorization", f"Basic {token}")
88
+ self.session.headers.setdefault("Content-Type", "application/json")
89
+
90
+ # -- connectivity --------------------------------------------------
91
+ def test_connection(self) -> bool:
92
+ self._request_json("GET", f"{self.base_url}/v1/collectors", params={"limit": 1})
93
+ return True
94
+
95
+ # -- rules (Monitors Library) -------------------------------------
96
+ def _rule_from_monitor(self, entry: Dict[str, Any]) -> Rule:
97
+ queries = entry.get("queries") or []
98
+ return Rule(
99
+ id=entry.get("id"),
100
+ name=entry.get("name", ""),
101
+ query=queries[0]["query"] if queries else "",
102
+ description=entry.get("description", ""),
103
+ severity="medium",
104
+ enabled=not entry.get("isDisabled", False),
105
+ tags=list((entry.get("tags") or {}).keys()),
106
+ raw=entry,
107
+ )
108
+
109
+ def list_rules(self, **filters: Any) -> List[Rule]:
110
+ # Best-effort: Monitors Library search endpoint; assumed response
111
+ # shape `{"items": [...]}` (search-result summaries, not full
112
+ # monitor objects -- use get_rule for the full definition).
113
+ data = self._request_json(
114
+ "GET", f"{self.base_url}/v1/monitors/search", params={"query": filters.get("query", "type:Monitor")}
115
+ )
116
+ return [self._rule_from_monitor(e) for e in data.get("items", [])]
117
+
118
+ def get_rule(self, rule_id: str) -> Rule:
119
+ entry = self._request_json("GET", f"{self.base_url}/v1/monitors/{rule_id}")
120
+ return self._rule_from_monitor(entry)
121
+
122
+ def create_rule(self, rule: Rule) -> Rule:
123
+ parent_id = rule.raw.get("parent_id")
124
+ if not parent_id:
125
+ raise ValueError(
126
+ "Sumo Logic create_rule requires rule.raw['parent_id'] -- Monitors Library "
127
+ "monitors always live in a folder (there's no bare, folder-less monitor)."
128
+ )
129
+ body = {
130
+ "type": "MonitorsLibraryMonitor",
131
+ "name": rule.name,
132
+ "description": rule.description,
133
+ "monitorType": "Logs",
134
+ "queries": [{"rowId": "A", "query": rule.query}],
135
+ "triggers": [
136
+ {
137
+ "triggerType": "Critical",
138
+ "threshold": 0,
139
+ "thresholdType": "GreaterThanOrEqual",
140
+ "timeRange": "-15m",
141
+ "occurrenceType": "ResultCount",
142
+ "triggerSource": "AllResults",
143
+ "detectionMethod": "StaticCondition",
144
+ }
145
+ ],
146
+ "notifications": [],
147
+ "isDisabled": not rule.enabled,
148
+ "contentType": "Monitor",
149
+ "status": [],
150
+ "groupNotifications": False,
151
+ "tags": {},
152
+ }
153
+ entry = self._request_json(
154
+ "POST", f"{self.base_url}/v1/monitors", params={"parentId": parent_id}, json=body
155
+ )
156
+ return self._rule_from_monitor(entry)
157
+
158
+ def _update_monitor(self, rule_id: str, **patch: Any) -> Dict[str, Any]:
159
+ current = self._request_json("GET", f"{self.base_url}/v1/monitors/{rule_id}")
160
+ current.update(patch)
161
+ current["id"] = "" # cleared in the body -- the id is already in the URL
162
+ self._request("PUT", f"{self.base_url}/v1/monitors/{rule_id}", json=current)
163
+ return self._request_json("GET", f"{self.base_url}/v1/monitors/{rule_id}")
164
+
165
+ def update_rule(self, rule_id: str, rule: Rule) -> Rule:
166
+ entry = self._update_monitor(
167
+ rule_id,
168
+ name=rule.name,
169
+ description=rule.description,
170
+ queries=[{"rowId": "A", "query": rule.query}],
171
+ isDisabled=not rule.enabled,
172
+ )
173
+ return self._rule_from_monitor(entry)
174
+
175
+ def delete_rule(self, rule_id: str) -> None:
176
+ self._request("DELETE", f"{self.base_url}/v1/monitors/{rule_id}")
177
+
178
+ def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
179
+ entry = self._update_monitor(rule_id, isDisabled=not enabled)
180
+ return self._rule_from_monitor(entry)
181
+
182
+ # -- lists (Cloud SIEM Match Lists) -------------------------------------
183
+ def _list_from_entry(self, entry: Dict[str, Any], items: Optional[List[str]] = None) -> ListObject:
184
+ return ListObject(
185
+ id=entry.get("id"),
186
+ name=entry.get("name", ""),
187
+ kind=_kind_from_description(entry.get("description", "")),
188
+ description=entry.get("description", ""),
189
+ items=items or [],
190
+ raw=entry,
191
+ )
192
+
193
+ def _fetch_match_list_items(self, list_id: str) -> List[Dict[str, Any]]:
194
+ items: List[Dict[str, Any]] = []
195
+ next_page_token = ""
196
+ for _ in range(1000): # hard safety cap against a runaway pagination loop
197
+ params = {"listIds": list_id}
198
+ if next_page_token:
199
+ params["nextPageToken"] = next_page_token
200
+ data = self._request_json(
201
+ "GET", f"{self.base_url}/sec/v1/match-list-items/all", params=params
202
+ ).get("data", {})
203
+ items.extend(data.get("objects", []))
204
+ next_page_token = data.get("nextPageToken", "")
205
+ if not next_page_token:
206
+ break
207
+ return items
208
+
209
+ def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
210
+ data = self._request_json("GET", f"{self.base_url}/sec/v1/match-lists")
211
+ results = [self._list_from_entry(e) for e in data.get("data", {}).get("objects", [])]
212
+ if kind:
213
+ results = [r for r in results if r.kind == kind]
214
+ return results
215
+
216
+ def get_list(self, list_id: str) -> ListObject:
217
+ entry = self._request_json("GET", f"{self.base_url}/sec/v1/match-lists/{list_id}").get("data", {})
218
+ items = [i["value"] for i in self._fetch_match_list_items(list_id)]
219
+ return self._list_from_entry(entry, items)
220
+
221
+ def create_list(self, list_obj: ListObject) -> ListObject:
222
+ body = {
223
+ "fields": {
224
+ "name": list_obj.name,
225
+ "description": _description_for(list_obj.kind, list_obj.description),
226
+ "targetColumn": list_obj.raw.get("target_column", "Other"),
227
+ "active": True,
228
+ "defaultTtl": list_obj.raw.get("default_ttl", 86400),
229
+ }
230
+ }
231
+ entry = self._request_json("POST", f"{self.base_url}/sec/v1/match-lists", json=body).get("data", {})
232
+ if list_obj.items:
233
+ self.add_list_items(entry["id"], list_obj.items)
234
+ return self.get_list(entry["id"])
235
+
236
+ def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
237
+ # Sumo's match-lists API only allows active/defaultTtl/description to
238
+ # change after creation -- name and targetColumn are immutable.
239
+ self._request(
240
+ "PUT",
241
+ f"{self.base_url}/sec/v1/match-lists/{list_id}",
242
+ json={
243
+ "fields": {
244
+ "active": True,
245
+ "defaultTtl": list_obj.raw.get("default_ttl", 86400),
246
+ "description": _description_for(list_obj.kind, list_obj.description),
247
+ }
248
+ },
249
+ )
250
+ existing_items = [i["value"] for i in self._fetch_match_list_items(list_id)]
251
+ if existing_items:
252
+ self.remove_list_items(list_id, existing_items)
253
+ if list_obj.items:
254
+ self.add_list_items(list_id, list_obj.items)
255
+ return self.get_list(list_id)
256
+
257
+ def delete_list(self, list_id: str) -> None:
258
+ self._request("DELETE", f"{self.base_url}/sec/v1/match-lists/{list_id}")
259
+
260
+ def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
261
+ self._request(
262
+ "POST",
263
+ f"{self.base_url}/sec/v1/match-lists/{list_id}/items",
264
+ json={"items": [{"value": value} for value in items]},
265
+ )
266
+ return self.get_list(list_id)
267
+
268
+ def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
269
+ to_remove = set(items)
270
+ matching_ids = [i["id"] for i in self._fetch_match_list_items(list_id) if i.get("value") in to_remove]
271
+ if matching_ids:
272
+ self._request(
273
+ "POST",
274
+ f"{self.base_url}/sec/v1/match-list-items/bulk-delete",
275
+ json={"ids": matching_ids},
276
+ )
277
+ return self.get_list(list_id)
278
+
279
+ # -- alerts (Cloud SIEM Insights -- best-effort, see module docstring) --
280
+ def _alert_from_entry(self, entry: Dict[str, Any]) -> Alert:
281
+ return Alert(
282
+ id=entry.get("id", ""),
283
+ title=entry.get("name", entry.get("readableId", "")),
284
+ severity=str(entry.get("severity", "unknown")),
285
+ status=entry.get("status", "new"),
286
+ rule_id=entry.get("ruleId"),
287
+ timestamp=entry.get("firstSeen"),
288
+ raw=entry,
289
+ )
290
+
291
+ def list_alerts(self, **filters: Any) -> List[Alert]:
292
+ data = self._request_json(
293
+ "GET", f"{self.base_url}/sec/v2/insights", params={"limit": filters.get("limit", 100)}
294
+ )
295
+ return [self._alert_from_entry(e) for e in data.get("data", {}).get("objects", [])]
296
+
297
+ def get_alert(self, alert_id: str) -> Alert:
298
+ entry = self._request_json("GET", f"{self.base_url}/sec/v2/insights/{alert_id}").get("data", {})
299
+ if not entry:
300
+ raise NotFoundError(f"insight not found: {alert_id}")
301
+ return self._alert_from_entry(entry)
302
+
303
+ def set_alert_status(self, alert_id: str, status: str) -> Alert:
304
+ self._request(
305
+ "PUT", f"{self.base_url}/sec/v2/insights/{alert_id}/status", json={"status": status}
306
+ )
307
+ return self.get_alert(alert_id)
308
+
309
+ # -- events / raw queries (Search Job API) -----------------------------
310
+ def run_query(
311
+ self, query: str, start: Optional[str] = None, end: Optional[str] = None, limit: int = 100, **kwargs: Any
312
+ ) -> QueryResult:
313
+ body = {"query": query, "from": start or "-1h", "to": end or "now", "timeZone": "UTC"}
314
+ created = self._request_json("POST", f"{self.base_url}/v1/search/jobs", json=body)
315
+ job_id = created["id"]
316
+ status_url = f"{self.base_url}/v1/search/jobs/{job_id}"
317
+
318
+ status = self._request_json("GET", status_url)
319
+ polls = 0
320
+ while status.get("state") != "DONE GATHERING RESULTS" and polls < self.max_polls:
321
+ if self.poll_interval > 0:
322
+ time.sleep(self.poll_interval)
323
+ polls += 1
324
+ status = self._request_json("GET", status_url)
325
+
326
+ results = self._request_json("GET", f"{status_url}/messages", params={"limit": limit, "offset": 0})
327
+ rows = [m["map"] for m in results.get("messages", [])]
328
+ columns = sorted({key for row in rows for key in row.keys()})
329
+ return QueryResult(columns=columns, rows=rows, raw=results)