detectl 0.2.0__tar.gz → 0.2.2__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.
Files changed (28) hide show
  1. {detectl-0.2.0 → detectl-0.2.2}/PKG-INFO +68 -16
  2. {detectl-0.2.0 → detectl-0.2.2}/README.md +67 -15
  3. {detectl-0.2.0 → detectl-0.2.2}/detectl/__init__.py +1 -1
  4. {detectl-0.2.0 → detectl-0.2.2}/detectl/cli.py +58 -5
  5. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/PKG-INFO +68 -16
  6. {detectl-0.2.0 → detectl-0.2.2}/pyproject.toml +1 -1
  7. {detectl-0.2.0 → detectl-0.2.2}/tests/test_cli.py +18 -0
  8. {detectl-0.2.0 → detectl-0.2.2}/LICENSE +0 -0
  9. {detectl-0.2.0 → detectl-0.2.2}/detectl/__main__.py +0 -0
  10. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/__init__.py +0 -0
  11. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/base.py +0 -0
  12. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/chronicle.py +0 -0
  13. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/crowdstrike.py +0 -0
  14. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/elastic.py +0 -0
  15. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/qradar.py +0 -0
  16. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/sentinel.py +0 -0
  17. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/splunk.py +0 -0
  18. {detectl-0.2.0 → detectl-0.2.2}/detectl/adapters/sumologic.py +0 -0
  19. {detectl-0.2.0 → detectl-0.2.2}/detectl/config.py +0 -0
  20. {detectl-0.2.0 → detectl-0.2.2}/detectl/exceptions.py +0 -0
  21. {detectl-0.2.0 → detectl-0.2.2}/detectl/models.py +0 -0
  22. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/SOURCES.txt +0 -0
  23. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/dependency_links.txt +0 -0
  24. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/entry_points.txt +0 -0
  25. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/requires.txt +0 -0
  26. {detectl-0.2.0 → detectl-0.2.2}/detectl.egg-info/top_level.txt +0 -0
  27. {detectl-0.2.0 → detectl-0.2.2}/setup.cfg +0 -0
  28. {detectl-0.2.0 → detectl-0.2.2}/tests/test_config.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: detectl
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
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
5
  Author: Kyle Main
6
6
  License: MIT
@@ -34,6 +34,7 @@ Dynamic: license-file
34
34
 
35
35
  [![CI](https://github.com/kylemain/detectl/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
36
36
  [![coverage](coverage.svg)](#testing)
37
+ [![PyPI](https://img.shields.io/pypi/v/detectl)](https://pypi.org/project/detectl/)
37
38
 
38
39
  A CLI (and Python library) for managing detection rules, tuning lists
39
40
  (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
@@ -84,16 +85,25 @@ real public REST API -- not a wrapper around any vendor SDK.
84
85
 
85
86
  ## Install
86
87
 
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
+ Published on PyPI. In a fresh terminal, with no prior setup:
89
+
90
+ ```bash
91
+ python3 -m venv .venv
92
+ source .venv/bin/activate
93
+ pip install "detectl[sigma,dryrun]"
94
+ ```
95
+
96
+ The quotes matter -- without them, zsh (macOS's default shell) treats `[...]` as a glob pattern and errors instead of installing. `sigma` pulls in [sigmux](https://github.com/kylemain/sigmux) (for `rules create-from-sigma`); `dryrun` pulls in `rich` (for `--dry-run`'s diff view). Both are optional -- plain `pip install detectl` works fine for everything else. And `pip install detectl` alone, outside a venv, will likely be refused on a modern Mac -- recent Python installs block bare system-wide installs on purpose, which the two lines above sidestep.
97
+
98
+ Prefer [pipx](https://pipx.pypa.io) and don't want to think about venvs at all: `pipx install "detectl[sigma,dryrun]"` (one command, isolation handled automatically).
99
+
100
+ The Usage examples below reference files under `examples/`, so to run them verbatim, clone the repo instead and install in editable mode:
88
101
 
89
102
  ```bash
90
103
  git clone https://github.com/kylemain/detectl.git
91
104
  cd detectl
92
105
  python3 -m venv .venv
93
106
  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
107
  pip install -e ".[sigma,dryrun]"
98
108
  ```
99
109
 
@@ -162,36 +172,53 @@ detectl -p chronicle query 'principal.hostname="host1" and target.process.file.f
162
172
  Every command prints JSON to stdout, so it composes with `jq` and shell
163
173
  pipelines the way a real ops CLI should.
164
174
 
175
+ ### Try it with the bundled example rules (no credentials needed)
176
+
177
+ `examples/rules/` has five real detection rules spanning credential access, web shells, persistence, and C2 -- pointed at five different platforms below, all with `--dry-run` so nothing needs to be configured first:
178
+
179
+ ```bash
180
+ detectl -p splunk rules create -f examples/rules/suspicious_powershell.json --dry-run
181
+ detectl -p elastic rules create -f examples/rules/mimikatz_credential_dumping.json --dry-run
182
+ detectl -p chronicle rules create -f examples/rules/webshell_iis_worker_process.json --dry-run
183
+ detectl -p qradar rules create -f examples/rules/registry_run_key_persistence.json --dry-run
184
+ detectl -p sumologic rules create -f examples/rules/c2_beacon_suspicious_port.json --dry-run
185
+ ```
186
+
187
+ Drop `--dry-run` on any of those and it becomes a real `rules create` call against that platform -- at which point it needs credentials configured for it (see Configure above). `examples/lists/` has five example lists (watchlist, blocklist, allowlist, and suppression) if you want to try `lists create` the same way, though list creation doesn't have a `--dry-run` mode yet.
188
+
165
189
  ### Pairs well with [sigmux](https://github.com/kylemain/sigmux)
166
190
 
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:
191
+ 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.
192
+
193
+ Try it right now, no credentials or config needed -- grab a real example rule and run it with `--dry-run`, which shows the full converted query and rule metadata (Terraform-plan style) without touching any platform:
168
194
 
169
195
  ```bash
170
- detectl -p elastic rules create-from-sigma my_rule.yml
196
+ curl -o mimikatz.yml https://raw.githubusercontent.com/kylemain/sigmux/main/examples/mimikatz_execution.yml
197
+ detectl -p elastic rules create-from-sigma mimikatz.yml --dry-run
171
198
  ```
172
199
 
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:
200
+ Swap `elastic` for `qradar`, `crowdstrike`, `chronicle`, etc. to see the same rule converted differently per platform. Drop `--dry-run` and it actually creates the rule -- that part does need real credentials in `~/.detectl/config.yml` first (see Configure above):
174
201
 
175
202
  ```bash
176
- detectl -p qradar rules create-from-sigma my_rule.yml --dry-run
203
+ detectl -p elastic rules create-from-sigma mimikatz.yml
177
204
  ```
178
205
 
179
206
  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
207
 
181
208
  ```bash
182
- detectl -p sumologic rules create-from-sigma my_rule.yml --raw parent_id=folder123
209
+ detectl -p sumologic rules create-from-sigma mimikatz.yml --raw parent_id=folder123
183
210
  ```
184
211
 
185
212
  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
213
 
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:
214
+ 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. `sigmux convert` runs with no credentials either way; `detectl query` (like `rules create-from-sigma` without `--dry-run`) needs a real, configured platform to actually query:
188
215
 
189
216
  ```bash
190
- sigmux convert my_rule.yml -t elastic -o out/
191
- detectl -p elastic query "$(cat out/my_rule.elastic.json)"
217
+ sigmux convert mimikatz.yml -t elastic -o out/
218
+ detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
192
219
 
193
- sigmux convert my_rule.yml -t crowdstrike -o out/
194
- detectl -p crowdstrike query "$(cat out/my_rule.crowdstrike.lql)"
220
+ sigmux convert mimikatz.yml -t crowdstrike -o out/
221
+ detectl -p crowdstrike query "$(cat out/mimikatz.crowdstrike.lql)"
195
222
  ```
196
223
 
197
224
  ## Architecture
@@ -311,7 +338,32 @@ credentials:
311
338
  python -m unittest discover -v
312
339
  ```
313
340
 
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.
341
+ 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. The [Actions tab](https://github.com/kylemain/detectl/actions/workflows/ci.yml) is the easiest way to see it passing without running anything yourself.
342
+
343
+ ### Optional: run the live Elasticsearch integration test yourself
344
+
345
+ This needs [Docker Desktop](https://www.docker.com/products/docker-desktop/) and pulls a ~600MB image, so it's not part of the quick-start flow above -- but if you want to watch the actual pipeline hit a real Elasticsearch rather than take CI's word for it:
346
+
347
+ ```bash
348
+ git clone https://github.com/kylemain/detectl.git && cd detectl
349
+ git clone https://github.com/kylemain/sigmux ../sigmux
350
+ python3 -m venv .venv
351
+ source .venv/bin/activate
352
+ pip install -e ../sigmux -e .
353
+
354
+ docker run -d --name detectl-demo-es -p 9200:9200 \
355
+ -e discovery.type=single-node -e xpack.security.enabled=false \
356
+ docker.elastic.co/elasticsearch/elasticsearch:8.13.4
357
+
358
+ # wait for it to report healthy (takes ~10-20s)
359
+ until curl -sf http://localhost:9200/_cluster/health; do sleep 2; done
360
+
361
+ python scripts/integration_test_elastic.py
362
+
363
+ docker stop detectl-demo-es && docker rm detectl-demo-es
364
+ ```
365
+
366
+ That's the exact same image, config, and script CI runs -- just driven locally instead of as a GitHub Actions service container.
315
367
 
316
368
  ## License
317
369
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  [![CI](https://github.com/kylemain/detectl/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
4
4
  [![coverage](coverage.svg)](#testing)
5
+ [![PyPI](https://img.shields.io/pypi/v/detectl)](https://pypi.org/project/detectl/)
5
6
 
6
7
  A CLI (and Python library) for managing detection rules, tuning lists
7
8
  (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
@@ -52,16 +53,25 @@ real public REST API -- not a wrapper around any vendor SDK.
52
53
 
53
54
  ## Install
54
55
 
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
+ Published on PyPI. In a fresh terminal, with no prior setup:
57
+
58
+ ```bash
59
+ python3 -m venv .venv
60
+ source .venv/bin/activate
61
+ pip install "detectl[sigma,dryrun]"
62
+ ```
63
+
64
+ The quotes matter -- without them, zsh (macOS's default shell) treats `[...]` as a glob pattern and errors instead of installing. `sigma` pulls in [sigmux](https://github.com/kylemain/sigmux) (for `rules create-from-sigma`); `dryrun` pulls in `rich` (for `--dry-run`'s diff view). Both are optional -- plain `pip install detectl` works fine for everything else. And `pip install detectl` alone, outside a venv, will likely be refused on a modern Mac -- recent Python installs block bare system-wide installs on purpose, which the two lines above sidestep.
65
+
66
+ Prefer [pipx](https://pipx.pypa.io) and don't want to think about venvs at all: `pipx install "detectl[sigma,dryrun]"` (one command, isolation handled automatically).
67
+
68
+ The Usage examples below reference files under `examples/`, so to run them verbatim, clone the repo instead and install in editable mode:
56
69
 
57
70
  ```bash
58
71
  git clone https://github.com/kylemain/detectl.git
59
72
  cd detectl
60
73
  python3 -m venv .venv
61
74
  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
75
  pip install -e ".[sigma,dryrun]"
66
76
  ```
67
77
 
@@ -130,36 +140,53 @@ detectl -p chronicle query 'principal.hostname="host1" and target.process.file.f
130
140
  Every command prints JSON to stdout, so it composes with `jq` and shell
131
141
  pipelines the way a real ops CLI should.
132
142
 
143
+ ### Try it with the bundled example rules (no credentials needed)
144
+
145
+ `examples/rules/` has five real detection rules spanning credential access, web shells, persistence, and C2 -- pointed at five different platforms below, all with `--dry-run` so nothing needs to be configured first:
146
+
147
+ ```bash
148
+ detectl -p splunk rules create -f examples/rules/suspicious_powershell.json --dry-run
149
+ detectl -p elastic rules create -f examples/rules/mimikatz_credential_dumping.json --dry-run
150
+ detectl -p chronicle rules create -f examples/rules/webshell_iis_worker_process.json --dry-run
151
+ detectl -p qradar rules create -f examples/rules/registry_run_key_persistence.json --dry-run
152
+ detectl -p sumologic rules create -f examples/rules/c2_beacon_suspicious_port.json --dry-run
153
+ ```
154
+
155
+ Drop `--dry-run` on any of those and it becomes a real `rules create` call against that platform -- at which point it needs credentials configured for it (see Configure above). `examples/lists/` has five example lists (watchlist, blocklist, allowlist, and suppression) if you want to try `lists create` the same way, though list creation doesn't have a `--dry-run` mode yet.
156
+
133
157
  ### Pairs well with [sigmux](https://github.com/kylemain/sigmux)
134
158
 
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:
159
+ 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.
160
+
161
+ Try it right now, no credentials or config needed -- grab a real example rule and run it with `--dry-run`, which shows the full converted query and rule metadata (Terraform-plan style) without touching any platform:
136
162
 
137
163
  ```bash
138
- detectl -p elastic rules create-from-sigma my_rule.yml
164
+ curl -o mimikatz.yml https://raw.githubusercontent.com/kylemain/sigmux/main/examples/mimikatz_execution.yml
165
+ detectl -p elastic rules create-from-sigma mimikatz.yml --dry-run
139
166
  ```
140
167
 
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:
168
+ Swap `elastic` for `qradar`, `crowdstrike`, `chronicle`, etc. to see the same rule converted differently per platform. Drop `--dry-run` and it actually creates the rule -- that part does need real credentials in `~/.detectl/config.yml` first (see Configure above):
142
169
 
143
170
  ```bash
144
- detectl -p qradar rules create-from-sigma my_rule.yml --dry-run
171
+ detectl -p elastic rules create-from-sigma mimikatz.yml
145
172
  ```
146
173
 
147
174
  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
175
 
149
176
  ```bash
150
- detectl -p sumologic rules create-from-sigma my_rule.yml --raw parent_id=folder123
177
+ detectl -p sumologic rules create-from-sigma mimikatz.yml --raw parent_id=folder123
151
178
  ```
152
179
 
153
180
  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
181
 
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:
182
+ 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. `sigmux convert` runs with no credentials either way; `detectl query` (like `rules create-from-sigma` without `--dry-run`) needs a real, configured platform to actually query:
156
183
 
157
184
  ```bash
158
- sigmux convert my_rule.yml -t elastic -o out/
159
- detectl -p elastic query "$(cat out/my_rule.elastic.json)"
185
+ sigmux convert mimikatz.yml -t elastic -o out/
186
+ detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
160
187
 
161
- sigmux convert my_rule.yml -t crowdstrike -o out/
162
- detectl -p crowdstrike query "$(cat out/my_rule.crowdstrike.lql)"
188
+ sigmux convert mimikatz.yml -t crowdstrike -o out/
189
+ detectl -p crowdstrike query "$(cat out/mimikatz.crowdstrike.lql)"
163
190
  ```
164
191
 
165
192
  ## Architecture
@@ -279,7 +306,32 @@ credentials:
279
306
  python -m unittest discover -v
280
307
  ```
281
308
 
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.
309
+ 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. The [Actions tab](https://github.com/kylemain/detectl/actions/workflows/ci.yml) is the easiest way to see it passing without running anything yourself.
310
+
311
+ ### Optional: run the live Elasticsearch integration test yourself
312
+
313
+ This needs [Docker Desktop](https://www.docker.com/products/docker-desktop/) and pulls a ~600MB image, so it's not part of the quick-start flow above -- but if you want to watch the actual pipeline hit a real Elasticsearch rather than take CI's word for it:
314
+
315
+ ```bash
316
+ git clone https://github.com/kylemain/detectl.git && cd detectl
317
+ git clone https://github.com/kylemain/sigmux ../sigmux
318
+ python3 -m venv .venv
319
+ source .venv/bin/activate
320
+ pip install -e ../sigmux -e .
321
+
322
+ docker run -d --name detectl-demo-es -p 9200:9200 \
323
+ -e discovery.type=single-node -e xpack.security.enabled=false \
324
+ docker.elastic.co/elasticsearch/elasticsearch:8.13.4
325
+
326
+ # wait for it to report healthy (takes ~10-20s)
327
+ until curl -sf http://localhost:9200/_cluster/health; do sleep 2; done
328
+
329
+ python scripts/integration_test_elastic.py
330
+
331
+ docker stop detectl-demo-es && docker rm detectl-demo-es
332
+ ```
333
+
334
+ That's the exact same image, config, and script CI runs -- just driven locally instead of as a GitHub Actions service container.
283
335
 
284
336
  ## License
285
337
 
@@ -8,4 +8,4 @@ under detectl.adapters, all implementing the same abstract interface
8
8
  alerts, and raw event queries.
9
9
  """
10
10
 
11
- __version__ = "0.1.0"
11
+ __version__ = "0.2.2"
@@ -59,9 +59,7 @@ def _load_sigmux():
59
59
  from sigmux.rule import SigmaRule
60
60
  except ImportError as exc:
61
61
  raise click.ClickException(
62
- "rules create-from-sigma needs sigmux installed: pip install 'detectl[sigma]' "
63
- "(sigmux isn't on PyPI yet -- that extra installs it straight from "
64
- "https://github.com/kylemain/sigmux)"
62
+ "rules create-from-sigma needs sigmux installed: pip install 'detectl[sigma]'"
65
63
  ) from exc
66
64
  return SigmaRule, get_backend
67
65
 
@@ -78,6 +76,40 @@ def _load_rich():
78
76
  return Console, Panel, Text
79
77
 
80
78
 
79
+ def _try_load_rich():
80
+ """Soft-import counterpart to _load_rich(), for callers (like `targets`)
81
+ that should still work perfectly well without the optional `dryrun`
82
+ extra -- falls back to (None, None) instead of raising."""
83
+ try:
84
+ from rich.console import Console
85
+ from rich.table import Table
86
+ except ImportError:
87
+ return None, None
88
+ return Console, Table
89
+
90
+
91
+ def _stdout_is_tty() -> bool:
92
+ """Broken out as its own function (rather than an inline sys.stdout.isatty()
93
+ call) purely so tests can patch it directly -- Click's CliRunner swaps
94
+ out sys.stdout for a captured buffer during invoke(), which would make
95
+ patching sys.stdout.isatty itself unreliable."""
96
+ return sys.stdout.isatty()
97
+
98
+
99
+ # Display metadata for `targets` only -- purely cosmetic. Colors match
100
+ # sigmux's _TARGET_INFO exactly for the same platform, since sigmux's
101
+ # target names and detectl's platform names are the same 1:1 set.
102
+ _PLATFORM_INFO: Dict[str, Dict[str, str]] = {
103
+ "splunk": {"query": "Splunk SPL", "rules": "Saved searches / correlation searches", "color": "orange3"},
104
+ "elastic": {"query": "Elasticsearch Query DSL", "rules": "Detection Engine rules", "color": "gold3"},
105
+ "sentinel": {"query": "Microsoft Sentinel (KQL)", "rules": "Scheduled Analytics Rules", "color": "deep_sky_blue1"},
106
+ "crowdstrike": {"query": "CrowdStrike Falcon LogScale (LQL)", "rules": "Custom IOA rules", "color": "magenta1"},
107
+ "qradar": {"query": "IBM QRadar (AQL)", "rules": "CRE rule metadata (enable/disable/delete)", "color": "green3"},
108
+ "chronicle": {"query": "Google Chronicle (YARA-L 2.0)", "rules": "Rules (YARA-L text)", "color": "cyan1"},
109
+ "sumologic": {"query": "Sumo Logic search query", "rules": "Monitors Library", "color": "red3"},
110
+ }
111
+
112
+
81
113
  def _append_field(body, sign: str, key: str, value: Any, style: str) -> None:
82
114
  if isinstance(value, str) and "\n" in value:
83
115
  body.append(f" {sign} {key}:\n", style=style)
@@ -145,9 +177,30 @@ def _adapter(ctx: click.Context) -> SIEMAdapter:
145
177
 
146
178
  @main.command()
147
179
  def targets():
148
- """List supported SIEM/EDR platforms."""
180
+ """List supported SIEM/EDR platforms.
181
+
182
+ Renders a colored table (matching sigmux's `targets` command) in an
183
+ interactive terminal. Falls back to a plain one-name-per-line list --
184
+ same as always -- when piped/redirected, or when rich isn't installed,
185
+ so `detectl targets | xargs ...`-style scripting still works exactly
186
+ as before.
187
+ """
188
+ Console, Table = _try_load_rich() if _stdout_is_tty() else (None, None)
189
+ if Console is None:
190
+ for name in sorted(REGISTRY):
191
+ click.echo(name)
192
+ return
193
+
194
+ table = Table(title="detectl supported platforms", header_style="bold")
195
+ table.add_column("Platform", style="bold")
196
+ table.add_column("Ad-hoc query language")
197
+ table.add_column("Rules resource")
149
198
  for name in sorted(REGISTRY):
150
- click.echo(name)
199
+ info = _PLATFORM_INFO.get(name, {})
200
+ color = info.get("color", "white")
201
+ table.add_row(f"[{color}]{name}[/{color}]", info.get("query", "--"), info.get("rules", "--"))
202
+
203
+ Console().print(table)
151
204
 
152
205
 
153
206
  @main.command("test-connection")
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: detectl
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
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
5
  Author: Kyle Main
6
6
  License: MIT
@@ -34,6 +34,7 @@ Dynamic: license-file
34
34
 
35
35
  [![CI](https://github.com/kylemain/detectl/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
36
36
  [![coverage](coverage.svg)](#testing)
37
+ [![PyPI](https://img.shields.io/pypi/v/detectl)](https://pypi.org/project/detectl/)
37
38
 
38
39
  A CLI (and Python library) for managing detection rules, tuning lists
39
40
  (watchlists, exclusion/allow/block lists, suppression lists, KV stores),
@@ -84,16 +85,25 @@ real public REST API -- not a wrapper around any vendor SDK.
84
85
 
85
86
  ## Install
86
87
 
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
+ Published on PyPI. In a fresh terminal, with no prior setup:
89
+
90
+ ```bash
91
+ python3 -m venv .venv
92
+ source .venv/bin/activate
93
+ pip install "detectl[sigma,dryrun]"
94
+ ```
95
+
96
+ The quotes matter -- without them, zsh (macOS's default shell) treats `[...]` as a glob pattern and errors instead of installing. `sigma` pulls in [sigmux](https://github.com/kylemain/sigmux) (for `rules create-from-sigma`); `dryrun` pulls in `rich` (for `--dry-run`'s diff view). Both are optional -- plain `pip install detectl` works fine for everything else. And `pip install detectl` alone, outside a venv, will likely be refused on a modern Mac -- recent Python installs block bare system-wide installs on purpose, which the two lines above sidestep.
97
+
98
+ Prefer [pipx](https://pipx.pypa.io) and don't want to think about venvs at all: `pipx install "detectl[sigma,dryrun]"` (one command, isolation handled automatically).
99
+
100
+ The Usage examples below reference files under `examples/`, so to run them verbatim, clone the repo instead and install in editable mode:
88
101
 
89
102
  ```bash
90
103
  git clone https://github.com/kylemain/detectl.git
91
104
  cd detectl
92
105
  python3 -m venv .venv
93
106
  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
107
  pip install -e ".[sigma,dryrun]"
98
108
  ```
99
109
 
@@ -162,36 +172,53 @@ detectl -p chronicle query 'principal.hostname="host1" and target.process.file.f
162
172
  Every command prints JSON to stdout, so it composes with `jq` and shell
163
173
  pipelines the way a real ops CLI should.
164
174
 
175
+ ### Try it with the bundled example rules (no credentials needed)
176
+
177
+ `examples/rules/` has five real detection rules spanning credential access, web shells, persistence, and C2 -- pointed at five different platforms below, all with `--dry-run` so nothing needs to be configured first:
178
+
179
+ ```bash
180
+ detectl -p splunk rules create -f examples/rules/suspicious_powershell.json --dry-run
181
+ detectl -p elastic rules create -f examples/rules/mimikatz_credential_dumping.json --dry-run
182
+ detectl -p chronicle rules create -f examples/rules/webshell_iis_worker_process.json --dry-run
183
+ detectl -p qradar rules create -f examples/rules/registry_run_key_persistence.json --dry-run
184
+ detectl -p sumologic rules create -f examples/rules/c2_beacon_suspicious_port.json --dry-run
185
+ ```
186
+
187
+ Drop `--dry-run` on any of those and it becomes a real `rules create` call against that platform -- at which point it needs credentials configured for it (see Configure above). `examples/lists/` has five example lists (watchlist, blocklist, allowlist, and suppression) if you want to try `lists create` the same way, though list creation doesn't have a `--dry-run` mode yet.
188
+
165
189
  ### Pairs well with [sigmux](https://github.com/kylemain/sigmux)
166
190
 
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:
191
+ 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.
192
+
193
+ Try it right now, no credentials or config needed -- grab a real example rule and run it with `--dry-run`, which shows the full converted query and rule metadata (Terraform-plan style) without touching any platform:
168
194
 
169
195
  ```bash
170
- detectl -p elastic rules create-from-sigma my_rule.yml
196
+ curl -o mimikatz.yml https://raw.githubusercontent.com/kylemain/sigmux/main/examples/mimikatz_execution.yml
197
+ detectl -p elastic rules create-from-sigma mimikatz.yml --dry-run
171
198
  ```
172
199
 
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:
200
+ Swap `elastic` for `qradar`, `crowdstrike`, `chronicle`, etc. to see the same rule converted differently per platform. Drop `--dry-run` and it actually creates the rule -- that part does need real credentials in `~/.detectl/config.yml` first (see Configure above):
174
201
 
175
202
  ```bash
176
- detectl -p qradar rules create-from-sigma my_rule.yml --dry-run
203
+ detectl -p elastic rules create-from-sigma mimikatz.yml
177
204
  ```
178
205
 
179
206
  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
207
 
181
208
  ```bash
182
- detectl -p sumologic rules create-from-sigma my_rule.yml --raw parent_id=folder123
209
+ detectl -p sumologic rules create-from-sigma mimikatz.yml --raw parent_id=folder123
183
210
  ```
184
211
 
185
212
  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
213
 
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:
214
+ 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. `sigmux convert` runs with no credentials either way; `detectl query` (like `rules create-from-sigma` without `--dry-run`) needs a real, configured platform to actually query:
188
215
 
189
216
  ```bash
190
- sigmux convert my_rule.yml -t elastic -o out/
191
- detectl -p elastic query "$(cat out/my_rule.elastic.json)"
217
+ sigmux convert mimikatz.yml -t elastic -o out/
218
+ detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
192
219
 
193
- sigmux convert my_rule.yml -t crowdstrike -o out/
194
- detectl -p crowdstrike query "$(cat out/my_rule.crowdstrike.lql)"
220
+ sigmux convert mimikatz.yml -t crowdstrike -o out/
221
+ detectl -p crowdstrike query "$(cat out/mimikatz.crowdstrike.lql)"
195
222
  ```
196
223
 
197
224
  ## Architecture
@@ -311,7 +338,32 @@ credentials:
311
338
  python -m unittest discover -v
312
339
  ```
313
340
 
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.
341
+ 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. The [Actions tab](https://github.com/kylemain/detectl/actions/workflows/ci.yml) is the easiest way to see it passing without running anything yourself.
342
+
343
+ ### Optional: run the live Elasticsearch integration test yourself
344
+
345
+ This needs [Docker Desktop](https://www.docker.com/products/docker-desktop/) and pulls a ~600MB image, so it's not part of the quick-start flow above -- but if you want to watch the actual pipeline hit a real Elasticsearch rather than take CI's word for it:
346
+
347
+ ```bash
348
+ git clone https://github.com/kylemain/detectl.git && cd detectl
349
+ git clone https://github.com/kylemain/sigmux ../sigmux
350
+ python3 -m venv .venv
351
+ source .venv/bin/activate
352
+ pip install -e ../sigmux -e .
353
+
354
+ docker run -d --name detectl-demo-es -p 9200:9200 \
355
+ -e discovery.type=single-node -e xpack.security.enabled=false \
356
+ docker.elastic.co/elasticsearch/elasticsearch:8.13.4
357
+
358
+ # wait for it to report healthy (takes ~10-20s)
359
+ until curl -sf http://localhost:9200/_cluster/health; do sleep 2; done
360
+
361
+ python scripts/integration_test_elastic.py
362
+
363
+ docker stop detectl-demo-es && docker rm detectl-demo-es
364
+ ```
365
+
366
+ That's the exact same image, config, and script CI runs -- just driven locally instead of as a GitHub Actions service container.
315
367
 
316
368
  ## License
317
369
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "detectl"
7
- version = "0.2.0"
7
+ version = "0.2.2"
8
8
  description = "A CLI for managing detection rules, tuning lists, alerts, and ad-hoc queries across multiple SIEM/EDR platforms through one consistent interface."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -55,6 +55,24 @@ class TestCli(unittest.TestCase):
55
55
  for name in ("splunk", "elastic", "sentinel", "crowdstrike"):
56
56
  self.assertIn(name, result.output)
57
57
 
58
+ def test_targets_plain_list_when_not_a_tty(self):
59
+ # CliRunner's captured output isn't a real tty, so this is really
60
+ # just documenting/pinning the default (piped) behavior explicitly.
61
+ result = self.runner.invoke(main, ["targets"])
62
+ self.assertEqual(result.exit_code, 0)
63
+ lines = result.output.strip().splitlines()
64
+ self.assertEqual(sorted(lines), sorted(["splunk", "elastic", "sentinel", "crowdstrike", "qradar", "sumologic", "chronicle"]))
65
+
66
+ @patch("detectl.cli._stdout_is_tty", return_value=True)
67
+ def test_targets_renders_rich_table_when_tty(self, _mock_tty):
68
+ result = self.runner.invoke(main, ["targets"])
69
+ self.assertEqual(result.exit_code, 0)
70
+ self.assertIn("detectl supported platforms", result.output)
71
+ for name in ("splunk", "elastic", "sentinel", "crowdstrike", "qradar", "sumologic", "chronicle"):
72
+ self.assertIn(name, result.output)
73
+ self.assertIn("Ad-hoc query language", result.output)
74
+ self.assertIn("Rules resource", result.output)
75
+
58
76
  def test_platform_required(self):
59
77
  result = self.runner.invoke(main, ["rules", "list"])
60
78
  self.assertNotEqual(result.exit_code, 0)
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes