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 ADDED
@@ -0,0 +1,11 @@
1
+ """detectl -- a CLI and Python library for interacting with multiple SIEM/EDR
2
+ platforms through a single, consistent interface.
3
+
4
+ Each supported platform is implemented as a self-contained adapter module
5
+ under detectl.adapters, all implementing the same abstract interface
6
+ (detectl.adapters.base.SIEMAdapter) for detection rules, tuning lists
7
+ (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
8
+ alerts, and raw event queries.
9
+ """
10
+
11
+ __version__ = "0.1.0"
detectl/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
@@ -0,0 +1,32 @@
1
+ """Adapter registry and factory."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+ from typing import Optional
6
+
7
+ from ..config import load_config
8
+ from .base import SIEMAdapter
9
+ from .chronicle import ChronicleAdapter
10
+ from .crowdstrike import CrowdStrikeAdapter
11
+ from .elastic import ElasticAdapter
12
+ from .qradar import QRadarAdapter
13
+ from .sentinel import SentinelAdapter
14
+ from .splunk import SplunkAdapter
15
+ from .sumologic import SumoLogicAdapter
16
+
17
+ REGISTRY = {
18
+ "splunk": SplunkAdapter,
19
+ "elastic": ElasticAdapter,
20
+ "sentinel": SentinelAdapter,
21
+ "crowdstrike": CrowdStrikeAdapter,
22
+ "qradar": QRadarAdapter,
23
+ "sumologic": SumoLogicAdapter,
24
+ "chronicle": ChronicleAdapter,
25
+ }
26
+
27
+
28
+ def get_adapter(platform: str, config_path: Optional[Path] = None) -> SIEMAdapter:
29
+ if platform not in REGISTRY:
30
+ raise ValueError(f"unknown platform: {platform!r} (choices: {', '.join(sorted(REGISTRY))})")
31
+ kwargs = load_config(platform, config_path)
32
+ return REGISTRY[platform](**kwargs)
@@ -0,0 +1,160 @@
1
+ """Abstract adapter interface every platform adapter implements, plus a
2
+ small shared HTTP helper mixin so concrete adapters don't each reimplement
3
+ error handling around `requests`.
4
+ """
5
+ from __future__ import annotations
6
+
7
+ from abc import ABC, abstractmethod
8
+ from typing import Any, Dict, List, Optional
9
+
10
+ import requests
11
+
12
+ from ..exceptions import APIError, AuthenticationError, NotFoundError
13
+ from ..models import Alert, ListObject, QueryResult, Rule
14
+
15
+
16
+ class HttpMixin:
17
+ """Thin wrapper around a `requests.Session` with consistent error
18
+ translation. Adapters call `self._request(...)` instead of using
19
+ `self.session` directly, so tests can inject a fake `session` object
20
+ (see tests/adapters/*.py) without ever hitting the network."""
21
+
22
+ session: requests.Session
23
+ timeout: float = 30.0
24
+
25
+ def _request(self, method: str, url: str, **kwargs) -> requests.Response:
26
+ kwargs.setdefault("timeout", self.timeout)
27
+ try:
28
+ resp = self.session.request(method, url, **kwargs)
29
+ except requests.RequestException as exc: # network-level failure
30
+ raise APIError(f"{method} {url} failed: {exc}") from exc
31
+
32
+ if resp.status_code == 401 or resp.status_code == 403:
33
+ raise AuthenticationError(
34
+ f"{method} {url} -> {resp.status_code}: authentication/authorization failed"
35
+ )
36
+ if resp.status_code == 404:
37
+ raise NotFoundError(f"{method} {url} -> 404 not found")
38
+ if resp.status_code >= 400:
39
+ raise APIError(
40
+ f"{method} {url} -> {resp.status_code}",
41
+ status_code=resp.status_code,
42
+ body=resp.text,
43
+ )
44
+ return resp
45
+
46
+ def _request_json(self, method: str, url: str, **kwargs) -> Any:
47
+ resp = self._request(method, url, **kwargs)
48
+ if not resp.content:
49
+ return None
50
+ return resp.json()
51
+
52
+
53
+ class SIEMAdapter(HttpMixin, ABC):
54
+ """Common interface for every SIEM/EDR platform adapter.
55
+
56
+ Resource categories, matching what a detection engineer actually tunes
57
+ day to day: rules (detections), lists (watchlists / exclusion lists /
58
+ allow-block lists / suppression lists / KV stores), alerts, and raw
59
+ event/query access for ad-hoc investigation.
60
+
61
+ Not every platform has a clean equivalent for every operation -- when
62
+ that's genuinely true (e.g. CrowdStrike has no generic ad-hoc query
63
+ language), the adapter should raise UnsupportedOperationError rather
64
+ than faking support.
65
+ """
66
+
67
+ name: str
68
+
69
+ # -- connectivity ------------------------------------------------
70
+ @abstractmethod
71
+ def test_connection(self) -> bool:
72
+ """Return True if credentials/connectivity are valid, else raise."""
73
+
74
+ # -- rules ---------------------------------------------------------
75
+ @abstractmethod
76
+ def list_rules(self, **filters: Any) -> List[Rule]:
77
+ ...
78
+
79
+ @abstractmethod
80
+ def get_rule(self, rule_id: str) -> Rule:
81
+ ...
82
+
83
+ @abstractmethod
84
+ def create_rule(self, rule: Rule) -> Rule:
85
+ ...
86
+
87
+ @abstractmethod
88
+ def update_rule(self, rule_id: str, rule: Rule) -> Rule:
89
+ ...
90
+
91
+ @abstractmethod
92
+ def delete_rule(self, rule_id: str) -> None:
93
+ ...
94
+
95
+ @abstractmethod
96
+ def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
97
+ ...
98
+
99
+ def enable_rule(self, rule_id: str) -> Rule:
100
+ return self.set_rule_enabled(rule_id, True)
101
+
102
+ def disable_rule(self, rule_id: str) -> Rule:
103
+ return self.set_rule_enabled(rule_id, False)
104
+
105
+ # -- lists (watchlists / exclusion / allow-block / suppression / kv) --
106
+ @abstractmethod
107
+ def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
108
+ ...
109
+
110
+ @abstractmethod
111
+ def get_list(self, list_id: str) -> ListObject:
112
+ ...
113
+
114
+ @abstractmethod
115
+ def create_list(self, list_obj: ListObject) -> ListObject:
116
+ ...
117
+
118
+ @abstractmethod
119
+ def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
120
+ ...
121
+
122
+ @abstractmethod
123
+ def delete_list(self, list_id: str) -> None:
124
+ ...
125
+
126
+ @abstractmethod
127
+ def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
128
+ ...
129
+
130
+ @abstractmethod
131
+ def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
132
+ ...
133
+
134
+ # -- alerts ----------------------------------------------------------
135
+ @abstractmethod
136
+ def list_alerts(self, **filters: Any) -> List[Alert]:
137
+ ...
138
+
139
+ @abstractmethod
140
+ def get_alert(self, alert_id: str) -> Alert:
141
+ ...
142
+
143
+ @abstractmethod
144
+ def set_alert_status(self, alert_id: str, status: str) -> Alert:
145
+ ...
146
+
147
+ # -- events / raw queries --------------------------------------------
148
+ @abstractmethod
149
+ def run_query(self, query: str, **kwargs: Any) -> QueryResult:
150
+ """Execute a raw, platform-native query (SPL / ES DSL / KQL / ...)
151
+ and return normalized results. Adapters with no ad-hoc query
152
+ capability should raise UnsupportedOperationError."""
153
+
154
+ def search_events(
155
+ self, query: str, start: Optional[str] = None, end: Optional[str] = None, limit: int = 100
156
+ ) -> QueryResult:
157
+ """Convenience wrapper around run_query for time-bounded event
158
+ search. Default implementation just forwards to run_query; adapters
159
+ can override if their time-filtering needs special handling."""
160
+ return self.run_query(query, start=start, end=end, limit=limit)
@@ -0,0 +1,298 @@
1
+ """Google Security Operations (Chronicle) adapter.
2
+
3
+ Maps detectl's canonical resources onto the real Chronicle API
4
+ (`https://{location}-chronicle.googleapis.com/v1beta/...`), a standard
5
+ GCP-style resource-hierarchy REST API under
6
+ `projects/{project}/locations/{location}/instances/{instance}/...`.
7
+
8
+ - Auth -> standard Google OAuth2, which for a service account means
9
+ signing a JWT with an RSA private key and exchanging it for
10
+ a bearer token -- real crypto, not something worth
11
+ reimplementing in a dependency-light, clean-room REST
12
+ client. This adapter instead takes an already-obtained
13
+ `access_token` (e.g. from `gcloud auth print-access-token`
14
+ against a service account, or your own token-refresh
15
+ cron), the same way you'd script against any Google Cloud
16
+ API from a lightweight client without pulling in the
17
+ google-auth SDK.
18
+ - Rules -> `rules` (the YARA-L rule text lives in the `text` field --
19
+ this is exactly what sigmux's `chronicle` backend emits,
20
+ see "Pairs well with sigmux" in the README) plus a
21
+ *separate* nested `rules/{id}/deployment` singleton
22
+ resource that controls whether the rule is actually live
23
+ (`enabled`). A freshly-created rule isn't live until its
24
+ deployment is patched, so `create_rule`/`update_rule` both
25
+ sync the deployment's `enabled` field after writing `text`.
26
+ - Lists -> `referenceLists`. No native "kind" concept, so (same
27
+ convention as the QRadar/Sumo Logic adapters) `kind` is
28
+ stored as a `detectl_kind:{kind}` tag in `description`.
29
+ Reference lists have no per-item add/remove endpoint --
30
+ `entries` is patched as a whole array -- and, per Google's
31
+ own Terraform provider source, **reference lists cannot be
32
+ deleted via the API at all** ("will be removed from
33
+ Terraform state, but will still be present on Google
34
+ Cloud"), so `delete_list` raises UnsupportedOperationError
35
+ rather than silently no-op'ing.
36
+ - Alerts -> Detections, which only exist scoped to the rule that
37
+ generated them (there's no bare, rule-less detection), so
38
+ `list_alerts` requires a `rule_id` filter (same convention
39
+ as the CrowdStrike adapter requiring `rule_group_id` for
40
+ Custom IOA rules) and `get_alert` IDs are encoded as
41
+ `"{rule_id}:{detection_id}"`. This is the least-verified
42
+ corner of this adapter -- Chronicle's detections REST
43
+ surface is thinner in public docs than rules/referenceLists
44
+ -- and detection triage/status lives in Chronicle's
45
+ separate SOAR/case-management module, not a simple status
46
+ field here, so `set_alert_status` raises
47
+ UnsupportedOperationError.
48
+ - run_query -> `instances:udmSearch`, a synchronous GET (empty body) over
49
+ raw UDM events -- unlike the other three new adapters in
50
+ this pass (Falcon LogScale, Ariel, Sumo Search Job), this
51
+ one isn't an async job, it just returns matches directly.
52
+ """
53
+ from __future__ import annotations
54
+
55
+ from datetime import datetime, timedelta, timezone
56
+ from typing import Any, Dict, List, Optional
57
+
58
+ import requests
59
+
60
+ from ..exceptions import UnsupportedOperationError
61
+ from ..models import Alert, ListObject, QueryResult, Rule
62
+ from .base import SIEMAdapter
63
+
64
+ _KIND_TAG_PREFIX = "detectl_kind:"
65
+ _RFC3339 = "%Y-%m-%dT%H:%M:%SZ"
66
+
67
+
68
+ def _kind_from_description(description: str) -> str:
69
+ for part in (description or "").split():
70
+ if part.startswith(_KIND_TAG_PREFIX):
71
+ return part[len(_KIND_TAG_PREFIX):]
72
+ return "watchlist"
73
+
74
+
75
+ def _description_for(kind: str, description: str = "") -> str:
76
+ tag = f"{_KIND_TAG_PREFIX}{kind}"
77
+ return f"{description} {tag}".strip() if description else tag
78
+
79
+
80
+ def _id_from_name(name: str) -> str:
81
+ return name.rstrip("/").rsplit("/", 1)[-1]
82
+
83
+
84
+ class ChronicleAdapter(SIEMAdapter):
85
+ name = "chronicle"
86
+
87
+ def __init__(
88
+ self,
89
+ project: str,
90
+ location: str,
91
+ instance: str,
92
+ access_token: str,
93
+ session: Optional[requests.Session] = None,
94
+ ):
95
+ self.project = project
96
+ self.location = location
97
+ self.instance = instance
98
+ self.base_url = f"https://{location}-chronicle.googleapis.com/v1beta"
99
+ self.session = session or requests.Session()
100
+ self.session.headers.setdefault("Authorization", f"Bearer {access_token}")
101
+ self.session.headers.setdefault("Content-Type", "application/json")
102
+
103
+ @property
104
+ def _instance_path(self) -> str:
105
+ return f"{self.base_url}/projects/{self.project}/locations/{self.location}/instances/{self.instance}"
106
+
107
+ # -- connectivity --------------------------------------------------
108
+ def test_connection(self) -> bool:
109
+ self._request_json("GET", f"{self._instance_path}/rules", params={"pageSize": 1})
110
+ return True
111
+
112
+ # -- rules --------------------------------------------------------
113
+ def _rule_from_entry(self, entry: Dict[str, Any], enabled: Optional[bool] = None) -> Rule:
114
+ return Rule(
115
+ id=_id_from_name(entry.get("name", "")),
116
+ name=entry.get("displayName", _id_from_name(entry.get("name", ""))),
117
+ query=entry.get("text", ""),
118
+ description="",
119
+ severity="medium",
120
+ enabled=True if enabled is None else enabled,
121
+ tags=[],
122
+ raw=entry,
123
+ )
124
+
125
+ def _get_deployment(self, rule_id: str) -> Dict[str, Any]:
126
+ return self._request_json("GET", f"{self._instance_path}/rules/{rule_id}/deployment")
127
+
128
+ def _set_deployment_enabled(self, rule_id: str, enabled: bool) -> None:
129
+ self._request(
130
+ "PATCH",
131
+ f"{self._instance_path}/rules/{rule_id}/deployment",
132
+ params={"updateMask": "enabled"},
133
+ json={"enabled": enabled},
134
+ )
135
+
136
+ def list_rules(self, **filters: Any) -> List[Rule]:
137
+ # Single call, so `enabled` isn't reflected here (that lives on the
138
+ # separate deployment sub-resource) -- use get_rule for that.
139
+ data = self._request_json("GET", f"{self._instance_path}/rules")
140
+ return [self._rule_from_entry(e) for e in data.get("rules", [])]
141
+
142
+ def get_rule(self, rule_id: str) -> Rule:
143
+ entry = self._request_json("GET", f"{self._instance_path}/rules/{rule_id}")
144
+ deployment = self._get_deployment(rule_id)
145
+ return self._rule_from_entry(entry, enabled=deployment.get("enabled", False))
146
+
147
+ def create_rule(self, rule: Rule) -> Rule:
148
+ entry = self._request_json("POST", f"{self._instance_path}/rules", json={"text": rule.query})
149
+ rule_id = _id_from_name(entry["name"])
150
+ self._set_deployment_enabled(rule_id, rule.enabled)
151
+ return self.get_rule(rule_id)
152
+
153
+ def update_rule(self, rule_id: str, rule: Rule) -> Rule:
154
+ self._request(
155
+ "PATCH",
156
+ f"{self._instance_path}/rules/{rule_id}",
157
+ params={"updateMask": "text"},
158
+ json={"text": rule.query},
159
+ )
160
+ self._set_deployment_enabled(rule_id, rule.enabled)
161
+ return self.get_rule(rule_id)
162
+
163
+ def delete_rule(self, rule_id: str) -> None:
164
+ self._request("DELETE", f"{self._instance_path}/rules/{rule_id}")
165
+
166
+ def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
167
+ self._set_deployment_enabled(rule_id, enabled)
168
+ return self.get_rule(rule_id)
169
+
170
+ # -- lists (reference lists) ---------------------------------------
171
+ def _list_from_entry(self, entry: Dict[str, Any]) -> ListObject:
172
+ return ListObject(
173
+ id=_id_from_name(entry.get("name", "")),
174
+ name=_id_from_name(entry.get("name", "")),
175
+ kind=_kind_from_description(entry.get("description", "")),
176
+ description=entry.get("description", ""),
177
+ items=[e.get("value", "") for e in entry.get("entries", [])],
178
+ raw=entry,
179
+ )
180
+
181
+ def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
182
+ data = self._request_json("GET", f"{self._instance_path}/referenceLists")
183
+ results = [self._list_from_entry(e) for e in data.get("referenceLists", [])]
184
+ if kind:
185
+ results = [r for r in results if r.kind == kind]
186
+ return results
187
+
188
+ def get_list(self, list_id: str) -> ListObject:
189
+ entry = self._request_json("GET", f"{self._instance_path}/referenceLists/{list_id}")
190
+ return self._list_from_entry(entry)
191
+
192
+ def create_list(self, list_obj: ListObject) -> ListObject:
193
+ body = {
194
+ "description": _description_for(list_obj.kind, list_obj.description),
195
+ "entries": [{"value": v} for v in list_obj.items],
196
+ "syntaxType": list_obj.raw.get(
197
+ "syntax_type", "REFERENCE_LIST_SYNTAX_TYPE_PLAIN_TEXT_STRING"
198
+ ),
199
+ }
200
+ entry = self._request_json(
201
+ "POST",
202
+ f"{self._instance_path}/referenceLists",
203
+ params={"referenceListId": list_obj.name},
204
+ json=body,
205
+ )
206
+ return self._list_from_entry(entry)
207
+
208
+ def _patch_entries(self, list_id: str, kind: str, description: str, items: List[str]) -> None:
209
+ self._request(
210
+ "PATCH",
211
+ f"{self._instance_path}/referenceLists/{list_id}",
212
+ params={"updateMask": "description,entries"},
213
+ json={
214
+ "description": _description_for(kind, description),
215
+ "entries": [{"value": v} for v in items],
216
+ },
217
+ )
218
+
219
+ def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
220
+ self._patch_entries(list_id, list_obj.kind, list_obj.description, list_obj.items)
221
+ return self.get_list(list_id)
222
+
223
+ def delete_list(self, list_id: str) -> None:
224
+ raise UnsupportedOperationError(
225
+ "Chronicle reference lists cannot be deleted via the API at all (confirmed by "
226
+ "Google's own Terraform provider, which just drops the resource from state rather "
227
+ "than deleting it) -- deletion has to happen in the Google SecOps console."
228
+ )
229
+
230
+ def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
231
+ current = self.get_list(list_id)
232
+ merged = current.items + [v for v in items if v not in current.items]
233
+ self._patch_entries(list_id, current.kind, current.description, merged)
234
+ return self.get_list(list_id)
235
+
236
+ def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
237
+ current = self.get_list(list_id)
238
+ to_remove = set(items)
239
+ remaining = [v for v in current.items if v not in to_remove]
240
+ self._patch_entries(list_id, current.kind, current.description, remaining)
241
+ return self.get_list(list_id)
242
+
243
+ # -- alerts (detections, always scoped to their generating rule) -------
244
+ def _alert_from_entry(self, rule_id: str, entry: Dict[str, Any]) -> Alert:
245
+ detection_id = _id_from_name(entry.get("name", ""))
246
+ return Alert(
247
+ id=f"{rule_id}:{detection_id}",
248
+ title=entry.get("type", "Detection"),
249
+ severity=str(entry.get("alertState", "unknown")),
250
+ status=entry.get("alertState", "unknown"),
251
+ rule_id=rule_id,
252
+ timestamp=(entry.get("timeWindow") or {}).get("endTime"),
253
+ raw=entry,
254
+ )
255
+
256
+ def list_alerts(self, **filters: Any) -> List[Alert]:
257
+ rule_id = filters.get("rule_id")
258
+ if not rule_id:
259
+ raise ValueError(
260
+ "Chronicle list_alerts requires a rule_id filter -- detections only exist "
261
+ "scoped to the rule that generated them (there's no bare, rule-less detection)."
262
+ )
263
+ data = self._request_json(
264
+ "GET", f"{self._instance_path}/rules/{rule_id}/detections", params={"pageSize": filters.get("limit", 100)}
265
+ )
266
+ return [self._alert_from_entry(rule_id, e) for e in data.get("detections", [])]
267
+
268
+ def get_alert(self, alert_id: str) -> Alert:
269
+ rule_id, _, detection_id = alert_id.partition(":")
270
+ entry = self._request_json(
271
+ "GET", f"{self._instance_path}/rules/{rule_id}/detections/{detection_id}"
272
+ )
273
+ return self._alert_from_entry(rule_id, entry)
274
+
275
+ def set_alert_status(self, alert_id: str, status: str) -> Alert:
276
+ raise UnsupportedOperationError(
277
+ "Chronicle detections have no simple settable status field via this API -- "
278
+ "triage/status changes happen through Chronicle's separate SOAR/case-management "
279
+ "module, not the core detections resource."
280
+ )
281
+
282
+ # -- events / raw queries (synchronous UDM search) ----------------------
283
+ def run_query(
284
+ self, query: str, start: Optional[str] = None, end: Optional[str] = None, limit: int = 100, **kwargs: Any
285
+ ) -> QueryResult:
286
+ end_dt = datetime.now(timezone.utc)
287
+ start_dt = end_dt - timedelta(hours=1)
288
+ params = {
289
+ "query": query,
290
+ "time_range.start_time": start or start_dt.strftime(_RFC3339),
291
+ "time_range.end_time": end or end_dt.strftime(_RFC3339),
292
+ "limit": limit,
293
+ }
294
+ data = self._request_json("GET", f"{self._instance_path}:udmSearch", params=params)
295
+ events = data.get("events", [])
296
+ rows = [e.get("udm", {}) for e in events]
297
+ columns = sorted({key for row in rows for key in row.keys()})
298
+ return QueryResult(columns=columns, rows=rows, raw=data)