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,417 @@
1
+ """CrowdStrike Falcon adapter.
2
+
3
+ Maps detectl's canonical resources onto the real Falcon API surface -- which
4
+ has a notably different shape than Splunk/Elastic/Sentinel, so a few
5
+ adapter-specific conventions are documented here:
6
+
7
+ - Rules -> Custom IOA Rules, which the Falcon API always scopes to a
8
+ parent "rule group" (there's no bare, group-less rule). Since
9
+ detectl's interface addresses a rule by a single `rule_id`
10
+ string, this adapter encodes both IDs as "{rule_group_id}:
11
+ {instance_id}". A rule's condition is built from structured
12
+ `field_values`, not a single query string like SPL/KQL, so
13
+ `Rule.query` holds that structure JSON-encoded.
14
+ - Lists -> IOC (indicator) management. Falcon's IOC API has no concept of
15
+ a named list container the way Splunk KV Store or Sentinel
16
+ watchlists do -- IOCs are just individually-tagged indicators.
17
+ detectl groups them into named lists via a `detectl_list:
18
+ {name}` tag convention, and infers `kind` (allowlist/blocklist/
19
+ exclusion) from the IOC `action` field.
20
+ - Alerts -> the Falcon Alerts API (composite IDs, POST-based entity fetch,
21
+ action_parameters-based status updates -- all matching Falcon's
22
+ real API design rather than a generic REST CRUD pattern).
23
+ - Events -> the core Falcon platform API (the one this adapter otherwise
24
+ talks to) has no ad-hoc event query endpoint comparable to
25
+ Splunk SPL, Elasticsearch DSL, or Sentinel KQL -- Falcon
26
+ exposes detections/alerts/IOCs as discrete resources, not a
27
+ general query surface over raw events. Ad-hoc queries run
28
+ against Falcon LogScale instead, which is a genuinely
29
+ separate CrowdStrike product with its own base URL and its
30
+ own auth (a LogScale Personal API token, not the Falcon OAuth2
31
+ client_id/client_secret used everywhere else in this file).
32
+ run_query() only works when `logscale_url`/`logscale_token`
33
+ are configured; otherwise it raises
34
+ UnsupportedOperationError explaining why, same as before.
35
+ """
36
+ from __future__ import annotations
37
+
38
+ import json
39
+ import re
40
+ import time
41
+ from typing import Any, Dict, List, Optional
42
+
43
+ import requests
44
+
45
+ from ..exceptions import AuthenticationError, NotFoundError, UnsupportedOperationError
46
+ from ..models import Alert, ListObject, QueryResult, Rule
47
+ from .base import SIEMAdapter
48
+
49
+ _IPV4_RE = re.compile(r"^\d{1,3}(\.\d{1,3}){3}$")
50
+ _HASH_LEN_TO_TYPE = {32: "md5", 40: "sha1", 64: "sha256"}
51
+
52
+ _KIND_TO_ACTION = {
53
+ "allowlist": "allow",
54
+ "blocklist": "block",
55
+ "exclusion": "no_action",
56
+ "suppression": "no_action",
57
+ "watchlist": "detect",
58
+ "kv_store": "no_action",
59
+ }
60
+ _ACTION_TO_KIND = {v: k for k, v in _KIND_TO_ACTION.items() if k in ("allowlist", "blocklist", "watchlist")}
61
+
62
+
63
+ def _guess_ioc_type(value: str) -> str:
64
+ if _IPV4_RE.match(value):
65
+ return "ipv4"
66
+ if re.fullmatch(r"[0-9a-fA-F]+", value) and len(value) in _HASH_LEN_TO_TYPE:
67
+ return _HASH_LEN_TO_TYPE[len(value)]
68
+ return "domain"
69
+
70
+
71
+ class CrowdStrikeAdapter(SIEMAdapter):
72
+ name = "crowdstrike"
73
+
74
+ def __init__(
75
+ self,
76
+ client_id: str,
77
+ client_secret: str,
78
+ base_url: str = "https://api.crowdstrike.com",
79
+ logscale_url: Optional[str] = None,
80
+ logscale_token: Optional[str] = None,
81
+ logscale_repository: str = "search-all",
82
+ poll_interval: float = 1.0,
83
+ max_polls: int = 30,
84
+ session: Optional[requests.Session] = None,
85
+ ):
86
+ self.client_id = client_id
87
+ self.client_secret = client_secret
88
+ self.base_url = base_url.rstrip("/")
89
+ self.logscale_url = logscale_url.rstrip("/") if logscale_url else None
90
+ self.logscale_token = logscale_token
91
+ self.logscale_repository = logscale_repository
92
+ self.poll_interval = poll_interval
93
+ self.max_polls = max_polls
94
+ self.session = session or requests.Session()
95
+ self._token: Optional[str] = None
96
+ self._token_expires_at: float = 0.0
97
+
98
+ # -- auth ------------------------------------------------------------
99
+ def _headers(self) -> Dict[str, str]:
100
+ if not self._token or self._token_expires_at <= time.time() + 30:
101
+ resp = self.session.post(
102
+ f"{self.base_url}/oauth2/token",
103
+ data={"client_id": self.client_id, "client_secret": self.client_secret},
104
+ timeout=self.timeout,
105
+ )
106
+ if resp.status_code >= 400:
107
+ raise AuthenticationError(f"CrowdStrike token exchange failed: {resp.status_code} {resp.text}")
108
+ payload = resp.json()
109
+ self._token = payload["access_token"]
110
+ self._token_expires_at = time.time() + int(payload.get("expires_in", 1800))
111
+ return {"Authorization": f"Bearer {self._token}"}
112
+
113
+ # -- connectivity --------------------------------------------------
114
+ def test_connection(self) -> bool:
115
+ self._headers()
116
+ return True
117
+
118
+ # -- rules (custom IOA rules, scoped to a rule group) -----------------
119
+ def _rule_from_entry(self, group_id: str, entry: Dict[str, Any]) -> Rule:
120
+ return Rule(
121
+ id=f"{group_id}:{entry['instance_id']}",
122
+ name=entry.get("name", ""),
123
+ query=json.dumps(entry.get("field_values", [])),
124
+ description=entry.get("description", ""),
125
+ severity=entry.get("pattern_severity", "medium"),
126
+ enabled=entry.get("enabled", True),
127
+ tags=[],
128
+ raw=entry,
129
+ )
130
+
131
+ def _get_group(self, group_id: str) -> Dict[str, Any]:
132
+ data = self._request_json(
133
+ "GET",
134
+ f"{self.base_url}/ioarules/entities/rule-groups/v1",
135
+ headers=self._headers(),
136
+ params={"ids": group_id},
137
+ )
138
+ resources = data.get("resources", [])
139
+ if not resources:
140
+ raise NotFoundError(f"IOA rule group not found: {group_id}")
141
+ return resources[0]
142
+
143
+ def list_rules(self, **filters: Any) -> List[Rule]:
144
+ group_id = filters.get("rule_group_id")
145
+ if not group_id:
146
+ raise ValueError(
147
+ "CrowdStrike list_rules requires a rule_group_id filter -- Falcon custom IOA "
148
+ "rules are always scoped to a rule group (there's no bare, group-less rule)."
149
+ )
150
+ group = self._get_group(group_id)
151
+ return [self._rule_from_entry(group_id, r) for r in group.get("rules", [])]
152
+
153
+ def get_rule(self, rule_id: str) -> Rule:
154
+ group_id, _, instance_id = rule_id.partition(":")
155
+ group = self._get_group(group_id)
156
+ for entry in group.get("rules", []):
157
+ if entry["instance_id"] == instance_id:
158
+ return self._rule_from_entry(group_id, entry)
159
+ raise NotFoundError(f"IOA rule not found: {rule_id}")
160
+
161
+ def create_rule(self, rule: Rule) -> Rule:
162
+ group_id = rule.raw.get("rule_group_id")
163
+ if not group_id:
164
+ raise ValueError("CrowdStrike create_rule requires rule.raw['rule_group_id']")
165
+ try:
166
+ field_values = json.loads(rule.query) if rule.query else []
167
+ except json.JSONDecodeError:
168
+ field_values = []
169
+ body = {
170
+ "rulegroup_id": group_id,
171
+ "name": rule.name,
172
+ "description": rule.description,
173
+ "pattern_severity": rule.severity,
174
+ "disposition_id": 20, # "detect"
175
+ "field_values": field_values,
176
+ "enabled": rule.enabled,
177
+ }
178
+ data = self._request_json(
179
+ "POST", f"{self.base_url}/ioarules/entities/rules/v1", headers=self._headers(), json=body
180
+ )
181
+ instance_id = data["resources"][0]["instance_id"]
182
+ return self.get_rule(f"{group_id}:{instance_id}")
183
+
184
+ def update_rule(self, rule_id: str, rule: Rule) -> Rule:
185
+ group_id, _, instance_id = rule_id.partition(":")
186
+ try:
187
+ field_values = json.loads(rule.query) if rule.query else []
188
+ except json.JSONDecodeError:
189
+ field_values = []
190
+ body = {
191
+ "rulegroup_id": group_id,
192
+ "instance_id": instance_id,
193
+ "name": rule.name,
194
+ "description": rule.description,
195
+ "pattern_severity": rule.severity,
196
+ "field_values": field_values,
197
+ "enabled": rule.enabled,
198
+ }
199
+ self._request("PATCH", f"{self.base_url}/ioarules/entities/rules/v1", headers=self._headers(), json=body)
200
+ return self.get_rule(rule_id)
201
+
202
+ def delete_rule(self, rule_id: str) -> None:
203
+ group_id, _, instance_id = rule_id.partition(":")
204
+ self._request(
205
+ "DELETE",
206
+ f"{self.base_url}/ioarules/entities/rules/v1",
207
+ headers=self._headers(),
208
+ params={"ids": instance_id, "rule_group_id": group_id},
209
+ )
210
+
211
+ def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
212
+ current = self.get_rule(rule_id)
213
+ current.enabled = enabled
214
+ return self.update_rule(rule_id, current)
215
+
216
+ # -- lists (IOCs grouped by a detectl_list:{name} tag) -----------------
217
+ def _iocs_by_list_name(self) -> Dict[str, List[Dict[str, Any]]]:
218
+ ids = self._request_json(
219
+ "GET",
220
+ f"{self.base_url}/iocs/queries/indicators/v1",
221
+ headers=self._headers(),
222
+ params={"filter": "tags:'detectl_list:*'", "limit": 5000},
223
+ ).get("resources", [])
224
+ if not ids:
225
+ return {}
226
+ details = self._request_json(
227
+ "GET", f"{self.base_url}/iocs/entities/indicators/v1", headers=self._headers(), params={"ids": ids}
228
+ ).get("resources", [])
229
+ grouped: Dict[str, List[Dict[str, Any]]] = {}
230
+ for ioc in details:
231
+ for tag in ioc.get("tags", []):
232
+ if tag.startswith("detectl_list:"):
233
+ grouped.setdefault(tag.split(":", 1)[1], []).append(ioc)
234
+ return grouped
235
+
236
+ @staticmethod
237
+ def _derive_kind(iocs: List[Dict[str, Any]]) -> str:
238
+ if not iocs:
239
+ return "exclusion"
240
+ action = iocs[0].get("action", "no_action")
241
+ return _ACTION_TO_KIND.get(action, "exclusion")
242
+
243
+ def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
244
+ grouped = self._iocs_by_list_name()
245
+ results = []
246
+ for name, iocs in grouped.items():
247
+ derived_kind = self._derive_kind(iocs)
248
+ if kind and derived_kind != kind:
249
+ continue
250
+ results.append(
251
+ ListObject(id=name, name=name, kind=derived_kind, items=[i["value"] for i in iocs], raw={"iocs": iocs})
252
+ )
253
+ return results
254
+
255
+ def get_list(self, list_id: str) -> ListObject:
256
+ grouped = self._iocs_by_list_name()
257
+ iocs = grouped.get(list_id)
258
+ if iocs is None:
259
+ raise NotFoundError(f"IOC list not found: {list_id}")
260
+ return ListObject(id=list_id, name=list_id, kind=self._derive_kind(iocs), items=[i["value"] for i in iocs], raw={"iocs": iocs})
261
+
262
+ def create_list(self, list_obj: ListObject) -> ListObject:
263
+ if list_obj.items:
264
+ self._add_iocs(list_obj.name, list_obj.kind, list_obj.items, list_obj.description)
265
+ return self.get_list(list_obj.name)
266
+
267
+ def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
268
+ existing = self.list_lists()
269
+ current = next((l for l in existing if l.id == list_id), None)
270
+ if current and current.items:
271
+ self.remove_list_items(list_id, current.items)
272
+ if list_obj.items:
273
+ self._add_iocs(list_id, list_obj.kind, list_obj.items, list_obj.description)
274
+ return self.get_list(list_id)
275
+
276
+ def delete_list(self, list_id: str) -> None:
277
+ grouped = self._iocs_by_list_name()
278
+ iocs = grouped.get(list_id, [])
279
+ if iocs:
280
+ self._request(
281
+ "DELETE",
282
+ f"{self.base_url}/iocs/entities/indicators/v1",
283
+ headers=self._headers(),
284
+ params={"ids": [i["id"] for i in iocs]},
285
+ )
286
+
287
+ def _add_iocs(self, list_name: str, kind: str, items: List[str], description: str = "") -> None:
288
+ action = _KIND_TO_ACTION.get(kind, "no_action")
289
+ indicators = [
290
+ {
291
+ "type": _guess_ioc_type(value),
292
+ "value": value,
293
+ "action": action,
294
+ "severity": "medium",
295
+ "description": description,
296
+ "tags": [f"detectl_list:{list_name}"],
297
+ }
298
+ for value in items
299
+ ]
300
+ self._request(
301
+ "POST",
302
+ f"{self.base_url}/iocs/entities/indicators/v1",
303
+ headers=self._headers(),
304
+ json={"indicators": indicators},
305
+ )
306
+
307
+ def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
308
+ existing = self.get_list(list_id)
309
+ self._add_iocs(list_id, existing.kind, items)
310
+ return self.get_list(list_id)
311
+
312
+ def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
313
+ grouped = self._iocs_by_list_name()
314
+ iocs = grouped.get(list_id, [])
315
+ to_remove = set(items)
316
+ matching_ids = [i["id"] for i in iocs if i["value"] in to_remove]
317
+ if matching_ids:
318
+ self._request(
319
+ "DELETE",
320
+ f"{self.base_url}/iocs/entities/indicators/v1",
321
+ headers=self._headers(),
322
+ params={"ids": matching_ids},
323
+ )
324
+ return self.get_list(list_id)
325
+
326
+ # -- alerts ------------------------------------------------------------
327
+ def _alert_from_entry(self, entry: Dict[str, Any]) -> Alert:
328
+ return Alert(
329
+ id=entry["composite_id"],
330
+ title=entry.get("display_name", entry.get("name", "")),
331
+ severity=str(entry.get("severity_name", entry.get("severity", "unknown"))),
332
+ status=entry.get("status", "new"),
333
+ rule_id=entry.get("detect_id") or entry.get("pattern_id"),
334
+ timestamp=entry.get("timestamp"),
335
+ raw=entry,
336
+ )
337
+
338
+ def list_alerts(self, **filters: Any) -> List[Alert]:
339
+ ids = self._request_json(
340
+ "GET",
341
+ f"{self.base_url}/alerts/queries/alerts/v2",
342
+ headers=self._headers(),
343
+ params={"limit": filters.get("limit", 100)},
344
+ ).get("resources", [])
345
+ if not ids:
346
+ return []
347
+ details = self._request_json(
348
+ "POST",
349
+ f"{self.base_url}/alerts/entities/alerts/v2",
350
+ headers=self._headers(),
351
+ json={"composite_ids": ids},
352
+ ).get("resources", [])
353
+ return [self._alert_from_entry(a) for a in details]
354
+
355
+ def get_alert(self, alert_id: str) -> Alert:
356
+ details = self._request_json(
357
+ "POST",
358
+ f"{self.base_url}/alerts/entities/alerts/v2",
359
+ headers=self._headers(),
360
+ json={"composite_ids": [alert_id]},
361
+ ).get("resources", [])
362
+ if not details:
363
+ raise NotFoundError(f"alert not found: {alert_id}")
364
+ return self._alert_from_entry(details[0])
365
+
366
+ def set_alert_status(self, alert_id: str, status: str) -> Alert:
367
+ self._request(
368
+ "PATCH",
369
+ f"{self.base_url}/alerts/entities/alerts/v2",
370
+ headers=self._headers(),
371
+ json={
372
+ "composite_ids": [alert_id],
373
+ "action_parameters": [{"name": "update_status", "value": status}],
374
+ },
375
+ )
376
+ return self.get_alert(alert_id)
377
+
378
+ # -- events / raw queries (Falcon LogScale, not the Falcon platform API) --
379
+ def _logscale_headers(self) -> Dict[str, str]:
380
+ return {"Authorization": f"Bearer {self.logscale_token}"}
381
+
382
+ def run_query(
383
+ self,
384
+ query: str,
385
+ start: Optional[str] = None,
386
+ end: Optional[str] = None,
387
+ limit: int = 100,
388
+ repository: Optional[str] = None,
389
+ **kwargs: Any,
390
+ ) -> QueryResult:
391
+ if not self.logscale_url or not self.logscale_token:
392
+ raise UnsupportedOperationError(
393
+ "The core Falcon platform API has no ad-hoc event query endpoint comparable "
394
+ "to Splunk SPL, Elasticsearch Query DSL, or Sentinel KQL -- but Falcon LogScale "
395
+ "(a separate CrowdStrike product/API) does. Configure `logscale_url` and "
396
+ "`logscale_token` (or CROWDSTRIKE_LOGSCALE_URL / CROWDSTRIKE_LOGSCALE_TOKEN) to "
397
+ "enable it; a LogScale Personal API token is a different credential than the "
398
+ "Falcon client_id/client_secret used for rules/lists/alerts."
399
+ )
400
+
401
+ repo = repository or self.logscale_repository
402
+ body: Dict[str, Any] = {"queryString": query, "start": start or "1hour", "end": end or "now"}
403
+ jobs_url = f"{self.logscale_url}/api/v1/repositories/{repo}/queryjobs"
404
+ created = self._request_json("POST", jobs_url, headers=self._logscale_headers(), json=body)
405
+ job_url = f"{jobs_url}/{created['id']}"
406
+
407
+ result = self._request_json("GET", job_url, headers=self._logscale_headers())
408
+ polls = 0
409
+ while not result.get("done", False) and polls < self.max_polls:
410
+ if self.poll_interval > 0:
411
+ time.sleep(self.poll_interval)
412
+ polls += 1
413
+ result = self._request_json("GET", job_url, headers=self._logscale_headers())
414
+
415
+ events = result.get("events", [])[:limit]
416
+ columns = sorted({key for event in events for key in event.keys()})
417
+ return QueryResult(columns=columns, rows=events, raw=result)