Skip to content

hypnguyen1209/offensive-claude / skills/threat-hunting

threat-hunting

Flagged

Use when hunting threats or engineering detections — ATT&CK Detection-Strategies, Sigma + correlation with Detection-as-Code CI, Windows endpoint hunting (Sysmon/ETW/LSASS/LOLBins), network C2 hunting (JA4+, beaconing, DNS tunneling), cloud-identity hunting, Atomic Red Team purple-team validation

scripts/coverage_matrix.py

View on GitHub
#!/usr/bin/env python3
"""
coverage_matrix.py - ATT&CK detection-coverage matrix + Navigator layer + gap report.

Ingests a directory of Sigma rules (reads `tags:` for `attack.tXXXX[.yyy]`) plus an
optional Atomic Red Team results JSON, then emits:
  1. A coverage table (technique -> covering rules + atomic test status)
  2. A MITRE ATT&CK Navigator layer JSON (heatmap by rule count / validation)
  3. A prioritized gap CSV (techniques tested-but-undetected, or in a watchlist with no rule)

USAGE:
    python3 coverage_matrix.py --rules rules/ \
        [--atomic-results atomic_results.json] \
        [--watchlist watchlist.txt] \
        [--navigator-out attack_layer.json] [--gaps-out gaps.csv]

    # atomic_results.json format (list): [{"technique":"T1003.001","status":"PASS|PARTIAL|FAIL"}, ...]
    #   PASS=telemetry+alert  PARTIAL=telemetry,no alert (rule gap)  FAIL=no telemetry (visibility gap)
    # watchlist.txt: one technique ID per line (high-priority techniques you MUST cover)

DEPENDENCIES: pip install pyyaml

This is a defensive detection-engineering tool. Authorized use only.
"""
import argparse
import csv
import json
import re
import sys
from collections import defaultdict
from pathlib import Path

try:
    import yaml
except ImportError:
    sys.exit("Install pyyaml: pip install pyyaml")

TECH_RE = re.compile(r"^attack\.(t\d{4}(?:\.\d{3})?)$", re.IGNORECASE)


def extract_techniques(rule: dict):
    """Return set of upper-cased ATT&CK technique IDs from a Sigma rule's tags."""
    out = set()
    for tag in (rule.get("tags") or []):
        m = TECH_RE.match(str(tag))
        if m:
            out.add(m.group(1).upper())
    return out


def load_rules(rules_dir: Path):
    """tech_id -> list of {title, level, file}."""
    cov = defaultdict(list)
    files = list(rules_dir.rglob("*.yml")) + list(rules_dir.rglob("*.yaml"))
    for f in files:
        try:
            for rule in yaml.safe_load_all(f.read_text(encoding="utf-8", errors="replace")):
                if not isinstance(rule, dict):
                    continue
                techs = extract_techniques(rule)
                for t in techs:
                    cov[t].append({"title": rule.get("title", "?"),
                                   "level": rule.get("level", "?"),
                                   "file": f.name})
        except yaml.YAMLError as e:
            print(f"[!] {f}: {e}", file=sys.stderr)
    return cov


def load_atomic(path: Path):
    """technique -> status (PASS/PARTIAL/FAIL)."""
    status = {}
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError) as e:
        sys.exit(f"[!] atomic-results: {e}")
    for entry in data:
        t = str(entry.get("technique", "")).upper()
        if t:
            status[t] = str(entry.get("status", "")).upper()
    return status


def navigator_layer(coverage, atomic):
    """Build a MITRE ATT&CK Navigator v4.5 layer JSON."""
    techniques = []
    all_ids = set(coverage) | set(atomic)
    for tid in sorted(all_ids):
        n = len(coverage.get(tid, []))
        st = atomic.get(tid)
        # color: green covered+validated, yellow partial, red gap, blue rule-only
        if st == "PASS":
            color = "#2ecc71"
        elif st == "PARTIAL":
            color = "#f1c40f"
        elif st == "FAIL" or (st is None and n == 0):
            color = "#e74c3c"
        elif n > 0:
            color = "#3498db"
        else:
            color = "#bdc3c7"
        techniques.append({
            "techniqueID": tid.split(".")[0] if "." in tid else tid,
            "score": n,
            "color": color,
            "comment": f"rules={n} atomic={st or 'untested'}",
            "enabled": True,
        })
        # If sub-technique, also add the sub explicitly
        if "." in tid:
            techniques[-1]["techniqueID"] = tid
    return {
        "name": "Detection Coverage (threat-hunting skill)",
        "versions": {"layer": "4.5", "navigator": "4.9.1", "attack": "18"},
        "domain": "enterprise-attack",
        "description": "Generated by coverage_matrix.py: rule count + Atomic Red Team validation",
        "techniques": techniques,
        "gradient": {"colors": ["#ffffff", "#66b1ff", "#0b6bcb"], "minValue": 0,
                     "maxValue": max((len(v) for v in coverage.values()), default=1)},
        "legendItems": [
            {"label": "Covered + validated (PASS)", "color": "#2ecc71"},
            {"label": "Partial (telemetry, no alert)", "color": "#f1c40f"},
            {"label": "Gap (FAIL / no rule)", "color": "#e74c3c"},
            {"label": "Rule exists, untested", "color": "#3498db"},
        ],
    }


def main():
    ap = argparse.ArgumentParser(description="ATT&CK detection-coverage matrix + Navigator layer")
    ap.add_argument("--rules", required=True, help="directory of Sigma rules")
    ap.add_argument("--atomic-results", help="Atomic Red Team results JSON")
    ap.add_argument("--watchlist", help="file of high-priority technique IDs (one per line)")
    ap.add_argument("--navigator-out", help="write ATT&CK Navigator layer JSON here")
    ap.add_argument("--gaps-out", help="write gap report CSV here")
    args = ap.parse_args()

    coverage = load_rules(Path(args.rules))
    atomic = load_atomic(Path(args.atomic_results)) if args.atomic_results else {}
    watchlist = set()
    if args.watchlist:
        watchlist = {l.strip().upper() for l in Path(args.watchlist).read_text().splitlines()
                     if l.strip() and not l.startswith("#")}

    # Console matrix
    print(f"{'TECHNIQUE':14} {'RULES':6} {'ATOMIC':9} STATUS")
    print("-" * 60)
    all_ids = sorted(set(coverage) | set(atomic) | watchlist)
    gaps = []
    for tid in all_ids:
        n = len(coverage.get(tid, []))
        st = atomic.get(tid, "untested")
        if n == 0 and st in ("FAIL", "untested"):
            status = "GAP"
            gaps.append((tid, "no rule + " + ("no telemetry" if st == "FAIL" else "untested"),
                         "watchlist" if tid in watchlist else "discovered"))
        elif st == "PARTIAL" or (n == 0 and st == "PASS"):
            status = "PARTIAL"
            gaps.append((tid, "telemetry present, alert missing", "rule-gap"))
        elif n > 0 and st == "PASS":
            status = "COVERED"
        elif n > 0:
            status = "RULE-ONLY"
        else:
            status = "PARTIAL"
        flag = " *WATCH*" if tid in watchlist else ""
        print(f"{tid:14} {n:<6} {st:9} {status}{flag}")

    print(f"\n[=] {len(coverage)} techniques with rules, {len(gaps)} gap(s)")

    if args.navigator_out:
        layer = navigator_layer(coverage, atomic)
        Path(args.navigator_out).write_text(json.dumps(layer, indent=2), encoding="utf-8")
        print(f"[+] Navigator layer -> {args.navigator_out} "
              f"(import at mitre-attack.github.io/attack-navigator)")

    if args.gaps_out:
        with open(args.gaps_out, "w", newline="", encoding="utf-8") as fh:
            w = csv.writer(fh)
            w.writerow(["technique", "gap_reason", "priority"])
            # watchlist gaps first
            gaps.sort(key=lambda g: 0 if g[2] == "watchlist" else 1)
            for row in gaps:
                w.writerow(row)
        print(f"[+] Gap report -> {args.gaps_out}")


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall