detectl 0.2.0__tar.gz

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-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kyle Main
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
detectl-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,318 @@
1
+ Metadata-Version: 2.4
2
+ Name: detectl
3
+ Version: 0.2.0
4
+ Summary: A CLI for managing detection rules, tuning lists, alerts, and ad-hoc queries across multiple SIEM/EDR platforms through one consistent interface.
5
+ Author: Kyle Main
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/kylemain/detectl
8
+ Project-URL: Repository, https://github.com/kylemain/detectl
9
+ Project-URL: Issues, https://github.com/kylemain/detectl/issues
10
+ Keywords: siem,detection-engineering,splunk,elastic,sentinel,crowdstrike,qradar,sumologic,chronicle,security,sigmux,sigma
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Information Technology
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Security
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: click>=8.0
25
+ Requires-Dist: PyYAML>=6.0
26
+ Requires-Dist: requests>=2.28
27
+ Provides-Extra: sigma
28
+ Requires-Dist: sigmux>=0.3.0; extra == "sigma"
29
+ Provides-Extra: dryrun
30
+ Requires-Dist: rich>=13.0; extra == "dryrun"
31
+ Dynamic: license-file
32
+
33
+ # detectl
34
+
35
+ [![CI](https://github.com/kylemain/detectl/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
36
+ [![coverage](coverage.svg)](#testing)
37
+
38
+ A CLI (and Python library) for managing detection rules, tuning lists
39
+ (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
40
+ alerts, and ad-hoc queries across multiple SIEM/EDR platforms through one
41
+ consistent interface.
42
+
43
+ This is the same kind of cross-platform detection tuning work I do professionally -- one consistent interface instead of re-learning seven platforms' APIs -- built clean-room, not tied to any employer's internal tooling. It pairs directly with [sigmux](https://github.com/kylemain/sigmux), which converts a portable Sigma rule into whichever query language a given platform speaks; detectl takes it the rest of the way and actually pushes it live. See [Pairs well with sigmux](#pairs-well-with-sigmux) below.
44
+
45
+ ![sigmux and detectl demo](demo.gif)
46
+
47
+ ```
48
+ $ detectl -p splunk rules list
49
+ [
50
+ {
51
+ "id": "Suspicious PowerShell Encoded Command",
52
+ "name": "Suspicious PowerShell Encoded Command",
53
+ "query": "index=main process_name IN (\"powershell.exe\", \"pwsh.exe\") AND args=\"*-enc*\"",
54
+ "severity": "high",
55
+ "enabled": true,
56
+ ...
57
+ }
58
+ ]
59
+ ```
60
+
61
+ ## Why
62
+
63
+ Every real detection engineering team ends up managing rules, tuning lists,
64
+ and alert triage across more than one platform -- and every platform's API
65
+ looks nothing like the others. `detectl` gives each platform a self-contained
66
+ adapter behind one shared interface, so the same four resource types (rules,
67
+ lists, alerts, queries) work the same way no matter which SIEM you're
68
+ pointed at.
69
+
70
+ This is a from-scratch, clean-room implementation against each platform's
71
+ real public REST API -- not a wrapper around any vendor SDK.
72
+
73
+ ## Supported platforms
74
+
75
+ | Platform | Rules | Lists | Alerts | Ad-hoc query |
76
+ |---|---|---|---|---|
77
+ | Splunk | Saved searches / correlation searches | KV Store collections | Fired alerts | Blocking search job (SPL) |
78
+ | Elastic (Kibana Security + Elasticsearch) | Detection Engine rules | Lists API | Detection signals | Elasticsearch Query DSL |
79
+ | Microsoft Sentinel | Scheduled Analytics Rules | Watchlists | Incidents | Log Analytics (KQL) |
80
+ | CrowdStrike Falcon | Custom IOA rules | IOC management | Falcon Alerts | Falcon LogScale (LQL) -- optional, see [Known limitations](#known-limitations) |
81
+ | IBM QRadar | CRE rule metadata (enable/disable/delete only) | Reference Data Sets | Offenses | Ariel Query Language (AQL) |
82
+ | Sumo Logic | Monitors Library | Cloud SIEM Match Lists | Cloud SIEM Insights | Search Job API |
83
+ | Google Chronicle (Google SecOps) | Rules (YARA-L text) | Reference Lists (no delete -- see [Known limitations](#known-limitations)) | Detections (rule-scoped, read-only) | UDM Search |
84
+
85
+ ## Install
86
+
87
+ Not published to PyPI yet -- `pyproject.toml` and `.github/workflows/publish.yml` are set up for it (PyPI Trusted Publishing, triggered on a version tag), but that needs a one-time manual step on pypi.org's side first. Until then, install from source:
88
+
89
+ ```bash
90
+ git clone https://github.com/kylemain/detectl.git
91
+ cd detectl
92
+ python3 -m venv .venv
93
+ source .venv/bin/activate
94
+ pip install -e .
95
+
96
+ # Optional extras: `sigma` for `rules create-from-sigma`, `dryrun` for --dry-run's diff view
97
+ pip install -e ".[sigma,dryrun]"
98
+ ```
99
+
100
+ ## Configure
101
+
102
+ Copy `examples/config.yml.example` to `~/.detectl/config.yml` and fill in
103
+ the platform(s) you use. String values can reference `${ENV_VAR}`, so
104
+ secrets never have to live in the file itself:
105
+
106
+ ```yaml
107
+ splunk:
108
+ base_url: https://splunk.example.com:8089
109
+ token: ${SPLUNK_TOKEN}
110
+ ```
111
+
112
+ Any field you don't set in the config file falls back to a
113
+ platform-prefixed environment variable instead (`SPLUNK_BASE_URL`,
114
+ `SPLUNK_TOKEN`, `ELASTIC_API_KEY`, `SENTINEL_CLIENT_SECRET`, ...), so you
115
+ can skip the config file entirely and configure purely through the
116
+ environment if you prefer. See `examples/config.yml.example` for the full
117
+ field list per platform.
118
+
119
+ ## Usage
120
+
121
+ ```bash
122
+ detectl targets # list supported platforms
123
+ detectl -p splunk test-connection # verify credentials
124
+
125
+ detectl -p elastic rules list
126
+ detectl -p elastic rules get <rule_id>
127
+ detectl -p elastic rules create -f examples/rules/suspicious_powershell.json
128
+ detectl -p elastic rules update <rule_id> -f updated_rule.json
129
+ detectl -p elastic rules enable <rule_id>
130
+ detectl -p elastic rules delete <rule_id>
131
+
132
+ detectl -p sentinel lists list --kind watchlist
133
+ detectl -p sentinel lists create -f examples/lists/known_bad_ips.json
134
+ detectl -p sentinel lists add-items known-bad-ips -i 198.51.100.99
135
+ detectl -p sentinel lists remove-items known-bad-ips -i 198.51.100.99
136
+
137
+ detectl -p crowdstrike alerts list
138
+ detectl -p crowdstrike alerts set-status <alert_id> closed
139
+
140
+ detectl -p sentinel query "SecurityEvent | where EventID == 4625 | take 20"
141
+ detectl -p elastic query '{"match": {"process.name": "mimikatz.exe"}}'
142
+
143
+ # Ad-hoc queries against Falcon run through Falcon LogScale, not the core
144
+ # Falcon platform API (see Known limitations) -- requires logscale_url /
145
+ # logscale_token in config, in addition to the Falcon client_id/secret.
146
+ detectl -p crowdstrike query "#event_simpleName=ProcessRollup2 FileName=mimikatz.exe"
147
+
148
+ detectl -p qradar rules list
149
+ detectl -p qradar lists create -f examples/lists/malicious_domains.json
150
+ detectl -p qradar alerts list
151
+ detectl -p qradar query "SELECT UTF8(payload) AS payload FROM events WHERE sourceip='10.0.0.5'"
152
+
153
+ detectl -p sumologic rules create -f examples/rules/c2_beacon_suspicious_port.json
154
+ detectl -p sumologic lists list --kind blocklist
155
+ detectl -p sumologic query "error | count by sourcehost"
156
+
157
+ detectl -p chronicle rules create -f examples/rules/mimikatz_credential_dumping.json
158
+ detectl -p chronicle lists create -f examples/lists/vip_watchlist_usernames.json
159
+ detectl -p chronicle query 'principal.hostname="host1" and target.process.file.full_path contains "mimikatz.exe"'
160
+ ```
161
+
162
+ Every command prints JSON to stdout, so it composes with `jq` and shell
163
+ pipelines the way a real ops CLI should.
164
+
165
+ ### Pairs well with [sigmux](https://github.com/kylemain/sigmux)
166
+
167
+ sigmux compiles a portable Sigma detection rule into per-platform query syntax, and its target names match detectl's platform names 1:1 on purpose (`elastic`, `crowdstrike`, `sentinel`, `splunk`, `qradar`, `sumologic`, `chronicle`). detectl imports sigmux as a library (the `sigma` extra) to fold "convert, then create" into one step:
168
+
169
+ ```bash
170
+ detectl -p elastic rules create-from-sigma my_rule.yml
171
+ ```
172
+
173
+ `rules create-from-sigma` parses the Sigma rule, picks the sigmux target that matches `--platform` automatically (never a manual mapping you can get out of sync), and creates it as a live detection rule. Add `--dry-run` to see the full converted query and rule metadata -- Terraform-plan style -- before anything is actually created:
174
+
175
+ ```bash
176
+ detectl -p qradar rules create-from-sigma my_rule.yml --dry-run
177
+ ```
178
+
179
+ A few platforms need one extra piece of platform-specific context a generic Sigma rule doesn't carry (CrowdStrike's IOA rule group, Sumo Logic's Monitors folder) -- pass it with repeatable `--raw KEY=VALUE`:
180
+
181
+ ```bash
182
+ detectl -p sumologic rules create-from-sigma my_rule.yml --raw parent_id=folder123
183
+ ```
184
+
185
+ This isn't just a documented pairing: a separate `integration` job in this repo's CI checks out sigmux fresh, spins up a real Elasticsearch, and runs a full Sigma rule → sigmux → live Elasticsearch → detectl round trip against it end to end (see `scripts/integration_test_elastic.py`) -- so the two projects staying compatible is something CI actually verifies, not just a README claim.
186
+
187
+ The lower-level pairing (convert with sigmux, then feed the raw query text into `detectl query` yourself) still works too, and is what `create-from-sigma` does internally for the rule-creation path:
188
+
189
+ ```bash
190
+ sigmux convert my_rule.yml -t elastic -o out/
191
+ detectl -p elastic query "$(cat out/my_rule.elastic.json)"
192
+
193
+ sigmux convert my_rule.yml -t crowdstrike -o out/
194
+ detectl -p crowdstrike query "$(cat out/my_rule.crowdstrike.lql)"
195
+ ```
196
+
197
+ ## Architecture
198
+
199
+ - `detectl/models.py` -- canonical, platform-agnostic dataclasses (`Rule`,
200
+ `ListObject`, `Alert`, `QueryResult`). Every adapter converts to/from
201
+ these at its own API boundary; callers only ever see one consistent
202
+ shape. Each model carries a `raw` field with the untouched platform
203
+ payload for anything the common fields don't capture.
204
+ - `detectl/adapters/base.py` -- the abstract `SIEMAdapter` interface every
205
+ platform implements, plus a small `HttpMixin` that centralizes HTTP error
206
+ translation (`AuthenticationError`, `NotFoundError`, `APIError`) so
207
+ concrete adapters don't each reimplement it.
208
+ - `detectl/adapters/{splunk,elastic,sentinel,crowdstrike,qradar,sumologic,chronicle}.py`
209
+ -- one self-contained file per platform, each mapping the canonical
210
+ interface onto that platform's real REST API.
211
+ - `detectl/config.py` -- per-platform config loading from YAML and/or
212
+ environment variables.
213
+ - `detectl/cli.py` -- the click-based CLI wiring the above together,
214
+ including the sigmux bridge (`rules create-from-sigma`) and the
215
+ Terraform-plan-style `--dry-run` diff view.
216
+ - `scripts/integration_test_elastic.py` -- the live, network-touching
217
+ Sigma → sigmux → Elasticsearch → detectl round trip that CI's
218
+ `integration` job runs (see Testing below); `scripts/generate_coverage_badge.py`
219
+ is the self-hosted badge renderer behind the coverage badge above.
220
+
221
+ ### Adding a new platform
222
+
223
+ Implement `SIEMAdapter` (see `detectl/adapters/base.py` for the full
224
+ method list) in a new file under `detectl/adapters/`, register it in
225
+ `detectl/adapters/__init__.py`'s `REGISTRY`, and add its required config
226
+ fields to `detectl/config.py`'s `REQUIRED_FIELDS`/`OPTIONAL_FIELDS`. Not
227
+ every platform needs to support every operation -- raise
228
+ `UnsupportedOperationError` with a clear explanation rather than faking
229
+ support (see Splunk's `set_alert_status`, or CrowdStrike's `run_query` when
230
+ Falcon LogScale isn't configured).
231
+
232
+ ## Known limitations
233
+
234
+ A few platforms don't have a clean native equivalent for one of detectl's
235
+ canonical resources. Rather than papering over the mismatch, each adapter
236
+ documents its own convention at the top of its file:
237
+
238
+ - **The core Falcon platform API has no ad-hoc event query endpoint**
239
+ comparable to Splunk SPL, Elasticsearch DSL, or Sentinel KQL -- Falcon
240
+ exposes detections/alerts/IOCs as discrete resources, not a general query
241
+ surface over raw events. `run_query` instead talks to **Falcon LogScale**,
242
+ a genuinely separate CrowdStrike product with its own base URL and its
243
+ own credential (a LogScale Personal API token, distinct from the Falcon
244
+ `client_id`/`client_secret` used for rules/lists/alerts). It's optional:
245
+ configure `logscale_url`/`logscale_token`/`logscale_repository` (see
246
+ `examples/config.yml.example`) to enable it; without them, `run_query`
247
+ raises `UnsupportedOperationError` explaining how to turn it on. LogScale
248
+ query jobs are asynchronous, so `run_query` polls the job (`poll_interval`
249
+ seconds between checks, up to `max_polls` times) until it reports done.
250
+ - **Splunk's fired-alerts API has no settable status field** (no ack/close
251
+ concept the way Elastic signals or Sentinel incidents have) --
252
+ `set_alert_status` raises `UnsupportedOperationError`.
253
+ - **Kibana's Lists API has no native "kind"** (watchlist vs. exclusion vs.
254
+ allow/block vs. suppression) -- the Elastic adapter stores it in the
255
+ list's `meta.detectl_kind` field as a convention.
256
+ - **CrowdStrike's IOC API has no named-list container** at all -- IOCs are
257
+ individually-tagged indicators, so the CrowdStrike adapter groups them
258
+ into named lists via a `detectl_list:{name}` tag, and infers `kind` from
259
+ each IOC's `action` field (allow/block/detect).
260
+ - **CrowdStrike custom IOA rules are always scoped to a parent rule
261
+ group** -- there's no bare, group-less rule -- so rule IDs in that
262
+ adapter are encoded as `"{rule_group_id}:{instance_id}"`.
263
+ - IOC type inference (`ipv4` / `md5` / `sha1` / `sha256` / `domain`) in the
264
+ CrowdStrike adapter is a heuristic based on the value's shape, not a
265
+ caller-supplied type.
266
+ - **QRadar's Custom Rules Engine has no API for authoring rule logic** --
267
+ `/analytics/rules` only manages metadata (enable/disable, delete) for
268
+ rules that already exist; new rule logic has to be built through the
269
+ in-product Rule Wizard. `create_rule`/`update_rule` raise
270
+ `UnsupportedOperationError`; use `enable_rule`/`disable_rule` instead.
271
+ - **QRadar Reference Sets have no native "kind"** -- same `detectl_kind:
272
+ {kind}` tag convention as Elastic's `meta.detectl_kind`, stored in the
273
+ set's `description` field.
274
+ - **Sumo Logic Monitors need a destination folder** (Monitors Library is a
275
+ folder tree, there's no bare/folder-less monitor) -- `create_rule`
276
+ requires `rule.raw["parent_id"]`, same convention as CrowdStrike's
277
+ `rule.raw["rule_group_id"]` for Custom IOA rules. Updates need the
278
+ monitor's current `version` for optimistic concurrency, so
279
+ `update_rule`/`set_rule_enabled` do a read-modify-write.
280
+ - **Sumo Logic Cloud SIEM Match Lists have no "kind" field** (they have a
281
+ required `targetColumn` describing the *value type* -- IP, domain, file
282
+ hash, ... -- instead) -- same tag-in-description convention as QRadar.
283
+ Removing items needs match-list-item IDs, not raw values, so
284
+ `remove_list_items` reads the current items first to resolve them.
285
+ - **Chronicle reference lists cannot be deleted via the API at all**
286
+ (confirmed directly in Google's own Terraform provider source, which
287
+ just drops the resource from state rather than deleting it) --
288
+ `delete_list` raises `UnsupportedOperationError` rather than silently
289
+ no-op'ing.
290
+ - **Chronicle detections only exist scoped to the rule that generated
291
+ them** -- `list_alerts` requires a `rule_id` filter, and `get_alert` IDs
292
+ are encoded as `"{rule_id}:{detection_id}"`, same shape as CrowdStrike's
293
+ `"{rule_group_id}:{instance_id}"`. Detection triage/status lives in
294
+ Chronicle's separate SOAR/case-management module, not a simple status
295
+ field here, so `set_alert_status` raises `UnsupportedOperationError`.
296
+ - **Chronicle auth is a pre-obtained OAuth2 bearer token, not a full
297
+ service-account flow** -- signing a JWT with an RSA private key is real
298
+ crypto, out of scope for a dependency-light client. Get one with
299
+ `gcloud auth print-access-token` (or your own refresh cron) and set it
300
+ as `access_token`.
301
+
302
+ ## Testing
303
+
304
+ No `pytest` dependency -- the whole suite runs on the standard library's
305
+ `unittest`. Every adapter test injects a fake `requests.Session` stand-in
306
+ (see `tests/helpers.py`) that asserts on exact HTTP calls and returns
307
+ canned responses, so the suite never touches the network and needs no
308
+ credentials:
309
+
310
+ ```bash
311
+ python -m unittest discover -v
312
+ ```
313
+
314
+ That's the fast, always-run signal that actually gates merges. Layered on top of it, a separate `integration` job in CI (see `scripts/integration_test_elastic.py`) deliberately does touch the network: it checks out sigmux, spins up a real Elasticsearch service container, and runs a full Sigma rule → sigmux → live Elasticsearch → detectl pipeline end to end. It's `continue-on-error` and its own job so a live-service flake never reddens the unit-test signal above.
315
+
316
+ ## License
317
+
318
+ MIT
@@ -0,0 +1,286 @@
1
+ # detectl
2
+
3
+ [![CI](https://github.com/kylemain/detectl/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
4
+ [![coverage](coverage.svg)](#testing)
5
+
6
+ A CLI (and Python library) for managing detection rules, tuning lists
7
+ (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
8
+ alerts, and ad-hoc queries across multiple SIEM/EDR platforms through one
9
+ consistent interface.
10
+
11
+ This is the same kind of cross-platform detection tuning work I do professionally -- one consistent interface instead of re-learning seven platforms' APIs -- built clean-room, not tied to any employer's internal tooling. It pairs directly with [sigmux](https://github.com/kylemain/sigmux), which converts a portable Sigma rule into whichever query language a given platform speaks; detectl takes it the rest of the way and actually pushes it live. See [Pairs well with sigmux](#pairs-well-with-sigmux) below.
12
+
13
+ ![sigmux and detectl demo](demo.gif)
14
+
15
+ ```
16
+ $ detectl -p splunk rules list
17
+ [
18
+ {
19
+ "id": "Suspicious PowerShell Encoded Command",
20
+ "name": "Suspicious PowerShell Encoded Command",
21
+ "query": "index=main process_name IN (\"powershell.exe\", \"pwsh.exe\") AND args=\"*-enc*\"",
22
+ "severity": "high",
23
+ "enabled": true,
24
+ ...
25
+ }
26
+ ]
27
+ ```
28
+
29
+ ## Why
30
+
31
+ Every real detection engineering team ends up managing rules, tuning lists,
32
+ and alert triage across more than one platform -- and every platform's API
33
+ looks nothing like the others. `detectl` gives each platform a self-contained
34
+ adapter behind one shared interface, so the same four resource types (rules,
35
+ lists, alerts, queries) work the same way no matter which SIEM you're
36
+ pointed at.
37
+
38
+ This is a from-scratch, clean-room implementation against each platform's
39
+ real public REST API -- not a wrapper around any vendor SDK.
40
+
41
+ ## Supported platforms
42
+
43
+ | Platform | Rules | Lists | Alerts | Ad-hoc query |
44
+ |---|---|---|---|---|
45
+ | Splunk | Saved searches / correlation searches | KV Store collections | Fired alerts | Blocking search job (SPL) |
46
+ | Elastic (Kibana Security + Elasticsearch) | Detection Engine rules | Lists API | Detection signals | Elasticsearch Query DSL |
47
+ | Microsoft Sentinel | Scheduled Analytics Rules | Watchlists | Incidents | Log Analytics (KQL) |
48
+ | CrowdStrike Falcon | Custom IOA rules | IOC management | Falcon Alerts | Falcon LogScale (LQL) -- optional, see [Known limitations](#known-limitations) |
49
+ | IBM QRadar | CRE rule metadata (enable/disable/delete only) | Reference Data Sets | Offenses | Ariel Query Language (AQL) |
50
+ | Sumo Logic | Monitors Library | Cloud SIEM Match Lists | Cloud SIEM Insights | Search Job API |
51
+ | Google Chronicle (Google SecOps) | Rules (YARA-L text) | Reference Lists (no delete -- see [Known limitations](#known-limitations)) | Detections (rule-scoped, read-only) | UDM Search |
52
+
53
+ ## Install
54
+
55
+ Not published to PyPI yet -- `pyproject.toml` and `.github/workflows/publish.yml` are set up for it (PyPI Trusted Publishing, triggered on a version tag), but that needs a one-time manual step on pypi.org's side first. Until then, install from source:
56
+
57
+ ```bash
58
+ git clone https://github.com/kylemain/detectl.git
59
+ cd detectl
60
+ python3 -m venv .venv
61
+ source .venv/bin/activate
62
+ pip install -e .
63
+
64
+ # Optional extras: `sigma` for `rules create-from-sigma`, `dryrun` for --dry-run's diff view
65
+ pip install -e ".[sigma,dryrun]"
66
+ ```
67
+
68
+ ## Configure
69
+
70
+ Copy `examples/config.yml.example` to `~/.detectl/config.yml` and fill in
71
+ the platform(s) you use. String values can reference `${ENV_VAR}`, so
72
+ secrets never have to live in the file itself:
73
+
74
+ ```yaml
75
+ splunk:
76
+ base_url: https://splunk.example.com:8089
77
+ token: ${SPLUNK_TOKEN}
78
+ ```
79
+
80
+ Any field you don't set in the config file falls back to a
81
+ platform-prefixed environment variable instead (`SPLUNK_BASE_URL`,
82
+ `SPLUNK_TOKEN`, `ELASTIC_API_KEY`, `SENTINEL_CLIENT_SECRET`, ...), so you
83
+ can skip the config file entirely and configure purely through the
84
+ environment if you prefer. See `examples/config.yml.example` for the full
85
+ field list per platform.
86
+
87
+ ## Usage
88
+
89
+ ```bash
90
+ detectl targets # list supported platforms
91
+ detectl -p splunk test-connection # verify credentials
92
+
93
+ detectl -p elastic rules list
94
+ detectl -p elastic rules get <rule_id>
95
+ detectl -p elastic rules create -f examples/rules/suspicious_powershell.json
96
+ detectl -p elastic rules update <rule_id> -f updated_rule.json
97
+ detectl -p elastic rules enable <rule_id>
98
+ detectl -p elastic rules delete <rule_id>
99
+
100
+ detectl -p sentinel lists list --kind watchlist
101
+ detectl -p sentinel lists create -f examples/lists/known_bad_ips.json
102
+ detectl -p sentinel lists add-items known-bad-ips -i 198.51.100.99
103
+ detectl -p sentinel lists remove-items known-bad-ips -i 198.51.100.99
104
+
105
+ detectl -p crowdstrike alerts list
106
+ detectl -p crowdstrike alerts set-status <alert_id> closed
107
+
108
+ detectl -p sentinel query "SecurityEvent | where EventID == 4625 | take 20"
109
+ detectl -p elastic query '{"match": {"process.name": "mimikatz.exe"}}'
110
+
111
+ # Ad-hoc queries against Falcon run through Falcon LogScale, not the core
112
+ # Falcon platform API (see Known limitations) -- requires logscale_url /
113
+ # logscale_token in config, in addition to the Falcon client_id/secret.
114
+ detectl -p crowdstrike query "#event_simpleName=ProcessRollup2 FileName=mimikatz.exe"
115
+
116
+ detectl -p qradar rules list
117
+ detectl -p qradar lists create -f examples/lists/malicious_domains.json
118
+ detectl -p qradar alerts list
119
+ detectl -p qradar query "SELECT UTF8(payload) AS payload FROM events WHERE sourceip='10.0.0.5'"
120
+
121
+ detectl -p sumologic rules create -f examples/rules/c2_beacon_suspicious_port.json
122
+ detectl -p sumologic lists list --kind blocklist
123
+ detectl -p sumologic query "error | count by sourcehost"
124
+
125
+ detectl -p chronicle rules create -f examples/rules/mimikatz_credential_dumping.json
126
+ detectl -p chronicle lists create -f examples/lists/vip_watchlist_usernames.json
127
+ detectl -p chronicle query 'principal.hostname="host1" and target.process.file.full_path contains "mimikatz.exe"'
128
+ ```
129
+
130
+ Every command prints JSON to stdout, so it composes with `jq` and shell
131
+ pipelines the way a real ops CLI should.
132
+
133
+ ### Pairs well with [sigmux](https://github.com/kylemain/sigmux)
134
+
135
+ sigmux compiles a portable Sigma detection rule into per-platform query syntax, and its target names match detectl's platform names 1:1 on purpose (`elastic`, `crowdstrike`, `sentinel`, `splunk`, `qradar`, `sumologic`, `chronicle`). detectl imports sigmux as a library (the `sigma` extra) to fold "convert, then create" into one step:
136
+
137
+ ```bash
138
+ detectl -p elastic rules create-from-sigma my_rule.yml
139
+ ```
140
+
141
+ `rules create-from-sigma` parses the Sigma rule, picks the sigmux target that matches `--platform` automatically (never a manual mapping you can get out of sync), and creates it as a live detection rule. Add `--dry-run` to see the full converted query and rule metadata -- Terraform-plan style -- before anything is actually created:
142
+
143
+ ```bash
144
+ detectl -p qradar rules create-from-sigma my_rule.yml --dry-run
145
+ ```
146
+
147
+ A few platforms need one extra piece of platform-specific context a generic Sigma rule doesn't carry (CrowdStrike's IOA rule group, Sumo Logic's Monitors folder) -- pass it with repeatable `--raw KEY=VALUE`:
148
+
149
+ ```bash
150
+ detectl -p sumologic rules create-from-sigma my_rule.yml --raw parent_id=folder123
151
+ ```
152
+
153
+ This isn't just a documented pairing: a separate `integration` job in this repo's CI checks out sigmux fresh, spins up a real Elasticsearch, and runs a full Sigma rule → sigmux → live Elasticsearch → detectl round trip against it end to end (see `scripts/integration_test_elastic.py`) -- so the two projects staying compatible is something CI actually verifies, not just a README claim.
154
+
155
+ The lower-level pairing (convert with sigmux, then feed the raw query text into `detectl query` yourself) still works too, and is what `create-from-sigma` does internally for the rule-creation path:
156
+
157
+ ```bash
158
+ sigmux convert my_rule.yml -t elastic -o out/
159
+ detectl -p elastic query "$(cat out/my_rule.elastic.json)"
160
+
161
+ sigmux convert my_rule.yml -t crowdstrike -o out/
162
+ detectl -p crowdstrike query "$(cat out/my_rule.crowdstrike.lql)"
163
+ ```
164
+
165
+ ## Architecture
166
+
167
+ - `detectl/models.py` -- canonical, platform-agnostic dataclasses (`Rule`,
168
+ `ListObject`, `Alert`, `QueryResult`). Every adapter converts to/from
169
+ these at its own API boundary; callers only ever see one consistent
170
+ shape. Each model carries a `raw` field with the untouched platform
171
+ payload for anything the common fields don't capture.
172
+ - `detectl/adapters/base.py` -- the abstract `SIEMAdapter` interface every
173
+ platform implements, plus a small `HttpMixin` that centralizes HTTP error
174
+ translation (`AuthenticationError`, `NotFoundError`, `APIError`) so
175
+ concrete adapters don't each reimplement it.
176
+ - `detectl/adapters/{splunk,elastic,sentinel,crowdstrike,qradar,sumologic,chronicle}.py`
177
+ -- one self-contained file per platform, each mapping the canonical
178
+ interface onto that platform's real REST API.
179
+ - `detectl/config.py` -- per-platform config loading from YAML and/or
180
+ environment variables.
181
+ - `detectl/cli.py` -- the click-based CLI wiring the above together,
182
+ including the sigmux bridge (`rules create-from-sigma`) and the
183
+ Terraform-plan-style `--dry-run` diff view.
184
+ - `scripts/integration_test_elastic.py` -- the live, network-touching
185
+ Sigma → sigmux → Elasticsearch → detectl round trip that CI's
186
+ `integration` job runs (see Testing below); `scripts/generate_coverage_badge.py`
187
+ is the self-hosted badge renderer behind the coverage badge above.
188
+
189
+ ### Adding a new platform
190
+
191
+ Implement `SIEMAdapter` (see `detectl/adapters/base.py` for the full
192
+ method list) in a new file under `detectl/adapters/`, register it in
193
+ `detectl/adapters/__init__.py`'s `REGISTRY`, and add its required config
194
+ fields to `detectl/config.py`'s `REQUIRED_FIELDS`/`OPTIONAL_FIELDS`. Not
195
+ every platform needs to support every operation -- raise
196
+ `UnsupportedOperationError` with a clear explanation rather than faking
197
+ support (see Splunk's `set_alert_status`, or CrowdStrike's `run_query` when
198
+ Falcon LogScale isn't configured).
199
+
200
+ ## Known limitations
201
+
202
+ A few platforms don't have a clean native equivalent for one of detectl's
203
+ canonical resources. Rather than papering over the mismatch, each adapter
204
+ documents its own convention at the top of its file:
205
+
206
+ - **The core Falcon platform API has no ad-hoc event query endpoint**
207
+ comparable to Splunk SPL, Elasticsearch DSL, or Sentinel KQL -- Falcon
208
+ exposes detections/alerts/IOCs as discrete resources, not a general query
209
+ surface over raw events. `run_query` instead talks to **Falcon LogScale**,
210
+ a genuinely separate CrowdStrike product with its own base URL and its
211
+ own credential (a LogScale Personal API token, distinct from the Falcon
212
+ `client_id`/`client_secret` used for rules/lists/alerts). It's optional:
213
+ configure `logscale_url`/`logscale_token`/`logscale_repository` (see
214
+ `examples/config.yml.example`) to enable it; without them, `run_query`
215
+ raises `UnsupportedOperationError` explaining how to turn it on. LogScale
216
+ query jobs are asynchronous, so `run_query` polls the job (`poll_interval`
217
+ seconds between checks, up to `max_polls` times) until it reports done.
218
+ - **Splunk's fired-alerts API has no settable status field** (no ack/close
219
+ concept the way Elastic signals or Sentinel incidents have) --
220
+ `set_alert_status` raises `UnsupportedOperationError`.
221
+ - **Kibana's Lists API has no native "kind"** (watchlist vs. exclusion vs.
222
+ allow/block vs. suppression) -- the Elastic adapter stores it in the
223
+ list's `meta.detectl_kind` field as a convention.
224
+ - **CrowdStrike's IOC API has no named-list container** at all -- IOCs are
225
+ individually-tagged indicators, so the CrowdStrike adapter groups them
226
+ into named lists via a `detectl_list:{name}` tag, and infers `kind` from
227
+ each IOC's `action` field (allow/block/detect).
228
+ - **CrowdStrike custom IOA rules are always scoped to a parent rule
229
+ group** -- there's no bare, group-less rule -- so rule IDs in that
230
+ adapter are encoded as `"{rule_group_id}:{instance_id}"`.
231
+ - IOC type inference (`ipv4` / `md5` / `sha1` / `sha256` / `domain`) in the
232
+ CrowdStrike adapter is a heuristic based on the value's shape, not a
233
+ caller-supplied type.
234
+ - **QRadar's Custom Rules Engine has no API for authoring rule logic** --
235
+ `/analytics/rules` only manages metadata (enable/disable, delete) for
236
+ rules that already exist; new rule logic has to be built through the
237
+ in-product Rule Wizard. `create_rule`/`update_rule` raise
238
+ `UnsupportedOperationError`; use `enable_rule`/`disable_rule` instead.
239
+ - **QRadar Reference Sets have no native "kind"** -- same `detectl_kind:
240
+ {kind}` tag convention as Elastic's `meta.detectl_kind`, stored in the
241
+ set's `description` field.
242
+ - **Sumo Logic Monitors need a destination folder** (Monitors Library is a
243
+ folder tree, there's no bare/folder-less monitor) -- `create_rule`
244
+ requires `rule.raw["parent_id"]`, same convention as CrowdStrike's
245
+ `rule.raw["rule_group_id"]` for Custom IOA rules. Updates need the
246
+ monitor's current `version` for optimistic concurrency, so
247
+ `update_rule`/`set_rule_enabled` do a read-modify-write.
248
+ - **Sumo Logic Cloud SIEM Match Lists have no "kind" field** (they have a
249
+ required `targetColumn` describing the *value type* -- IP, domain, file
250
+ hash, ... -- instead) -- same tag-in-description convention as QRadar.
251
+ Removing items needs match-list-item IDs, not raw values, so
252
+ `remove_list_items` reads the current items first to resolve them.
253
+ - **Chronicle reference lists cannot be deleted via the API at all**
254
+ (confirmed directly in Google's own Terraform provider source, which
255
+ just drops the resource from state rather than deleting it) --
256
+ `delete_list` raises `UnsupportedOperationError` rather than silently
257
+ no-op'ing.
258
+ - **Chronicle detections only exist scoped to the rule that generated
259
+ them** -- `list_alerts` requires a `rule_id` filter, and `get_alert` IDs
260
+ are encoded as `"{rule_id}:{detection_id}"`, same shape as CrowdStrike's
261
+ `"{rule_group_id}:{instance_id}"`. Detection triage/status lives in
262
+ Chronicle's separate SOAR/case-management module, not a simple status
263
+ field here, so `set_alert_status` raises `UnsupportedOperationError`.
264
+ - **Chronicle auth is a pre-obtained OAuth2 bearer token, not a full
265
+ service-account flow** -- signing a JWT with an RSA private key is real
266
+ crypto, out of scope for a dependency-light client. Get one with
267
+ `gcloud auth print-access-token` (or your own refresh cron) and set it
268
+ as `access_token`.
269
+
270
+ ## Testing
271
+
272
+ No `pytest` dependency -- the whole suite runs on the standard library's
273
+ `unittest`. Every adapter test injects a fake `requests.Session` stand-in
274
+ (see `tests/helpers.py`) that asserts on exact HTTP calls and returns
275
+ canned responses, so the suite never touches the network and needs no
276
+ credentials:
277
+
278
+ ```bash
279
+ python -m unittest discover -v
280
+ ```
281
+
282
+ That's the fast, always-run signal that actually gates merges. Layered on top of it, a separate `integration` job in CI (see `scripts/integration_test_elastic.py`) deliberately does touch the network: it checks out sigmux, spins up a real Elasticsearch service container, and runs a full Sigma rule → sigmux → live Elasticsearch → detectl pipeline end to end. It's `continue-on-error` and its own job so a live-service flake never reddens the unit-test signal above.
283
+
284
+ ## License
285
+
286
+ MIT
@@ -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"
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()