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,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)
|