detkit-cli 0.1.5__tar.gz → 0.1.6__tar.gz

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detkit-cli
-Version: 0.1.5
+Version: 0.1.6
 Summary: dbt for detections — test, validate, and CI-gate Sigma detection rules as code.
 Author: detkit
 License-Expression: MIT
@@ -105,11 +105,28 @@ repos:
 
 There's a `detkit-validate` hook too, for the lighter structural check.
 
+## Coverage
+
+Past a handful of rules you want to see what you're *not* covering. `detkit docs` builds a single self-contained HTML page: a catalog of every rule plus a MITRE ATT&CK heatmap of which techniques you detect, which you test, and which are gaps.
+
+```bash
+detkit docs rules -o coverage.html
+```
+
+Green is a technique with a tested rule, amber is a rule with no test, and the faint cells are the gaps. It's one file with no external assets, so you can commit it or publish it to GitHub Pages.
+
+`detkit navigator` exports the same coverage as a [MITRE ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) layer, so it drops straight into the tool your team already uses:
+
+```bash
+detkit navigator rules -o coverage.json
+# then Open Existing Layer -> Upload at the Navigator
+```
+
 ## What it handles
 
-detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, keyword lists, and `X of` / `all of` conditions.
+detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, nested/dotted fields (`DeviceDetail.deviceId`), keyword lists, and `X of` / `all of` conditions.
 
-It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like nested fields (`DeviceDetail.deviceId`) or `base64` modifiers, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
+It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like `base64`/`windash` modifiers or arrays of objects, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
 
 ## Why
 
@@ -117,7 +134,7 @@ Detections live in Git now, but the testing habit that comes with the rest of so
 
 ## Roadmap
 
-- Nested/dotted fields and `base64` modifiers (the two things it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
+- `base64`/`windash` modifiers and arrays of objects (what it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
 - `detkit generate`: draft a rule and its tests from a plain-English description. The tests come with it, not as an afterthought.
 - Field mapping, so one rule can be checked against more than one log schema.
 - A hosted option down the line for teams that want shared runs and history. The CLI stays free.

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/README.md

@@ -84,11 +84,28 @@ repos:
 
 There's a `detkit-validate` hook too, for the lighter structural check.
 
+## Coverage
+
+Past a handful of rules you want to see what you're *not* covering. `detkit docs` builds a single self-contained HTML page: a catalog of every rule plus a MITRE ATT&CK heatmap of which techniques you detect, which you test, and which are gaps.
+
+```bash
+detkit docs rules -o coverage.html
+```
+
+Green is a technique with a tested rule, amber is a rule with no test, and the faint cells are the gaps. It's one file with no external assets, so you can commit it or publish it to GitHub Pages.
+
+`detkit navigator` exports the same coverage as a [MITRE ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) layer, so it drops straight into the tool your team already uses:
+
+```bash
+detkit navigator rules -o coverage.json
+# then Open Existing Layer -> Upload at the Navigator
+```
+
 ## What it handles
 
-detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, keyword lists, and `X of` / `all of` conditions.
+detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, nested/dotted fields (`DeviceDetail.deviceId`), keyword lists, and `X of` / `all of` conditions.
 
-It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like nested fields (`DeviceDetail.deviceId`) or `base64` modifiers, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
+It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like `base64`/`windash` modifiers or arrays of objects, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
 
 ## Why
 
@@ -96,7 +113,7 @@ Detections live in Git now, but the testing habit that comes with the rest of so
 
 ## Roadmap
 
-- Nested/dotted fields and `base64` modifiers (the two things it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
+- `base64`/`windash` modifiers and arrays of objects (what it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
 - `detkit generate`: draft a rule and its tests from a plain-English description. The tests come with it, not as an afterthought.
 - Field mapping, so one rule can be checked against more than one log schema.
 - A hosted option down the line for teams that want shared runs and history. The CLI stays free.

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit/cli.py

@@ -272,6 +272,23 @@ def cmd_docs(args):
     return 0
 
 
+def cmd_navigator(args):
+    rules = _discover_rules(args.path)
+    if not rules:
+        print(f"no rules found under {args.path!r}")
+        return 1
+    items = [
+        {"path": rp, "rule": _load_yaml(rp) or {}, "has_tests": _test_file_for(rp) is not None}
+        for rp in rules
+    ]
+    layer = docs.navigator_layer(items, _load_attack_data())
+    with open(args.output, "w", encoding="utf-8") as f:
+        json.dump(layer, f, indent=2)
+    print(f"exported {len(layer['techniques'])} techniques -> {args.output}")
+    print("import it at https://mitre-attack.github.io/attack-navigator/ (Open Existing Layer -> Upload)")
+    return 0
+
+
 def cmd_generate(args):
     print(
         "`detkit generate` is not implemented yet.\n"
@@ -307,6 +324,11 @@ def main(argv=None):
     p_docs.add_argument("-o", "--output", default="detkit-docs.html")
     p_docs.set_defaults(func=cmd_docs)
 
+    p_nav = sub.add_parser("navigator", help="export coverage as a MITRE ATT&CK Navigator layer (JSON)")
+    p_nav.add_argument("path", nargs="?", default=".")
+    p_nav.add_argument("-o", "--output", default="detkit-navigator.json")
+    p_nav.set_defaults(func=cmd_navigator)
+
     p_gen = sub.add_parser("generate", help="(planned) AI-draft a rule + tests")
     p_gen.set_defaults(func=cmd_generate)
 

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit/docs.py

@@ -124,6 +124,54 @@ def render(items, attack_data=None):
     return _page(rules, covered, other, full, names, matrix_on, summary), summary
 
 
+def _covered_by_technique(items):
+    """{parent technique id: tested?} across all rules — folds sub-techniques to parent."""
+    out = {}
+    for it in items:
+        r = _extract(it)
+        for tech in r["techniques"]:
+            parent = tech.split(".")[0]
+            out[parent] = out.get(parent, False) or r["has_tests"]
+    return out
+
+
+def navigator_layer(items, attack_data=None, name="detkit coverage"):
+    """Build a MITRE ATT&CK Navigator layer (dict) from rule coverage.
+
+    score 100 = has detkit tests (green), 50 = covered but untested (amber);
+    gaps are left out so Navigator shows them uncolored. Import at
+    https://mitre-attack.github.io/attack-navigator/.
+    """
+    covered = _covered_by_technique(items)
+    full, _ = _matrix(attack_data)
+    universe = {t for techs in full.values() for t in techs}
+    version = str((attack_data or {}).get("attack_version", "")).lstrip("vV") or "17"
+    techniques = [
+        {
+            "techniqueID": tech,
+            "score": 100 if tested else 50,
+            "enabled": True,
+            "comment": "tested" if tested else "covered (no detkit test)",
+        }
+        for tech, tested in sorted(covered.items())
+        if not universe or tech in universe
+    ]
+    return {
+        "name": name,
+        "domain": "enterprise-attack",
+        "description": "detkit detection coverage. score 100 = has detkit tests, 50 = covered but untested.",
+        "versions": {"attack": version, "navigator": "5.1.0", "layer": "4.5"},
+        "sorting": 0,
+        "hideDisabled": False,
+        "techniques": techniques,
+        "gradient": {"colors": ["#fff8c5", "#8ec843"], "minValue": 50, "maxValue": 100},
+        "legendItems": [
+            {"label": "covered, no test", "color": "#fff8c5"},
+            {"label": "tested", "color": "#8ec843"},
+        ],
+    }
+
+
 def _cells(cov, official, names):
     """cov: {tech: tested?}. official: {tech: name} (full matrix) or None."""
     if official is None:                       # v1: only covered techniques

detkit_cli-0.1.6/detkit-navigator.json

@@ -0,0 +1,50 @@
+{
+  "name": "detkit coverage",
+  "domain": "enterprise-attack",
+  "description": "detkit detection coverage. score 100 = has detkit tests, 50 = covered but untested.",
+  "versions": {
+    "attack": "19",
+    "navigator": "5.1.0",
+    "layer": "4.5"
+  },
+  "sorting": 0,
+  "hideDisabled": false,
+  "techniques": [
+    {
+      "techniqueID": "T1027",
+      "score": 100,
+      "enabled": true,
+      "comment": "tested"
+    },
+    {
+      "techniqueID": "T1033",
+      "score": 100,
+      "enabled": true,
+      "comment": "tested"
+    },
+    {
+      "techniqueID": "T1059",
+      "score": 100,
+      "enabled": true,
+      "comment": "tested"
+    }
+  ],
+  "gradient": {
+    "colors": [
+      "#fff8c5",
+      "#8ec843"
+    ],
+    "minValue": 50,
+    "maxValue": 100
+  },
+  "legendItems": [
+    {
+      "label": "covered, no test",
+      "color": "#fff8c5"
+    },
+    {
+      "label": "tested",
+      "color": "#8ec843"
+    }
+  ]
+}

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detkit-cli
-Version: 0.1.5
+Version: 0.1.6
 Summary: dbt for detections — test, validate, and CI-gate Sigma detection rules as code.
 Author: detkit
 License-Expression: MIT
@@ -105,11 +105,28 @@ repos:
 
 There's a `detkit-validate` hook too, for the lighter structural check.
 
+## Coverage
+
+Past a handful of rules you want to see what you're *not* covering. `detkit docs` builds a single self-contained HTML page: a catalog of every rule plus a MITRE ATT&CK heatmap of which techniques you detect, which you test, and which are gaps.
+
+```bash
+detkit docs rules -o coverage.html
+```
+
+Green is a technique with a tested rule, amber is a rule with no test, and the faint cells are the gaps. It's one file with no external assets, so you can commit it or publish it to GitHub Pages.
+
+`detkit navigator` exports the same coverage as a [MITRE ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) layer, so it drops straight into the tool your team already uses:
+
+```bash
+detkit navigator rules -o coverage.json
+# then Open Existing Layer -> Upload at the Navigator
+```
+
 ## What it handles
 
-detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, keyword lists, and `X of` / `all of` conditions.
+detkit runs your rules locally. No SIEM, no credentials, nothing leaves your machine or CI runner. I ran it against every rule in the SigmaHQ repo, and about 91% use only features it understands today: `contains`, `startswith`, `endswith`, `re`, value wildcards (`*` and `?`), `|cidr`, nested/dotted fields (`DeviceDetail.deviceId`), keyword lists, and `X of` / `all of` conditions.
 
-It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like nested fields (`DeviceDetail.deviceId`) or `base64` modifiers, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
+It won't guess at the rest. If a rule uses something detkit can't evaluate yet, like `base64`/`windash` modifiers or arrays of objects, `test` and `validate` print a WARN naming the feature instead of returning an answer that might be wrong. A detection tool that's quietly wrong is worse than no tool.
 
 ## Why
 
@@ -117,7 +134,7 @@ Detections live in Git now, but the testing habit that comes with the rest of so
 
 ## Roadmap
 
-- Nested/dotted fields and `base64` modifiers (the two things it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
+- `base64`/`windash` modifiers and arrays of objects (what it warns on today), probably via [pySigma](https://github.com/SigmaHQ/pySigma).
 - `detkit generate`: draft a rule and its tests from a plain-English description. The tests come with it, not as an afterthought.
 - Field mapping, so one rule can be checked against more than one log schema.
 - A hosted option down the line for teams that want shared runs and history. The CLI stays free.

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit_cli.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ README.md
 action.yml
 detkit-demo.gif
 detkit-demo.tape
+detkit-navigator.json
 pyproject.toml
 .github/ISSUE_TEMPLATE/bug_report.md
 .github/ISSUE_TEMPLATE/feature_request.md

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit_cli.egg-info/scm_file_list.json

@@ -2,6 +2,7 @@
   "files": [
     ".gitignore",
     "detkit-demo.tape",
+    "detkit-navigator.json",
     "README.md",
     "action.yml",
     "CONTRIBUTING.md",

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/detkit_cli.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.1.5",
+  "tag": "0.1.6",
   "distance": 0,
-  "node": "g8ebd5d89c44f1c35a218bb1a008163aee32f87cd",
+  "node": "gefb596d8a8684369663c94b34680e262fc75fa3c",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-07-21"

{detkit_cli-0.1.5 → detkit_cli-0.1.6}/tests/test_docs.py

@@ -4,7 +4,7 @@ import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
-from detkit.docs import parse_attack, render  # noqa: E402
+from detkit.docs import navigator_layer, parse_attack, render  # noqa: E402
 
 
 def test_parse_attack():
@@ -39,6 +39,25 @@ def test_render_empty():
     assert "<!doctype html>" in html_str.lower()
 
 
+def test_navigator_layer():
+    items = [
+        {"path": "a.yml", "has_tests": True,
+         "rule": {"title": "A", "tags": ["attack.execution", "attack.t1059.001"]}},
+        {"path": "b.yml", "has_tests": False,
+         "rule": {"title": "B", "tags": ["attack.persistence", "attack.t1547"]}},
+    ]
+    attack = {"attack_version": "v19", "techniques": [
+        {"id": "T1059", "name": "x", "tactics": ["execution"]},
+        {"id": "T1547", "name": "y", "tactics": ["persistence"]},
+    ]}
+    layer = navigator_layer(items, attack)
+    assert layer["domain"] == "enterprise-attack"
+    assert layer["versions"]["attack"] == "19"        # 'v19' -> '19'
+    by = {t["techniqueID"]: t for t in layer["techniques"]}
+    assert by["T1059"]["score"] == 100                # sub-technique folds to parent, tested
+    assert by["T1547"]["score"] == 50                 # covered, no test
+
+
 if __name__ == "__main__":
     fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
     for fn in fns: