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
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,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)
|
detectl/adapters/base.py
ADDED
|
@@ -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)
|