detectl 0.2.0__tar.gz → 0.2.1__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 → detectl-0.2.1}/PKG-INFO +68 -16
- {detectl-0.2.0 → detectl-0.2.1}/README.md +67 -15
- {detectl-0.2.0 → detectl-0.2.1}/detectl/__init__.py +1 -1
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/PKG-INFO +68 -16
- {detectl-0.2.0 → detectl-0.2.1}/pyproject.toml +1 -1
- {detectl-0.2.0 → detectl-0.2.1}/LICENSE +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/__main__.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/__init__.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/base.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/chronicle.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/crowdstrike.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/elastic.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/qradar.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/sentinel.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/splunk.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/adapters/sumologic.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/cli.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/config.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/exceptions.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl/models.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/SOURCES.txt +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/dependency_links.txt +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/entry_points.txt +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/requires.txt +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/detectl.egg-info/top_level.txt +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/setup.cfg +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/tests/test_cli.py +0 -0
- {detectl-0.2.0 → detectl-0.2.1}/tests/test_config.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: detectl
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.1
|
|
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
|
[](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
|
|
36
36
|
[](#testing)
|
|
37
|
+
[](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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
191
|
-
detectl -p elastic query "$(cat out/
|
|
217
|
+
sigmux convert mimikatz.yml -t elastic -o out/
|
|
218
|
+
detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
|
|
192
219
|
|
|
193
|
-
sigmux convert
|
|
194
|
-
detectl -p crowdstrike query "$(cat out/
|
|
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
|
[](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
|
|
4
4
|
[](#testing)
|
|
5
|
+
[](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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
159
|
-
detectl -p elastic query "$(cat out/
|
|
185
|
+
sigmux convert mimikatz.yml -t elastic -o out/
|
|
186
|
+
detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
|
|
160
187
|
|
|
161
|
-
sigmux convert
|
|
162
|
-
detectl -p crowdstrike query "$(cat out/
|
|
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
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: detectl
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.1
|
|
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
|
[](https://github.com/kylemain/detectl/actions/workflows/ci.yml)
|
|
36
36
|
[](#testing)
|
|
37
|
+
[](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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
191
|
-
detectl -p elastic query "$(cat out/
|
|
217
|
+
sigmux convert mimikatz.yml -t elastic -o out/
|
|
218
|
+
detectl -p elastic query "$(cat out/mimikatz.elastic.json)"
|
|
192
219
|
|
|
193
|
-
sigmux convert
|
|
194
|
-
detectl -p crowdstrike query "$(cat out/
|
|
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.
|
|
7
|
+
version = "0.2.1"
|
|
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"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|