detkit-cli 0.1.0__tar.gz

detkit_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 detkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detkit_cli-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: detkit-cli
+Version: 0.1.0
+Summary: dbt for detections — test, validate, and CI-gate Sigma detection rules as code.
+Author: detkit
+License: MIT
+Project-URL: Homepage, https://github.com/ELSATOAH/detkit
+Project-URL: Repository, https://github.com/ELSATOAH/detkit
+Project-URL: Issues, https://github.com/ELSATOAH/detkit/issues
+Keywords: sigma,detection-engineering,detection-as-code,siem,security,detections,blue-team,cybersecurity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# detkit — dbt for detections
+
+[![CI](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Test, validate, and CI-gate your Sigma detection rules **as code**, before they
+ever reach production.
+
+![detkit catching a broken detection before it ships](detkit-demo.gif)
+
+Detection engineers write rules in [Sigma](https://sigmahq.io/), commit them to
+Git, and ship them to a SIEM — but there's no standard way to *unit-test* a rule
+locally: does it actually fire on the attack it targets, and stay quiet on benign
+traffic? Today that's checked by hand, or in prod. detkit closes that loop.
+
+```
+detkit test ./rules        # run every rule against its sample events
+detkit validate ./rules    # structural + condition-reference checks
+```
+
+detkit is **open source (MIT)**, **self-hostable**, and **vendor-neutral** — it
+sits *alongside* your SIEM (Wazuh, Elastic, Splunk, Sentinel), not in front of
+it. Your logs and rules never leave your machine or CI runner.
+
+## Quickstart
+
+```bash
+pipx install git+https://github.com/ELSATOAH/detkit.git   # PyPI: `pipx install detkit-cli` (coming soon)
+
+detkit init         # scaffold a starter rule + test + a CI workflow
+detkit test rules   # -> green on the first run
+```
+
+Each rule gets a sibling `*.test.yml` describing sample events and whether the
+rule should match:
+
+```yaml
+# whoami_execution.test.yml
+tests:
+  - name: fires on whoami run by a normal user
+    event: { EventID: 4688, CommandLine: "cmd /c whoami /all", User: "alice" }
+    expect: match
+  - name: suppressed for SYSTEM
+    event: { EventID: 4688, CommandLine: "whoami", User: "SYSTEM" }
+    expect: no_match
+```
+
+`detkit test` exits non-zero on any failure, so you can drop it straight into CI
+and block a pull request that breaks a detection.
+
+## Use it in CI (GitHub Actions)
+
+Drop this into your **rules** repo to gate every pull request:
+
+```yaml
+# .github/workflows/detections.yml
+name: Detections
+on: [pull_request]
+jobs:
+  detkit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ELSATOAH/detkit@v0   # this repo's composite action
+        with:
+          path: rules                # where your Sigma rules live
+```
+
+A rule whose `*.test.yml` no longer passes now fails the check and blocks the
+merge — the same safety net dbt gives analytics engineers.
+
+## Why this, why now
+
+- **Detection-as-code is mainstream** (SigmaHQ, Elastic detection-rules, Splunk
+  ESCU) but the *test* step is missing — the same gap dbt filled for analytics.
+- **Self-host is a hard requirement, not a preference:** security telemetry can't
+  be shipped to someone else's cloud. That's the wedge closed SaaS SOC tools
+  (Dropzone, Prophet, Intezer) structurally can't serve.
+- **The community distributes it:** good detection tooling spreads bottom-up on
+  GitHub. detkit is built to be forked, extended, and shared.
+
+## Roadmap
+
+- `detkit generate` — AI-draft a rule **and its tests** from a natural-language
+  threat description (tests are mandatory, never optional).
+- More log schemas / field-mapping so one rule tests against multiple log sources.
+- Close the remaining gaps detkit currently warns on: nested/dotted field access
+  (~3% of rules) and `base64` modifiers — likely via
+  [pySigma](https://github.com/SigmaHQ/pySigma) for full-spec parsing.
+- Managed cloud (hosted runs, SSO, shared rule/test libraries) — the paid tier.
+  The tool stays free forever.
+
+## Status
+
+Early, but the core is real. detkit evaluates a rule's `detection`/`condition`
+against log events and runs tests around it — covering the features used by the
+**large majority of published SigmaHQ rules**: `contains`/`startswith`/`endswith`/
+`re` modifiers, value wildcards (`*`/`?`), `|cidr`, list-as-OR, keyword lists, and
+`X of` / `all of` conditions.
+
+What it can't yet evaluate (nested/dotted fields, `base64` modifiers) it **flags
+loudly** — `detkit validate` and `detkit test` print a `WARN` rather than return a
+confident wrong answer. A detection tool that's silently wrong is worse than none.
+
+Run the checks: `python tests/test_evaluator.py`. Limits are marked with
+`# ponytail:` comments in `detkit/evaluator.py`.
+
+MIT licensed. Contributions welcome.

detkit_cli-0.1.0/README.md

@@ -0,0 +1,107 @@
+# detkit — dbt for detections
+
+[![CI](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Test, validate, and CI-gate your Sigma detection rules **as code**, before they
+ever reach production.
+
+![detkit catching a broken detection before it ships](detkit-demo.gif)
+
+Detection engineers write rules in [Sigma](https://sigmahq.io/), commit them to
+Git, and ship them to a SIEM — but there's no standard way to *unit-test* a rule
+locally: does it actually fire on the attack it targets, and stay quiet on benign
+traffic? Today that's checked by hand, or in prod. detkit closes that loop.
+
+```
+detkit test ./rules        # run every rule against its sample events
+detkit validate ./rules    # structural + condition-reference checks
+```
+
+detkit is **open source (MIT)**, **self-hostable**, and **vendor-neutral** — it
+sits *alongside* your SIEM (Wazuh, Elastic, Splunk, Sentinel), not in front of
+it. Your logs and rules never leave your machine or CI runner.
+
+## Quickstart
+
+```bash
+pipx install git+https://github.com/ELSATOAH/detkit.git   # PyPI: `pipx install detkit-cli` (coming soon)
+
+detkit init         # scaffold a starter rule + test + a CI workflow
+detkit test rules   # -> green on the first run
+```
+
+Each rule gets a sibling `*.test.yml` describing sample events and whether the
+rule should match:
+
+```yaml
+# whoami_execution.test.yml
+tests:
+  - name: fires on whoami run by a normal user
+    event: { EventID: 4688, CommandLine: "cmd /c whoami /all", User: "alice" }
+    expect: match
+  - name: suppressed for SYSTEM
+    event: { EventID: 4688, CommandLine: "whoami", User: "SYSTEM" }
+    expect: no_match
+```
+
+`detkit test` exits non-zero on any failure, so you can drop it straight into CI
+and block a pull request that breaks a detection.
+
+## Use it in CI (GitHub Actions)
+
+Drop this into your **rules** repo to gate every pull request:
+
+```yaml
+# .github/workflows/detections.yml
+name: Detections
+on: [pull_request]
+jobs:
+  detkit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ELSATOAH/detkit@v0   # this repo's composite action
+        with:
+          path: rules                # where your Sigma rules live
+```
+
+A rule whose `*.test.yml` no longer passes now fails the check and blocks the
+merge — the same safety net dbt gives analytics engineers.
+
+## Why this, why now
+
+- **Detection-as-code is mainstream** (SigmaHQ, Elastic detection-rules, Splunk
+  ESCU) but the *test* step is missing — the same gap dbt filled for analytics.
+- **Self-host is a hard requirement, not a preference:** security telemetry can't
+  be shipped to someone else's cloud. That's the wedge closed SaaS SOC tools
+  (Dropzone, Prophet, Intezer) structurally can't serve.
+- **The community distributes it:** good detection tooling spreads bottom-up on
+  GitHub. detkit is built to be forked, extended, and shared.
+
+## Roadmap
+
+- `detkit generate` — AI-draft a rule **and its tests** from a natural-language
+  threat description (tests are mandatory, never optional).
+- More log schemas / field-mapping so one rule tests against multiple log sources.
+- Close the remaining gaps detkit currently warns on: nested/dotted field access
+  (~3% of rules) and `base64` modifiers — likely via
+  [pySigma](https://github.com/SigmaHQ/pySigma) for full-spec parsing.
+- Managed cloud (hosted runs, SSO, shared rule/test libraries) — the paid tier.
+  The tool stays free forever.
+
+## Status
+
+Early, but the core is real. detkit evaluates a rule's `detection`/`condition`
+against log events and runs tests around it — covering the features used by the
+**large majority of published SigmaHQ rules**: `contains`/`startswith`/`endswith`/
+`re` modifiers, value wildcards (`*`/`?`), `|cidr`, list-as-OR, keyword lists, and
+`X of` / `all of` conditions.
+
+What it can't yet evaluate (nested/dotted fields, `base64` modifiers) it **flags
+loudly** — `detkit validate` and `detkit test` print a `WARN` rather than return a
+confident wrong answer. A detection tool that's silently wrong is worse than none.
+
+Run the checks: `python tests/test_evaluator.py`. Limits are marked with
+`# ponytail:` comments in `detkit/evaluator.py`.
+
+MIT licensed. Contributions welcome.

detkit_cli-0.1.0/detkit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

detkit_cli-0.1.0/detkit/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

detkit_cli-0.1.0/detkit/cli.py

@@ -0,0 +1,226 @@
+"""detkit command line: test / validate / generate."""
+import argparse
+import glob
+import os
+import re
+import sys
+
+from .evaluator import event_matches_rule, scan_unsupported
+
+REQUIRED_KEYS = ("title", "logsource", "detection")
+
+
+def _load_yaml(path):
+    try:
+        import yaml
+    except ImportError:
+        sys.exit("detkit needs PyYAML: pip install pyyaml")
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+
+def _discover_rules(path):
+    if os.path.isfile(path):
+        return [path]
+    found = []
+    for pat in ("**/*.yml", "**/*.yaml"):
+        found += glob.glob(os.path.join(path, pat), recursive=True)
+    return sorted({f for f in found if not f.endswith((".test.yml", ".test.yaml"))})
+
+
+def _test_file_for(rule_path):
+    base = rule_path.rsplit(".", 1)[0]
+    for ext in (".test.yml", ".test.yaml"):
+        if os.path.exists(base + ext):
+            return base + ext
+    return None
+
+
+def cmd_test(args):
+    rules = _discover_rules(args.path)
+    if not rules:
+        print(f"no rules found under {args.path!r}")
+        return 1
+    passed = failed = untested = 0
+    for rule_path in rules:
+        rule = _load_yaml(rule_path)
+        detection = (rule or {}).get("detection")
+        if isinstance(detection, dict):
+            for warn in scan_unsupported(detection):
+                print(f"  ! {rule_path}  WARN: {warn} (result may be unreliable)")
+        test_path = _test_file_for(rule_path)
+        if not test_path:
+            untested += 1
+            print(f"  ? {rule_path}  (no .test.yml)")
+            continue
+        cases = (_load_yaml(test_path) or {}).get("tests", [])
+        for case in cases:
+            want = case.get("expect", "match") == "match"
+            try:
+                got = event_matches_rule(detection, case.get("event", {}))
+            except Exception as exc:  # a rule error should fail the test, not crash the run
+                failed += 1
+                print(f"  x {rule_path} :: {case.get('name', '?')}  ERROR: {exc}")
+                continue
+            if got == want:
+                passed += 1
+                print(f"  . {rule_path} :: {case.get('name', '?')}")
+            else:
+                failed += 1
+                verb = "fired" if got else "did not fire"
+                print(f"  x {rule_path} :: {case.get('name', '?')}  (rule {verb}, expected {case['expect']})")
+    print(f"\n{passed} passed, {failed} failed, {untested} rule(s) without tests")
+    return 1 if failed else 0
+
+
+def _validate_rule(rule):
+    errors = []
+    for key in REQUIRED_KEYS:
+        if key not in rule:
+            errors.append(f"missing top-level key '{key}'")
+    detection = rule.get("detection", {})
+    if isinstance(detection, dict):
+        if "condition" not in detection:
+            errors.append("detection block missing 'condition'")
+        else:
+            defined = {k for k in detection if k != "condition"}
+            referenced = set(re.findall(r"[A-Za-z0-9_]+\*?", str(detection["condition"])))
+            keywords = {"and", "or", "not", "of", "them", "all"}
+            for ref in referenced - keywords:
+                if ref.isdigit():
+                    continue
+                if ref.endswith("*"):
+                    if not any(d.startswith(ref[:-1]) for d in defined):
+                        errors.append(f"condition references '{ref}' but no identifier matches")
+                elif ref not in defined:
+                    errors.append(f"condition references undefined identifier '{ref}'")
+    return errors
+
+
+def cmd_validate(args):
+    rules = _discover_rules(args.path)
+    if not rules:
+        print(f"no rules found under {args.path!r}")
+        return 1
+    total_errors = total_warnings = 0
+    for rule_path in rules:
+        rule = _load_yaml(rule_path) or {}
+        errors = _validate_rule(rule)
+        detection = rule.get("detection")
+        warns = scan_unsupported(detection) if isinstance(detection, dict) else []
+        total_errors += len(errors)
+        total_warnings += len(warns)
+        print(f"  {'x' if errors else '!' if warns else '.'} {rule_path}")
+        for e in errors:
+            print(f"      - error: {e}")
+        for w in warns:
+            print(f"      - warn:  {w}")
+    print(f"\n{total_errors} error(s), {total_warnings} warning(s)")
+    return 1 if total_errors else 0
+
+
+_INIT_RULE = """\
+title: Whoami Execution
+id: 3a2b1c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
+status: experimental
+description: Example rule from `detkit init` — detects whoami, a common recon command. Replace with your own.
+logsource:
+  category: process_creation
+  product: windows
+detection:
+  selection:
+    CommandLine|contains: 'whoami'
+  condition: selection
+level: low
+"""
+
+_INIT_TEST = """\
+# Sample events proving the rule fires (and stays quiet). This is the point of detkit.
+tests:
+  - name: fires on whoami
+    event: { CommandLine: "cmd /c whoami /all" }
+    expect: match
+  - name: ignores an unrelated command
+    event: { CommandLine: "ipconfig /all" }
+    expect: no_match
+"""
+
+_INIT_WORKFLOW = """\
+name: Detections
+on: [pull_request, push]
+
+jobs:
+  detkit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - run: pip install detkit
+      - run: detkit test rules
+"""
+
+
+def cmd_init(args):
+    files = {
+        os.path.join("rules", "example_rule.yml"): _INIT_RULE,
+        os.path.join("rules", "example_rule.test.yml"): _INIT_TEST,
+        os.path.join(".github", "workflows", "detections.yml"): _INIT_WORKFLOW,
+    }
+    created = skipped = 0
+    for rel, content in files.items():
+        dest = os.path.join(args.path, rel)
+        if os.path.exists(dest):
+            skipped += 1
+            print(f"  skipped (exists): {dest}")
+            continue
+        parent = os.path.dirname(dest)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(dest, "w") as f:
+            f.write(content)
+        created += 1
+        print(f"  created: {dest}")
+    print(f"\n{created} file(s) created, {skipped} skipped.")
+    if created:
+        print("Next: run `detkit test rules` — you should see it pass.")
+    return 0
+
+
+def cmd_generate(args):
+    print(
+        "`detkit generate` is not implemented yet.\n"
+        "Planned: draft a Sigma rule AND its test cases from a natural-language\n"
+        "threat description via an LLM; you review and commit the code.\n"
+        "Design rule: generation must always emit tests, so every AI-drafted\n"
+        "detection ships with a runnable check. LLM client stays swappable."
+    )
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="detkit", description="Test Sigma detection rules as code.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_test = sub.add_parser("test", help="run rule tests against sample events")
+    p_test.add_argument("path", nargs="?", default=".")
+    p_test.set_defaults(func=cmd_test)
+
+    p_val = sub.add_parser("validate", help="structurally validate rules")
+    p_val.add_argument("path", nargs="?", default=".")
+    p_val.set_defaults(func=cmd_validate)
+
+    p_init = sub.add_parser("init", help="scaffold a starter rule + test + CI workflow")
+    p_init.add_argument("path", nargs="?", default=".")
+    p_init.set_defaults(func=cmd_init)
+
+    p_gen = sub.add_parser("generate", help="(planned) AI-draft a rule + tests")
+    p_gen.set_defaults(func=cmd_generate)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

detkit_cli-0.1.0/detkit/evaluator.py

@@ -0,0 +1,224 @@
+"""Evaluate a Sigma rule's detection block against a single log event.
+
+This is the core of detkit: unit-testing detection rules locally, the way
+dbt tests data models. It implements the common Sigma subset.
+
+# ponytail: common-subset evaluator (modifiers contains/startswith/endswith/re/cased/all/cidr,
+# value wildcards * and ?, list-OR, `N of them | N of prefix*`, and/or/not/parens). Ceilings:
+# no nested-field (dot) access, no |base64/|windash modifiers, no count()/timeframe aggregation,
+# matching is case-insensitive by default (real SIEM backends differ). Anything unsupported is
+# reported by scan_unsupported() so it fails loud instead of returning a wrong boolean. Upgrade
+# path: delegate to pySigma pipelines or a per-backend evaluator when a rule needs the full spec.
+"""
+import ipaddress
+import re
+
+__all__ = ["event_matches_rule", "scan_unsupported"]
+
+_SUPPORTED_MODS = {"contains", "startswith", "endswith", "re", "cased", "all", "cidr"}
+
+
+def event_matches_rule(detection: dict, event: dict) -> bool:
+    """Return True if `event` triggers the Sigma `detection` block."""
+    if "condition" not in detection:
+        raise ValueError("detection block missing 'condition'")
+    condition = detection["condition"]
+    identifiers = {k: v for k, v in detection.items() if k != "condition"}
+    matches = {name: _matches_identifier(spec, event) for name, spec in identifiers.items()}
+    conditions = condition if isinstance(condition, list) else [condition]
+    return any(_eval_condition(str(c), matches) for c in conditions)
+
+
+def _matches_identifier(spec, event) -> bool:
+    if isinstance(spec, list):
+        # list of maps => OR of maps; list of scalars => keyword search (any)
+        return any(
+            _matches_map(item, event) if isinstance(item, dict) else _keyword_match(item, event)
+            for item in spec
+        )
+    if isinstance(spec, dict):
+        return _matches_map(spec, event)
+    return _keyword_match(spec, event)
+
+
+def _matches_map(spec: dict, event: dict) -> bool:
+    return all(_matches_field(key, expected, event) for key, expected in spec.items())
+
+
+def _matches_field(key: str, expected, event: dict) -> bool:
+    parts = key.split("|")
+    field, mods = parts[0], [m.lower() for m in parts[1:]]
+    if field not in event:
+        return False
+    ev = event[field]
+    if isinstance(expected, list):
+        results = [_match_scalar(ev, x, mods) for x in expected]
+        return all(results) if "all" in mods else any(results)
+    return _match_scalar(ev, expected, mods)
+
+
+def _match_scalar(ev, expected, mods) -> bool:
+    cased = "cased" in mods
+    if "cidr" in mods:
+        return _cidr_match(ev, expected)
+    if "re" in mods:
+        return re.search(str(expected), str(ev), 0 if cased else re.IGNORECASE) is not None
+    if expected is None:
+        return ev is None
+    if isinstance(expected, bool):
+        return ev == expected
+    string_mod = any(m in mods for m in ("contains", "startswith", "endswith"))
+    if isinstance(expected, (int, float)) and not string_mod:
+        try:
+            return float(ev) == float(expected)
+        except (TypeError, ValueError):
+            return str(ev) == str(expected)
+    a, b = str(ev), str(expected)
+    if not cased:
+        a, b = a.lower(), b.lower()
+    if "contains" in mods:
+        return b in a
+    if "startswith" in mods:
+        return a.startswith(b)
+    if "endswith" in mods:
+        return a.endswith(b)
+    if _has_glob(b):  # Sigma value wildcards: * = any run, ? = one char
+        return re.fullmatch(_glob_to_regex(b), a) is not None
+    return a == b
+
+
+def _has_glob(value: str) -> bool:
+    return re.search(r"(?<!\\)[*?]", value) is not None
+
+
+def _glob_to_regex(pattern: str) -> str:
+    out, i = [], 0
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "\\" and i + 1 < len(pattern) and pattern[i + 1] in "*?\\":
+            out.append(re.escape(pattern[i + 1]))
+            i += 2
+            continue
+        out.append(".*" if c == "*" else "." if c == "?" else re.escape(c))
+        i += 1
+    return "".join(out)
+
+
+def _cidr_match(ev, expected) -> bool:
+    try:
+        return ipaddress.ip_address(str(ev)) in ipaddress.ip_network(str(expected), strict=False)
+    except ValueError:
+        return False
+
+
+def scan_unsupported(detection: dict) -> list:
+    """Report Sigma features this evaluator cannot handle, so a rule fails loud
+    instead of silently returning a wrong result. Returns human-readable strings."""
+    findings, seen = [], set()
+
+    def check_key(key):
+        parts = key.split("|")
+        field = parts[0]
+        for mod in (m.lower() for m in parts[1:]):
+            if mod not in _SUPPORTED_MODS and ("m", mod) not in seen:
+                seen.add(("m", mod))
+                findings.append(f"unsupported modifier '|{mod}' (on '{field}')")
+        if "." in field and ("f", field) not in seen:
+            seen.add(("f", field))
+            findings.append(f"nested/dotted field '{field}' (matched only as a flat key)")
+
+    def walk(spec):
+        if isinstance(spec, dict):
+            for key in spec:
+                check_key(key)
+        elif isinstance(spec, list):
+            for item in spec:
+                walk(item)
+
+    for name, spec in detection.items():
+        if name != "condition":
+            walk(spec)
+    return findings
+
+
+def _keyword_match(keyword, event: dict) -> bool:
+    needle = str(keyword).lower()
+    return any(needle in str(v).lower() for v in event.values())
+
+
+def _eval_condition(condition: str, matches: dict) -> bool:
+    def _select(target):
+        if target == "them":
+            return list(matches)
+        if target.endswith("*"):
+            return [n for n in matches if n.startswith(target[:-1])]
+        return [target]
+
+    def _repl_quant(m):
+        quant, target = m.group(1), m.group(2)
+        vals = [bool(matches.get(n, False)) for n in _select(target)]
+        if quant == "all":
+            return "true" if vals and all(vals) else "false"
+        return "true" if sum(vals) >= int(quant) else "false"
+
+    expr = re.sub(r"\b(\d+|all)\s+of\s+([A-Za-z0-9_*]+)", _repl_quant, condition)
+    tokens = []
+    for tok in re.findall(r"\(|\)|[A-Za-z0-9_*]+", expr):
+        low = tok.lower()
+        if low in ("and", "or", "not", "true", "false"):
+            tokens.append(low)
+        elif tok in ("(", ")"):
+            tokens.append(tok)
+        else:
+            tokens.append("true" if matches.get(tok, False) else "false")
+    return _parse_bool(tokens)
+
+
+def _parse_bool(tokens) -> bool:
+    pos = 0
+
+    def peek():
+        return tokens[pos] if pos < len(tokens) else None
+
+    def eat():
+        nonlocal pos
+        tok = tokens[pos]
+        pos += 1
+        return tok
+
+    def parse_or():
+        v = parse_and()
+        while peek() == "or":
+            eat()
+            v = parse_and() or v
+        return v
+
+    def parse_and():
+        v = parse_not()
+        while peek() == "and":
+            eat()
+            v = parse_not() and v
+        return v
+
+    def parse_not():
+        if peek() == "not":
+            eat()
+            return not parse_not()
+        return parse_atom()
+
+    def parse_atom():
+        tok = eat() if peek() is not None else None
+        if tok == "(":
+            v = parse_or()
+            if peek() == ")":
+                eat()
+            return v
+        if tok == "true":
+            return True
+        if tok == "false":
+            return False
+        raise ValueError(f"cannot parse condition near {tok!r}")
+
+    if not tokens:
+        raise ValueError("empty condition")
+    return parse_or()

detkit_cli-0.1.0/detkit_cli.egg-info/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: detkit-cli
+Version: 0.1.0
+Summary: dbt for detections — test, validate, and CI-gate Sigma detection rules as code.
+Author: detkit
+License: MIT
+Project-URL: Homepage, https://github.com/ELSATOAH/detkit
+Project-URL: Repository, https://github.com/ELSATOAH/detkit
+Project-URL: Issues, https://github.com/ELSATOAH/detkit/issues
+Keywords: sigma,detection-engineering,detection-as-code,siem,security,detections,blue-team,cybersecurity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# detkit — dbt for detections
+
+[![CI](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ELSATOAH/detkit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Test, validate, and CI-gate your Sigma detection rules **as code**, before they
+ever reach production.
+
+![detkit catching a broken detection before it ships](detkit-demo.gif)
+
+Detection engineers write rules in [Sigma](https://sigmahq.io/), commit them to
+Git, and ship them to a SIEM — but there's no standard way to *unit-test* a rule
+locally: does it actually fire on the attack it targets, and stay quiet on benign
+traffic? Today that's checked by hand, or in prod. detkit closes that loop.
+
+```
+detkit test ./rules        # run every rule against its sample events
+detkit validate ./rules    # structural + condition-reference checks
+```
+
+detkit is **open source (MIT)**, **self-hostable**, and **vendor-neutral** — it
+sits *alongside* your SIEM (Wazuh, Elastic, Splunk, Sentinel), not in front of
+it. Your logs and rules never leave your machine or CI runner.
+
+## Quickstart
+
+```bash
+pipx install git+https://github.com/ELSATOAH/detkit.git   # PyPI: `pipx install detkit-cli` (coming soon)
+
+detkit init         # scaffold a starter rule + test + a CI workflow
+detkit test rules   # -> green on the first run
+```
+
+Each rule gets a sibling `*.test.yml` describing sample events and whether the
+rule should match:
+
+```yaml
+# whoami_execution.test.yml
+tests:
+  - name: fires on whoami run by a normal user
+    event: { EventID: 4688, CommandLine: "cmd /c whoami /all", User: "alice" }
+    expect: match
+  - name: suppressed for SYSTEM
+    event: { EventID: 4688, CommandLine: "whoami", User: "SYSTEM" }
+    expect: no_match
+```
+
+`detkit test` exits non-zero on any failure, so you can drop it straight into CI
+and block a pull request that breaks a detection.
+
+## Use it in CI (GitHub Actions)
+
+Drop this into your **rules** repo to gate every pull request:
+
+```yaml
+# .github/workflows/detections.yml
+name: Detections
+on: [pull_request]
+jobs:
+  detkit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ELSATOAH/detkit@v0   # this repo's composite action
+        with:
+          path: rules                # where your Sigma rules live
+```
+
+A rule whose `*.test.yml` no longer passes now fails the check and blocks the
+merge — the same safety net dbt gives analytics engineers.
+
+## Why this, why now
+
+- **Detection-as-code is mainstream** (SigmaHQ, Elastic detection-rules, Splunk
+  ESCU) but the *test* step is missing — the same gap dbt filled for analytics.
+- **Self-host is a hard requirement, not a preference:** security telemetry can't
+  be shipped to someone else's cloud. That's the wedge closed SaaS SOC tools
+  (Dropzone, Prophet, Intezer) structurally can't serve.
+- **The community distributes it:** good detection tooling spreads bottom-up on
+  GitHub. detkit is built to be forked, extended, and shared.
+
+## Roadmap
+
+- `detkit generate` — AI-draft a rule **and its tests** from a natural-language
+  threat description (tests are mandatory, never optional).
+- More log schemas / field-mapping so one rule tests against multiple log sources.
+- Close the remaining gaps detkit currently warns on: nested/dotted field access
+  (~3% of rules) and `base64` modifiers — likely via
+  [pySigma](https://github.com/SigmaHQ/pySigma) for full-spec parsing.
+- Managed cloud (hosted runs, SSO, shared rule/test libraries) — the paid tier.
+  The tool stays free forever.
+
+## Status
+
+Early, but the core is real. detkit evaluates a rule's `detection`/`condition`
+against log events and runs tests around it — covering the features used by the
+**large majority of published SigmaHQ rules**: `contains`/`startswith`/`endswith`/
+`re` modifiers, value wildcards (`*`/`?`), `|cidr`, list-as-OR, keyword lists, and
+`X of` / `all of` conditions.
+
+What it can't yet evaluate (nested/dotted fields, `base64` modifiers) it **flags
+loudly** — `detkit validate` and `detkit test` print a `WARN` rather than return a
+confident wrong answer. A detection tool that's silently wrong is worse than none.
+
+Run the checks: `python tests/test_evaluator.py`. Limits are marked with
+`# ponytail:` comments in `detkit/evaluator.py`.
+
+MIT licensed. Contributions welcome.

detkit_cli-0.1.0/detkit_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+detkit/__init__.py
+detkit/__main__.py
+detkit/cli.py
+detkit/evaluator.py
+detkit_cli.egg-info/PKG-INFO
+detkit_cli.egg-info/SOURCES.txt
+detkit_cli.egg-info/dependency_links.txt
+detkit_cli.egg-info/entry_points.txt
+detkit_cli.egg-info/requires.txt
+detkit_cli.egg-info/top_level.txt
+tests/test_evaluator.py

detkit_cli-0.1.0/detkit_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

detkit_cli-0.1.0/detkit_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+detkit = detkit.cli:main

detkit_cli-0.1.0/detkit_cli.egg-info/requires.txt

@@ -0,0 +1 @@
+pyyaml>=6

detkit_cli-0.1.0/detkit_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+detkit

detkit_cli-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+# PyPI distribution name (`detkit` was taken); the import package and CLI command
+# both stay `detkit`, so users still run `detkit ...` after `pipx install detkit-cli`.
+name = "detkit-cli"
+version = "0.1.0"
+description = "dbt for detections — test, validate, and CI-gate Sigma detection rules as code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "detkit" }]
+keywords = [
+    "sigma", "detection-engineering", "detection-as-code",
+    "siem", "security", "detections", "blue-team", "cybersecurity",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Information Technology",
+    "Topic :: Security",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = ["pyyaml>=6"]
+
+[project.urls]
+Homepage = "https://github.com/ELSATOAH/detkit"
+Repository = "https://github.com/ELSATOAH/detkit"
+Issues = "https://github.com/ELSATOAH/detkit/issues"
+
+[project.scripts]
+detkit = "detkit.cli:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["detkit*"]

detkit_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

detkit_cli-0.1.0/tests/test_evaluator.py

@@ -0,0 +1,110 @@
+"""Runnable check for the Sigma evaluator core.
+
+No framework needed: `python tests/test_evaluator.py` runs every assert and
+prints OK, or raises on the first failure. pytest also discovers it.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from detkit.evaluator import event_matches_rule, scan_unsupported  # noqa: E402
+
+
+def test_equals_contains_and_not():
+    det = {
+        "selection": {"EventID": 4688, "CommandLine|contains": "whoami"},
+        "filter": {"User": "SYSTEM"},
+        "condition": "selection and not filter",
+    }
+    assert event_matches_rule(det, {"EventID": 4688, "CommandLine": "cmd /c whoami", "User": "alice"})
+    assert not event_matches_rule(det, {"EventID": 4688, "CommandLine": "whoami", "User": "SYSTEM"})
+    assert not event_matches_rule(det, {"EventID": 4688, "CommandLine": "ipconfig", "User": "alice"})
+
+
+def test_numeric_string_coercion():
+    det = {"sel": {"EventID": 4688}, "condition": "sel"}
+    assert event_matches_rule(det, {"EventID": "4688"})  # log field arrives as string
+    assert not event_matches_rule(det, {"EventID": 4689})
+
+
+def test_list_value_is_or():
+    det = {"sel": {"Image|endswith": ["\\cmd.exe", "\\powershell.exe"]}, "condition": "sel"}
+    assert event_matches_rule(det, {"Image": "C:\\Windows\\System32\\cmd.exe"})
+    assert not event_matches_rule(det, {"Image": "C:\\Windows\\explorer.exe"})
+
+
+def test_all_modifier_is_and():
+    det = {"sel": {"CommandLine|contains|all": ["-enc", "bypass"]}, "condition": "sel"}
+    assert event_matches_rule(det, {"CommandLine": "powershell -enc AAAA -ExecutionPolicy bypass"})
+    assert not event_matches_rule(det, {"CommandLine": "powershell -enc AAAA"})
+
+
+def test_missing_field_no_match():
+    det = {"sel": {"CommandLine|contains": "whoami"}, "condition": "sel"}
+    assert not event_matches_rule(det, {"EventID": 4688})
+
+
+def test_one_of_them_and_all_of_prefix():
+    det = {
+        "selection_a": {"EventID": 1},
+        "selection_b": {"EventID": 2},
+        "condition": "1 of them",
+    }
+    assert event_matches_rule(det, {"EventID": 2})
+    det2 = {
+        "selection_a": {"EventID": 1},
+        "selection_b": {"UserName": "root"},
+        "condition": "all of selection*",
+    }
+    assert event_matches_rule(det2, {"EventID": 1, "UserName": "root"})
+    assert not event_matches_rule(det2, {"EventID": 1})
+
+
+def test_keyword_list_search():
+    det = {"keywords": ["mimikatz", "sekurlsa"], "condition": "keywords"}
+    assert event_matches_rule(det, {"CommandLine": "run sekurlsa::logonpasswords"})
+    assert not event_matches_rule(det, {"CommandLine": "dir /s"})
+
+
+def test_regex_modifier():
+    det = {"sel": {"CommandLine|re": r"whoami(\.exe)?\s"}, "condition": "sel"}
+    assert event_matches_rule(det, {"CommandLine": "whoami.exe /all"})
+    assert not event_matches_rule(det, {"CommandLine": "whoamidaemon"})
+
+
+def test_value_wildcard():
+    # regression for dogfood bug #1: `v*.compute.firewalls.delete` was matched literally
+    det = {"sel": {"MethodName": "v*.compute.firewalls.delete"}, "condition": "sel"}
+    assert event_matches_rule(det, {"MethodName": "v1.compute.firewalls.delete"})
+    assert not event_matches_rule(det, {"MethodName": "v1.compute.networks.delete"})
+    det_q = {"sel": {"Code": "AC?E"}, "condition": "sel"}
+    assert event_matches_rule(det_q, {"Code": "ACME"})
+    assert not event_matches_rule(det_q, {"Code": "ACabE"})
+
+
+def test_cidr_modifier():
+    # regression for dogfood bug #3: |cidr degraded to string equality, so filters never fired
+    det = {"filter": {"IpAddress|cidr": "10.0.0.0/8"}, "condition": "filter"}
+    assert event_matches_rule(det, {"IpAddress": "10.20.30.40"})
+    assert not event_matches_rule(det, {"IpAddress": "8.8.8.8"})
+    assert not event_matches_rule(det, {"IpAddress": "not-an-ip"})
+
+
+def test_scan_flags_unsupported():
+    det = {
+        "sel": {"CommandLine|base64offset|contains": "abc", "id.orig_h": "1.2.3.4"},
+        "condition": "sel",
+    }
+    findings = scan_unsupported(det)
+    assert any("base64offset" in f for f in findings)
+    assert any("id.orig_h" in f for f in findings)
+    assert scan_unsupported({"sel": {"EventID": 1}, "condition": "sel"}) == []
+
+
+if __name__ == "__main__":
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    for fn in fns:
+        fn()
+        print(f"ok  {fn.__name__}")
+    print(f"\n{len(fns)} checks passed")