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,275 @@
|
|
|
1
|
+
"""Elastic (Kibana Security + Elasticsearch) adapter.
|
|
2
|
+
|
|
3
|
+
Maps detectl's canonical resources onto the real Kibana/Elasticsearch APIs:
|
|
4
|
+
|
|
5
|
+
- Rules -> Kibana Detection Engine API (/api/detection_engine/rules)
|
|
6
|
+
- Lists -> Kibana Lists API (/api/lists, /api/lists/items) -- this API
|
|
7
|
+
has no native "kind" (watchlist vs. exclusion vs. allow/
|
|
8
|
+
block vs. suppression) concept, so detectl stores the kind
|
|
9
|
+
in the list's `meta.detectl_kind` field as a convention.
|
|
10
|
+
- Alerts -> Detection signals API (/api/detection_engine/signals/*)
|
|
11
|
+
- run_query -> a raw Elasticsearch _search against `es_base_url`. Accepts
|
|
12
|
+
either a full Query DSL JSON body (a string, e.g. straight
|
|
13
|
+
from `sigmux convert --target elastic`) or a bare
|
|
14
|
+
query string, which gets wrapped in a query_string query.
|
|
15
|
+
|
|
16
|
+
Kibana requires the `kbn-xsrf` header on any state-changing request; that's
|
|
17
|
+
set once on the session in __init__ rather than repeated per call.
|
|
18
|
+
"""
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import json
|
|
22
|
+
from typing import Any, Dict, List, Optional
|
|
23
|
+
|
|
24
|
+
import requests
|
|
25
|
+
|
|
26
|
+
from ..exceptions import ConfigError, NotFoundError
|
|
27
|
+
from ..models import Alert, ListObject, QueryResult, Rule
|
|
28
|
+
from .base import SIEMAdapter
|
|
29
|
+
|
|
30
|
+
_SEVERITY_TO_RISK_SCORE = {"low": 21, "medium": 47, "high": 73, "critical": 99}
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class ElasticAdapter(SIEMAdapter):
|
|
34
|
+
name = "elastic"
|
|
35
|
+
|
|
36
|
+
def __init__(
|
|
37
|
+
self,
|
|
38
|
+
kibana_base_url: str,
|
|
39
|
+
api_key: str,
|
|
40
|
+
es_base_url: Optional[str] = None,
|
|
41
|
+
verify_ssl: bool = True,
|
|
42
|
+
session: Optional[requests.Session] = None,
|
|
43
|
+
):
|
|
44
|
+
self.kibana_base_url = kibana_base_url.rstrip("/")
|
|
45
|
+
self.es_base_url = es_base_url.rstrip("/") if es_base_url else None
|
|
46
|
+
self.session = session or requests.Session()
|
|
47
|
+
self.session.headers.setdefault("Authorization", f"ApiKey {api_key}")
|
|
48
|
+
self.session.headers.setdefault("kbn-xsrf", "detectl")
|
|
49
|
+
self.session.headers.setdefault("Content-Type", "application/json")
|
|
50
|
+
self.session.verify = verify_ssl
|
|
51
|
+
|
|
52
|
+
# -- helpers -----------------------------------------------------
|
|
53
|
+
def _rule_from_item(self, item: Dict[str, Any]) -> Rule:
|
|
54
|
+
return Rule(
|
|
55
|
+
id=item.get("id"),
|
|
56
|
+
name=item.get("name", ""),
|
|
57
|
+
query=item.get("query", ""),
|
|
58
|
+
description=item.get("description", ""),
|
|
59
|
+
severity=item.get("severity", "medium"),
|
|
60
|
+
enabled=item.get("enabled", True),
|
|
61
|
+
tags=item.get("tags", []),
|
|
62
|
+
raw=item,
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
def _list_from_container(self, container: Dict[str, Any], items: Optional[List[str]] = None) -> ListObject:
|
|
66
|
+
kind = (container.get("meta") or {}).get("detectl_kind", "watchlist")
|
|
67
|
+
return ListObject(
|
|
68
|
+
id=container.get("id"),
|
|
69
|
+
name=container.get("name", container.get("id", "")),
|
|
70
|
+
kind=kind,
|
|
71
|
+
description=container.get("description", ""),
|
|
72
|
+
items=items or [],
|
|
73
|
+
raw=container,
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
# -- connectivity --------------------------------------------------
|
|
77
|
+
def test_connection(self) -> bool:
|
|
78
|
+
self._request_json("GET", f"{self.kibana_base_url}/api/status")
|
|
79
|
+
return True
|
|
80
|
+
|
|
81
|
+
# -- rules (Detection Engine API) -------------------------------------
|
|
82
|
+
def list_rules(self, **filters: Any) -> List[Rule]:
|
|
83
|
+
params = {"per_page": filters.get("per_page", 100), "page": filters.get("page", 1)}
|
|
84
|
+
data = self._request_json("GET", f"{self.kibana_base_url}/api/detection_engine/rules/_find", params=params)
|
|
85
|
+
return [self._rule_from_item(item) for item in data.get("data", [])]
|
|
86
|
+
|
|
87
|
+
def get_rule(self, rule_id: str) -> Rule:
|
|
88
|
+
item = self._request_json(
|
|
89
|
+
"GET", f"{self.kibana_base_url}/api/detection_engine/rules", params={"id": rule_id}
|
|
90
|
+
)
|
|
91
|
+
return self._rule_from_item(item)
|
|
92
|
+
|
|
93
|
+
def create_rule(self, rule: Rule) -> Rule:
|
|
94
|
+
body = {
|
|
95
|
+
"name": rule.name,
|
|
96
|
+
"description": rule.description or rule.name,
|
|
97
|
+
"query": rule.query,
|
|
98
|
+
"language": "kuery",
|
|
99
|
+
"type": "query",
|
|
100
|
+
"severity": rule.severity,
|
|
101
|
+
"risk_score": _SEVERITY_TO_RISK_SCORE.get(rule.severity, 47),
|
|
102
|
+
"enabled": rule.enabled,
|
|
103
|
+
"tags": rule.tags,
|
|
104
|
+
"index": ["logs-*"],
|
|
105
|
+
"from": "now-6m",
|
|
106
|
+
"interval": "5m",
|
|
107
|
+
}
|
|
108
|
+
item = self._request_json("POST", f"{self.kibana_base_url}/api/detection_engine/rules", json=body)
|
|
109
|
+
return self._rule_from_item(item)
|
|
110
|
+
|
|
111
|
+
def update_rule(self, rule_id: str, rule: Rule) -> Rule:
|
|
112
|
+
body = {
|
|
113
|
+
"id": rule_id,
|
|
114
|
+
"name": rule.name,
|
|
115
|
+
"description": rule.description or rule.name,
|
|
116
|
+
"query": rule.query,
|
|
117
|
+
"language": "kuery",
|
|
118
|
+
"type": "query",
|
|
119
|
+
"severity": rule.severity,
|
|
120
|
+
"risk_score": _SEVERITY_TO_RISK_SCORE.get(rule.severity, 47),
|
|
121
|
+
"enabled": rule.enabled,
|
|
122
|
+
"tags": rule.tags,
|
|
123
|
+
}
|
|
124
|
+
item = self._request_json("PUT", f"{self.kibana_base_url}/api/detection_engine/rules", json=body)
|
|
125
|
+
return self._rule_from_item(item)
|
|
126
|
+
|
|
127
|
+
def delete_rule(self, rule_id: str) -> None:
|
|
128
|
+
self._request("DELETE", f"{self.kibana_base_url}/api/detection_engine/rules", params={"id": rule_id})
|
|
129
|
+
|
|
130
|
+
def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
|
|
131
|
+
item = self._request_json(
|
|
132
|
+
"PATCH",
|
|
133
|
+
f"{self.kibana_base_url}/api/detection_engine/rules",
|
|
134
|
+
json={"id": rule_id, "enabled": enabled},
|
|
135
|
+
)
|
|
136
|
+
return self._rule_from_item(item)
|
|
137
|
+
|
|
138
|
+
# -- lists (Kibana Lists API) ------------------------------------------
|
|
139
|
+
def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
|
|
140
|
+
data = self._request_json(
|
|
141
|
+
"GET", f"{self.kibana_base_url}/api/lists/_find", params={"per_page": 100}
|
|
142
|
+
)
|
|
143
|
+
results = [self._list_from_container(c) for c in data.get("data", [])]
|
|
144
|
+
if kind:
|
|
145
|
+
results = [r for r in results if r.kind == kind]
|
|
146
|
+
return results
|
|
147
|
+
|
|
148
|
+
def get_list(self, list_id: str) -> ListObject:
|
|
149
|
+
container = self._request_json("GET", f"{self.kibana_base_url}/api/lists", params={"id": list_id})
|
|
150
|
+
item_data = self._request_json(
|
|
151
|
+
"GET",
|
|
152
|
+
f"{self.kibana_base_url}/api/lists/items/_find",
|
|
153
|
+
params={"list_id": list_id, "per_page": 9999},
|
|
154
|
+
)
|
|
155
|
+
items = [i["value"] for i in item_data.get("data", [])]
|
|
156
|
+
return self._list_from_container(container, items)
|
|
157
|
+
|
|
158
|
+
def create_list(self, list_obj: ListObject) -> ListObject:
|
|
159
|
+
body = {
|
|
160
|
+
"name": list_obj.name,
|
|
161
|
+
"description": list_obj.description or list_obj.name,
|
|
162
|
+
"type": "keyword",
|
|
163
|
+
"meta": {"detectl_kind": list_obj.kind},
|
|
164
|
+
}
|
|
165
|
+
if list_obj.id:
|
|
166
|
+
body["id"] = list_obj.id
|
|
167
|
+
container = self._request_json("POST", f"{self.kibana_base_url}/api/lists", json=body)
|
|
168
|
+
if list_obj.items:
|
|
169
|
+
self.add_list_items(container["id"], list_obj.items)
|
|
170
|
+
return self.get_list(container["id"])
|
|
171
|
+
|
|
172
|
+
def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
|
|
173
|
+
body = {
|
|
174
|
+
"id": list_id,
|
|
175
|
+
"name": list_obj.name,
|
|
176
|
+
"description": list_obj.description or list_obj.name,
|
|
177
|
+
"meta": {"detectl_kind": list_obj.kind},
|
|
178
|
+
}
|
|
179
|
+
self._request("PUT", f"{self.kibana_base_url}/api/lists", json=body)
|
|
180
|
+
|
|
181
|
+
existing = self.get_list(list_id)
|
|
182
|
+
if existing.items:
|
|
183
|
+
self.remove_list_items(list_id, existing.items)
|
|
184
|
+
if list_obj.items:
|
|
185
|
+
self.add_list_items(list_id, list_obj.items)
|
|
186
|
+
return self.get_list(list_id)
|
|
187
|
+
|
|
188
|
+
def delete_list(self, list_id: str) -> None:
|
|
189
|
+
self._request(
|
|
190
|
+
"DELETE", f"{self.kibana_base_url}/api/lists", params={"id": list_id, "deleteReferences": "true"}
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
194
|
+
for value in items:
|
|
195
|
+
self._request(
|
|
196
|
+
"POST",
|
|
197
|
+
f"{self.kibana_base_url}/api/lists/items",
|
|
198
|
+
json={"list_id": list_id, "value": value, "type": "keyword"},
|
|
199
|
+
)
|
|
200
|
+
return self.get_list(list_id)
|
|
201
|
+
|
|
202
|
+
def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
203
|
+
item_data = self._request_json(
|
|
204
|
+
"GET",
|
|
205
|
+
f"{self.kibana_base_url}/api/lists/items/_find",
|
|
206
|
+
params={"list_id": list_id, "per_page": 9999},
|
|
207
|
+
)
|
|
208
|
+
to_remove = set(items)
|
|
209
|
+
for entry in item_data.get("data", []):
|
|
210
|
+
if entry.get("value") in to_remove:
|
|
211
|
+
self._request("DELETE", f"{self.kibana_base_url}/api/lists/items", params={"id": entry["id"]})
|
|
212
|
+
return self.get_list(list_id)
|
|
213
|
+
|
|
214
|
+
# -- alerts (detection signals API) ------------------------------------
|
|
215
|
+
def _alert_from_hit(self, hit: Dict[str, Any]) -> Alert:
|
|
216
|
+
source = hit.get("_source", {})
|
|
217
|
+
signal = source.get("signal", {})
|
|
218
|
+
rule = signal.get("rule", {})
|
|
219
|
+
return Alert(
|
|
220
|
+
id=hit["_id"],
|
|
221
|
+
title=rule.get("name", ""),
|
|
222
|
+
severity=rule.get("severity", "unknown"),
|
|
223
|
+
status=signal.get("status", "open"),
|
|
224
|
+
rule_id=rule.get("id"),
|
|
225
|
+
timestamp=source.get("@timestamp"),
|
|
226
|
+
raw=hit,
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
def list_alerts(self, **filters: Any) -> List[Alert]:
|
|
230
|
+
body = {"query": {"match_all": {}}, "size": filters.get("limit", 100)}
|
|
231
|
+
data = self._request_json(
|
|
232
|
+
"POST", f"{self.kibana_base_url}/api/detection_engine/signals/search", json=body
|
|
233
|
+
)
|
|
234
|
+
return [self._alert_from_hit(h) for h in data.get("hits", {}).get("hits", [])]
|
|
235
|
+
|
|
236
|
+
def get_alert(self, alert_id: str) -> Alert:
|
|
237
|
+
body = {"query": {"term": {"_id": alert_id}}, "size": 1}
|
|
238
|
+
data = self._request_json(
|
|
239
|
+
"POST", f"{self.kibana_base_url}/api/detection_engine/signals/search", json=body
|
|
240
|
+
)
|
|
241
|
+
hits = data.get("hits", {}).get("hits", [])
|
|
242
|
+
if not hits:
|
|
243
|
+
raise NotFoundError(f"signal not found: {alert_id}")
|
|
244
|
+
return self._alert_from_hit(hits[0])
|
|
245
|
+
|
|
246
|
+
def set_alert_status(self, alert_id: str, status: str) -> Alert:
|
|
247
|
+
self._request(
|
|
248
|
+
"POST",
|
|
249
|
+
f"{self.kibana_base_url}/api/detection_engine/signals/status",
|
|
250
|
+
json={"signal_ids": [alert_id], "status": status},
|
|
251
|
+
)
|
|
252
|
+
return self.get_alert(alert_id)
|
|
253
|
+
|
|
254
|
+
# -- events / raw queries ---------------------------------------------
|
|
255
|
+
def run_query(self, query: str, limit: int = 100, index: str = "*", **kwargs: Any) -> QueryResult:
|
|
256
|
+
if not self.es_base_url:
|
|
257
|
+
raise ConfigError(
|
|
258
|
+
"run_query requires es_base_url to be configured for the elastic adapter "
|
|
259
|
+
"(raw Query DSL search goes directly to Elasticsearch, not Kibana)"
|
|
260
|
+
)
|
|
261
|
+
index = kwargs.get("index", index)
|
|
262
|
+
stripped = query.strip()
|
|
263
|
+
if stripped.startswith("{"):
|
|
264
|
+
body = json.loads(stripped)
|
|
265
|
+
if "query" not in body:
|
|
266
|
+
body = {"query": body}
|
|
267
|
+
else:
|
|
268
|
+
body = {"query": {"query_string": {"query": query}}}
|
|
269
|
+
body.setdefault("size", limit)
|
|
270
|
+
|
|
271
|
+
resp = self._request_json("POST", f"{self.es_base_url}/{index}/_search", json=body)
|
|
272
|
+
hits = resp.get("hits", {}).get("hits", [])
|
|
273
|
+
rows = [{"_id": h["_id"], "_index": h.get("_index"), **h.get("_source", {})} for h in hits]
|
|
274
|
+
columns = list(rows[0].keys()) if rows else []
|
|
275
|
+
return QueryResult(columns=columns, rows=rows, raw=resp)
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
"""IBM QRadar adapter.
|
|
2
|
+
|
|
3
|
+
Maps detectl's canonical resources onto QRadar's real REST API, which has
|
|
4
|
+
its own conventions worth calling out:
|
|
5
|
+
|
|
6
|
+
- Auth -> an Authorized Service Token in the `SEC` header (not
|
|
7
|
+
`Authorization: Bearer`), plus a required `Version` header
|
|
8
|
+
pinning the API version -- omitting it silently falls back
|
|
9
|
+
to whatever QRadar's default is.
|
|
10
|
+
- Rules -> the Custom Rules Engine (CRE). `/analytics/rules` only
|
|
11
|
+
exposes existing rule *metadata* (name, enabled, owner,
|
|
12
|
+
...) -- rule *logic* is authored through the in-product
|
|
13
|
+
Rule Wizard and isn't creatable or generally editable via
|
|
14
|
+
this API. So `create_rule`/`update_rule` raise
|
|
15
|
+
UnsupportedOperationError; `set_rule_enabled` (a real,
|
|
16
|
+
documented toggle) and `delete_rule` work normally.
|
|
17
|
+
- Lists -> Reference Data Sets (`/reference_data/sets`), QRadar's
|
|
18
|
+
lookup-list primitive. No native "kind" concept, so (same
|
|
19
|
+
convention as the Elastic adapter's `meta.detectl_kind`)
|
|
20
|
+
kind is stored as a `detectl_kind:{kind}` tag in the set's
|
|
21
|
+
`description` field. Items are added/removed one at a time
|
|
22
|
+
-- QRadar's bulk-load endpoint needs a namespace/domain_id
|
|
23
|
+
this adapter doesn't otherwise track, so it isn't used.
|
|
24
|
+
- Alerts -> Offenses (`/siem/offenses`).
|
|
25
|
+
- run_query -> the Ariel Query Language (AQL) search API. Ariel searches
|
|
26
|
+
are asynchronous: POST to start, poll GET until COMPLETED,
|
|
27
|
+
then GET the results -- same shape as the CrowdStrike
|
|
28
|
+
adapter's Falcon LogScale polling, reusing the same
|
|
29
|
+
poll_interval/max_polls knobs.
|
|
30
|
+
"""
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import time
|
|
34
|
+
from typing import Any, Dict, List, Optional
|
|
35
|
+
|
|
36
|
+
import requests
|
|
37
|
+
|
|
38
|
+
from ..exceptions import UnsupportedOperationError
|
|
39
|
+
from ..models import Alert, ListObject, QueryResult, Rule
|
|
40
|
+
from .base import SIEMAdapter
|
|
41
|
+
|
|
42
|
+
_KIND_TAG_PREFIX = "detectl_kind:"
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _kind_from_description(description: str) -> str:
|
|
46
|
+
for part in (description or "").split():
|
|
47
|
+
if part.startswith(_KIND_TAG_PREFIX):
|
|
48
|
+
return part[len(_KIND_TAG_PREFIX):]
|
|
49
|
+
return "watchlist"
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _description_for(kind: str, description: str = "") -> str:
|
|
53
|
+
tag = f"{_KIND_TAG_PREFIX}{kind}"
|
|
54
|
+
return f"{description} {tag}".strip() if description else tag
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class QRadarAdapter(SIEMAdapter):
|
|
58
|
+
name = "qradar"
|
|
59
|
+
|
|
60
|
+
def __init__(
|
|
61
|
+
self,
|
|
62
|
+
base_url: str,
|
|
63
|
+
token: str,
|
|
64
|
+
version: str = "21.0",
|
|
65
|
+
verify_ssl: bool = True,
|
|
66
|
+
poll_interval: float = 1.0,
|
|
67
|
+
max_polls: int = 30,
|
|
68
|
+
session: Optional[requests.Session] = None,
|
|
69
|
+
):
|
|
70
|
+
self.base_url = base_url.rstrip("/")
|
|
71
|
+
self.poll_interval = poll_interval
|
|
72
|
+
self.max_polls = max_polls
|
|
73
|
+
self.session = session or requests.Session()
|
|
74
|
+
self.session.headers.setdefault("SEC", token)
|
|
75
|
+
self.session.headers.setdefault("Version", version)
|
|
76
|
+
self.session.headers.setdefault("Accept", "application/json")
|
|
77
|
+
self.session.verify = verify_ssl
|
|
78
|
+
|
|
79
|
+
# -- connectivity --------------------------------------------------
|
|
80
|
+
def test_connection(self) -> bool:
|
|
81
|
+
self._request_json("GET", f"{self.base_url}/api/system/about")
|
|
82
|
+
return True
|
|
83
|
+
|
|
84
|
+
# -- rules (Custom Rules Engine metadata only) -------------------------
|
|
85
|
+
def _rule_from_entry(self, entry: Dict[str, Any]) -> Rule:
|
|
86
|
+
return Rule(
|
|
87
|
+
id=str(entry.get("id")),
|
|
88
|
+
name=entry.get("name", ""),
|
|
89
|
+
query="",
|
|
90
|
+
description="QRadar CRE rule logic isn't exposed as text via this API",
|
|
91
|
+
severity="medium",
|
|
92
|
+
enabled=entry.get("enabled", True),
|
|
93
|
+
tags=[entry.get("type", "")] if entry.get("type") else [],
|
|
94
|
+
raw=entry,
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
def list_rules(self, **filters: Any) -> List[Rule]:
|
|
98
|
+
data = self._request_json("GET", f"{self.base_url}/api/analytics/rules")
|
|
99
|
+
return [self._rule_from_entry(e) for e in data]
|
|
100
|
+
|
|
101
|
+
def get_rule(self, rule_id: str) -> Rule:
|
|
102
|
+
entry = self._request_json("GET", f"{self.base_url}/api/analytics/rules/{rule_id}")
|
|
103
|
+
return self._rule_from_entry(entry)
|
|
104
|
+
|
|
105
|
+
def create_rule(self, rule: Rule) -> Rule:
|
|
106
|
+
raise UnsupportedOperationError(
|
|
107
|
+
"QRadar's Custom Rules Engine has no API for creating new rule logic -- rules are "
|
|
108
|
+
"authored through the in-product Rule Wizard. /analytics/rules only manages "
|
|
109
|
+
"metadata (enable/disable, delete) for rules that already exist."
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
def update_rule(self, rule_id: str, rule: Rule) -> Rule:
|
|
113
|
+
raise UnsupportedOperationError(
|
|
114
|
+
"QRadar's Custom Rules Engine has no API for editing rule logic (name/query/"
|
|
115
|
+
"severity) -- only enabling/disabling an existing rule is supported. Use "
|
|
116
|
+
"enable_rule/disable_rule instead."
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
def delete_rule(self, rule_id: str) -> None:
|
|
120
|
+
self._request("DELETE", f"{self.base_url}/api/analytics/rules/{rule_id}")
|
|
121
|
+
|
|
122
|
+
def set_rule_enabled(self, rule_id: str, enabled: bool) -> Rule:
|
|
123
|
+
entry = self._request_json(
|
|
124
|
+
"POST", f"{self.base_url}/api/analytics/rules/{rule_id}", json={"enabled": enabled}
|
|
125
|
+
)
|
|
126
|
+
return self._rule_from_entry(entry)
|
|
127
|
+
|
|
128
|
+
# -- lists (Reference Data Sets) ---------------------------------------
|
|
129
|
+
def _list_from_entry(self, entry: Dict[str, Any]) -> ListObject:
|
|
130
|
+
return ListObject(
|
|
131
|
+
id=entry.get("name"),
|
|
132
|
+
name=entry.get("name", ""),
|
|
133
|
+
kind=_kind_from_description(entry.get("description", "")),
|
|
134
|
+
description=entry.get("description", ""),
|
|
135
|
+
items=[str(d.get("value")) for d in entry.get("data", [])],
|
|
136
|
+
raw=entry,
|
|
137
|
+
)
|
|
138
|
+
|
|
139
|
+
def list_lists(self, kind: Optional[str] = None) -> List[ListObject]:
|
|
140
|
+
data = self._request_json("GET", f"{self.base_url}/api/reference_data/sets")
|
|
141
|
+
results = [self._list_from_entry(e) for e in data]
|
|
142
|
+
if kind:
|
|
143
|
+
results = [r for r in results if r.kind == kind]
|
|
144
|
+
return results
|
|
145
|
+
|
|
146
|
+
def get_list(self, list_id: str) -> ListObject:
|
|
147
|
+
entry = self._request_json("GET", f"{self.base_url}/api/reference_data/sets/{list_id}")
|
|
148
|
+
return self._list_from_entry(entry)
|
|
149
|
+
|
|
150
|
+
def create_list(self, list_obj: ListObject) -> ListObject:
|
|
151
|
+
self._request(
|
|
152
|
+
"POST",
|
|
153
|
+
f"{self.base_url}/api/reference_data/sets",
|
|
154
|
+
params={
|
|
155
|
+
"name": list_obj.name,
|
|
156
|
+
"element_type": "ALN",
|
|
157
|
+
"timeout_type": "UNKNOWN",
|
|
158
|
+
"description": _description_for(list_obj.kind, list_obj.description),
|
|
159
|
+
},
|
|
160
|
+
)
|
|
161
|
+
if list_obj.items:
|
|
162
|
+
self.add_list_items(list_obj.name, list_obj.items)
|
|
163
|
+
return self.get_list(list_obj.name)
|
|
164
|
+
|
|
165
|
+
def update_list(self, list_id: str, list_obj: ListObject) -> ListObject:
|
|
166
|
+
existing = self.get_list(list_id)
|
|
167
|
+
if existing.items:
|
|
168
|
+
self.remove_list_items(list_id, existing.items)
|
|
169
|
+
if list_obj.items:
|
|
170
|
+
self.add_list_items(list_id, list_obj.items)
|
|
171
|
+
return self.get_list(list_id)
|
|
172
|
+
|
|
173
|
+
def delete_list(self, list_id: str) -> None:
|
|
174
|
+
self._request("DELETE", f"{self.base_url}/api/reference_data/sets/{list_id}")
|
|
175
|
+
|
|
176
|
+
def add_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
177
|
+
for value in items:
|
|
178
|
+
self._request(
|
|
179
|
+
"POST", f"{self.base_url}/api/reference_data/sets/{list_id}", params={"value": value}
|
|
180
|
+
)
|
|
181
|
+
return self.get_list(list_id)
|
|
182
|
+
|
|
183
|
+
def remove_list_items(self, list_id: str, items: List[str]) -> ListObject:
|
|
184
|
+
for value in items:
|
|
185
|
+
self._request("DELETE", f"{self.base_url}/api/reference_data/sets/{list_id}/{value}")
|
|
186
|
+
return self.get_list(list_id)
|
|
187
|
+
|
|
188
|
+
# -- alerts (offenses) ---------------------------------------------
|
|
189
|
+
def _alert_from_entry(self, entry: Dict[str, Any]) -> Alert:
|
|
190
|
+
rule_ids = [str(r.get("id")) for r in entry.get("rules", []) if r.get("id") is not None]
|
|
191
|
+
return Alert(
|
|
192
|
+
id=str(entry.get("id")),
|
|
193
|
+
title=entry.get("description", ""),
|
|
194
|
+
severity=str(entry.get("severity", entry.get("magnitude", "unknown"))),
|
|
195
|
+
status=entry.get("status", "OPEN"),
|
|
196
|
+
rule_id=rule_ids[0] if rule_ids else None,
|
|
197
|
+
timestamp=str(entry.get("start_time")) if entry.get("start_time") is not None else None,
|
|
198
|
+
raw=entry,
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
def list_alerts(self, **filters: Any) -> List[Alert]:
|
|
202
|
+
data = self._request_json(
|
|
203
|
+
"GET", f"{self.base_url}/api/siem/offenses", params={"Range": f"items=0-{filters.get('limit', 100) - 1}"}
|
|
204
|
+
)
|
|
205
|
+
return [self._alert_from_entry(e) for e in data]
|
|
206
|
+
|
|
207
|
+
def get_alert(self, alert_id: str) -> Alert:
|
|
208
|
+
entry = self._request_json("GET", f"{self.base_url}/api/siem/offenses/{alert_id}")
|
|
209
|
+
return self._alert_from_entry(entry)
|
|
210
|
+
|
|
211
|
+
def set_alert_status(self, alert_id: str, status: str) -> Alert:
|
|
212
|
+
entry = self._request_json(
|
|
213
|
+
"POST", f"{self.base_url}/api/siem/offenses/{alert_id}", params={"status": status}
|
|
214
|
+
)
|
|
215
|
+
return self._alert_from_entry(entry)
|
|
216
|
+
|
|
217
|
+
# -- events / raw queries (Ariel Query Language) -----------------------
|
|
218
|
+
def run_query(self, query: str, limit: int = 100, **kwargs: Any) -> QueryResult:
|
|
219
|
+
created = self._request_json(
|
|
220
|
+
"POST", f"{self.base_url}/api/ariel/searches", params={"query_expression": query}
|
|
221
|
+
)
|
|
222
|
+
search_id = created["search_id"]
|
|
223
|
+
status_url = f"{self.base_url}/api/ariel/searches/{search_id}"
|
|
224
|
+
|
|
225
|
+
status = self._request_json("GET", status_url)
|
|
226
|
+
polls = 0
|
|
227
|
+
while status.get("status") != "COMPLETED" and polls < self.max_polls:
|
|
228
|
+
if self.poll_interval > 0:
|
|
229
|
+
time.sleep(self.poll_interval)
|
|
230
|
+
polls += 1
|
|
231
|
+
status = self._request_json("GET", status_url)
|
|
232
|
+
|
|
233
|
+
results = self._request_json("GET", f"{status_url}/results")
|
|
234
|
+
events = results.get("events", [])[:limit]
|
|
235
|
+
columns = sorted({key for event in events for key in event.keys()})
|
|
236
|
+
return QueryResult(columns=columns, rows=events, raw=results)
|