attack-mapper 0.4.0__py3-none-any.whl

attack_mapper/__init__.py

@@ -0,0 +1,30 @@
+"""attack-mapper: map your Sigma detection rules onto the MITRE ATT&CK matrix."""
+
+from .attack_loader import AttackDB, load_attack
+from .coverage import CoverageReport, build_report
+from .sigma_parser import (
+    ParsedRule,
+    parse_rule_file,
+    parse_rule_text,
+    parse_rules,
+)
+from .renderers import render_terminal, render_html, STYLES
+from .plugins import render_badge, render_json
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "AttackDB",
+    "load_attack",
+    "CoverageReport",
+    "build_report",
+    "ParsedRule",
+    "parse_rule_file",
+    "parse_rule_text",
+    "parse_rules",
+    "render_terminal",
+    "render_html",
+    "STYLES",
+    "render_badge",
+    "render_json",
+]

attack_mapper/attack_loader.py

@@ -0,0 +1,140 @@
+"""Load MITRE ATT&CK data for coverage mapping.
+
+Two modes are supported:
+
+* **Bundled compact DB** (``data/attack_db.json``) — generated by
+  :mod:`attack_mapper.build_db` from the official MITRE CTI STIX bundle. This
+  is the default because it is small (``~180 KB``) and needs no network.
+* **Full STIX bundle** (``enterprise-attack.json``) — if you point
+  ``ATTACK_MAPPER_STIX`` at the raw STIX 2.0/2.1 bundle, it is parsed directly
+  so you always have the latest techniques/tactics.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+DEFAULT_DB_PATH = os.path.join(os.path.dirname(__file__), "data", "attack_db.json")
+
+
+@dataclass
+class AttackDB:
+    """In-memory view of ATT&CK tactics and techniques."""
+
+    version: str = ""
+    tactics: Dict[str, dict] = field(default_factory=dict)
+    techniques: Dict[str, dict] = field(default_factory=dict)
+
+    def technique_name(self, tid: str) -> Optional[str]:
+        t = self.techniques.get(tid.upper())
+        return t["name"] if t else None
+
+    def tactic_name(self, shortname: str) -> Optional[str]:
+        t = self.tactics.get(shortname)
+        return t["name"] if t else shortname
+
+    def valid_technique(self, tid: str) -> bool:
+        return tid.upper() in self.techniques
+
+    def resolve_tactic_token(self, token: str) -> str:
+        """Map a TA tactic ID (e.g. ``TA0002``) to its shortname.
+
+        Returns the token unchanged if it isn't a known TA id, so scope
+        tokens can be technique IDs, shortnames, or TA ids interchangeably.
+        Older compact DBs may lack the ``id`` field — fall back to parsing
+        the TA id out of the tactic URL.
+        """
+        wanted = token.strip().upper()
+        if not wanted.startswith("TA"):
+            return token
+        for shortname, tac in self.tactics.items():
+            taid = tac.get("id")
+            if not taid:
+                url = tac.get("url") or ""
+                if "/tactics/" in url:
+                    taid = url.rstrip("/").rsplit("/", 1)[-1]
+            if taid and taid.upper() == wanted:
+                return shortname
+        return token
+
+
+def _load_compact(path: str) -> AttackDB:
+    with open(path, "r", encoding="utf-8") as fh:
+        d = json.load(fh)
+    return AttackDB(
+        version=d.get("version", ""),
+        tactics=d.get("tactics", {}),
+        techniques=d.get("techniques", {}),
+    )
+
+
+def _load_stix(path: str) -> AttackDB:
+    with open(path, "r", encoding="utf-8") as fh:
+        bundle = json.load(fh)
+    tactics: Dict[str, dict] = {}
+    techniques: Dict[str, dict] = {}
+    version = ""
+    for o in bundle.get("objects", []):
+        t = o.get("type")
+        # Revoked/deprecated objects are kept in the STIX bundle for history,
+        # but they are no longer part of ATT&CK — including them would inflate
+        # the coverage denominator with techniques that don't exist anymore.
+        if o.get("revoked") or o.get("x_mitre_deprecated"):
+            continue
+        if t == "x-mitre-matrix":
+            # The bundle has no version object; the matrix name + last-modified
+            # date is the most honest snapshot identifier available.
+            modified = (o.get("modified") or "")[:10]
+            version = f'{o.get("name", "ATT&CK")} ({modified})' if modified else o.get("name", "")
+        elif t == "x-mitre-tactic":
+            sn = o.get("x_mitre_shortname")
+            ref = next(
+                (e for e in o.get("external_references", []) if e.get("source_name") == "mitre-attack"),
+                {},
+            )
+            tactics[sn] = {
+                "id": ref.get("external_id"),
+                "name": o.get("name"),
+                "shortname": sn,
+                "url": ref.get("url"),
+            }
+        elif t == "attack-pattern":
+            refs = [e for e in o.get("external_references", []) if e.get("source_name") == "mitre-attack"]
+            if not refs:
+                continue
+            ext = refs[0].get("external_id")
+            if not (ext and ext.startswith("T")):
+                continue
+            techniques[ext] = {
+                "id": ext,
+                "name": o.get("name"),
+                "url": refs[0].get("url"),
+                "tactics": [p.get("phase_name") for p in o.get("kill_chain_phases", [])],
+                "is_subtechnique": "." in ext,
+            }
+    return AttackDB(version=version or "stix", tactics=tactics, techniques=techniques)
+
+
+def load_attack(db_path: Optional[str] = None) -> AttackDB:
+    """Load ATT&CK data.
+
+    Resolution order:
+    1. ``db_path`` argument if provided.
+    2. ``ATTACK_MAPPER_STIX`` env var -> full STIX bundle.
+    3. ``ATTACK_MAPPER_DB`` env var -> compact DB.
+    4. Bundled compact DB shipped with the package.
+    """
+    stix = os.environ.get("ATTACK_MAPPER_STIX")
+    compact = db_path or os.environ.get("ATTACK_MAPPER_DB") or os.path.abspath(DEFAULT_DB_PATH)
+
+    if stix and os.path.isfile(stix):
+        return _load_stix(stix)
+    if os.path.isfile(compact):
+        return _load_compact(compact)
+    raise FileNotFoundError(
+        f"No ATT&CK database found. Looked for compact DB at {compact} "
+        f"and STIX at {stix}. Run `python -m attack_mapper.build_db` to generate one."
+    )

attack_mapper/build_db.py

@@ -0,0 +1,44 @@
+"""Generate data/attack_db.json from a MITRE CTI STIX bundle.
+
+Usage:
+    ATTACK_MAPPER_STIX=path/to/enterprise-attack.json \
+        python -m attack_mapper.build_db
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from .attack_loader import _load_stix  # noqa: F401 (reuse the parser)
+
+DEFAULT_OUT = os.path.join(os.path.dirname(__file__), "data", "attack_db.json")
+
+
+def main() -> int:
+    stix = os.environ.get("ATTACK_MAPPER_STIX")
+    if not stix or not os.path.isfile(stix):
+        print(
+            "Set ATTACK_MAPPER_STIX to a downloaded enterprise-attack.json "
+            "(e.g. https://github.com/mitre/cti).",
+            file=__import__("sys").stderr,
+        )
+        return 1
+    db = _load_stix(stix)
+    out = os.path.abspath(DEFAULT_OUT)
+    compact = {
+        "version": db.version,
+        "tactics": db.tactics,
+        "techniques": db.techniques,
+    }
+    with open(out, "w", encoding="utf-8") as fh:
+        json.dump(compact, fh, indent=1)
+    print(
+        f"Wrote {len(db.techniques)} techniques / {len(db.tactics)} tactics "
+        f"to {out}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

attack_mapper/cli.py

@@ -0,0 +1,94 @@
+"""CLI entry point for attack-mapper."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .attack_loader import load_attack
+from .coverage import build_report
+from .renderers import render_terminal, render_html, STYLES
+from .sigma_parser import parse_rules
+from .plugins import render_badge, render_json
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="attack-mapper",
+        description="Map your Sigma detection rules onto the MITRE ATT&CK matrix "
+        "and find coverage gaps.",
+    )
+    p.add_argument(
+        "rules",
+        nargs="+",
+        help="Sigma rule file(s), directory(ies), or glob pattern(s).",
+    )
+    p.add_argument("--db", default=None, help="Path to a compact ATT&CK DB JSON.")
+    p.add_argument(
+        "--html", metavar="PATH", default=None,
+        help="Write a standalone HTML coverage report to PATH.",
+    )
+    p.add_argument(
+        "--style", choices=STYLES, default="matrix",
+        help="HTML layout: matrix (cards), rows (bars), or heat (dense).",
+    )
+    p.add_argument(
+        "--include", nargs="*", default=None, metavar="TOKEN",
+        help="Only count/show techniques or tactics matching these tokens "
+             "(e.g. T1059 TA0002). Others are treated as out-of-scope.",
+    )
+    p.add_argument(
+        "--ignore", nargs="*", default=None, metavar="TOKEN",
+        help="Exclude these techniques/tactics from scope (e.g. T1003 Reconnaissance).",
+    )
+    p.add_argument(
+        "--json", metavar="PATH", default=None,
+        help="Also write a machine-readable JSON summary to PATH.",
+    )
+    p.add_argument(
+        "--badge", metavar="PATH", default=None,
+        help="Also write an SVG coverage badge to PATH (great for a README).",
+    )
+    p.add_argument("--quiet", action="store_true", help="Suppress the terminal table.")
+    p.add_argument("--version", action="version", version="%(prog)s 0.4.0")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        db = load_attack(args.db)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    rules = parse_rules(args.rules)
+    if not rules:
+        print("No Sigma rules found at the given path(s).", file=sys.stderr)
+        return 1
+
+    report = build_report(rules, db, include=args.include, ignore=args.ignore)
+
+    if not args.quiet:
+        print(render_terminal(report))
+
+    if args.html:
+        out = render_html(report, args.html, style=args.style)
+        print(f"\nHTML report written to: {os.path.abspath(out)}")
+
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as fh:
+            fh.write(render_json(report))
+        print(f"JSON summary written to: {os.path.abspath(args.json)}")
+
+    if args.badge:
+        with open(args.badge, "w", encoding="utf-8") as fh:
+            fh.write(render_badge(report))
+        print(f"Badge written to: {os.path.abspath(args.badge)}")
+
+    return 0 if report.covered else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

attack_mapper/coverage.py

@@ -0,0 +1,190 @@
+"""Compute detection coverage and gaps against the ATT&CK matrix.
+
+Supports *scope filters*:
+
+* ``include`` — restrict the analysis to a set of techniques / tactics. Only
+  those are counted toward totals and shown as in-scope.
+* ``ignore``  — explicitly exclude techniques / tactics (e.g. deprecated or
+  out-of-scope for your environment). Ignored items are reported separately.
+
+A token in either set matches if it equals a technique ID, is a prefix of a
+technique ID (so ``T1059`` covers ``T1059.001``), or equals a tactic
+shortname. An empty ``include`` means "everything is in scope".
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional, Set
+
+from .attack_loader import AttackDB
+from .sigma_parser import ParsedRule
+
+
+def _matches(token: str, include: Set[str]) -> bool:
+    """True if ``token`` (technique id or tactic) is covered by ``include``."""
+    token = token.upper()
+    for inc in include:
+        inc = inc.upper()
+        if token == inc or token.startswith(inc + "."):
+            return True
+    return False
+
+
+def _normalize_scope(tokens: Optional[Iterable[str]], db: AttackDB) -> Set[str]:
+    """Uppercase scope tokens, mapping TA tactic IDs to tactic shortnames.
+
+    ``TA0002`` → ``EXECUTION`` so it matches technique tactic lists the same
+    way the shortname form does. Unknown tokens pass through unchanged.
+    """
+    return {db.resolve_tactic_token(s).upper() for s in (tokens or [])}
+
+
+@dataclass
+class CoverageReport:
+    """Result of mapping a set of rules onto ATT&CK, optionally scoped."""
+
+    db: AttackDB
+    covered: Dict[str, List[str]] = field(default_factory=dict)   # technique_id -> [rule paths]
+    unknown: List[str] = field(default_factory=list)             # technique ids not in ATT&CK
+    unmapped_rules: List[ParsedRule] = field(default_factory=list)
+    rule_count: int = 0
+    include: Set[str] = field(default_factory=set)
+    ignore: Set[str] = field(default_factory=set)
+    ignored: List[str] = field(default_factory=list)            # in-scope tokens explicitly ignored
+    out_of_scope: List[str] = field(default_factory=list)       # not matched by include
+
+    @property
+    def covered_techniques(self) -> List[str]:
+        return sorted(self.covered.keys(), key=lambda t: (len(t), t))
+
+    @property
+    def in_scope_techniques(self) -> List[str]:
+        """All ATT&CK techniques that are in scope (after include/ignore)."""
+        result = []
+        for tid, tech in self.db.techniques.items():
+            if self._in_scope(tid, tech):
+                result.append(tid)
+        return sorted(result, key=lambda t: (len(t), t))
+
+    def _in_scope(self, tid: str, tech: dict) -> bool:
+        if self.include and not (
+            _matches(tid, self.include)
+            or any(_matches(t, self.include) for t in tech.get("tactics", []))
+        ):
+            return False
+        if self.ignore and (
+            _matches(tid, self.ignore)
+            or any(_matches(t, self.ignore) for t in tech.get("tactics", []))
+        ):
+            return False
+        return True
+
+    @property
+    def covered_in_scope(self) -> List[str]:
+        """Covered techniques that are also in scope (the ratio numerator).
+
+        A technique detected by a rule but excluded via ``--include`` /
+        ``--ignore`` is still *recorded* in ``covered`` (you did detect it),
+        but it must not count toward the scoped coverage ratio.
+        """
+        in_scope = set(self.in_scope_techniques)
+        return [t for t in self.covered_techniques if t in in_scope]
+
+    @property
+    def total_techniques(self) -> int:
+        """In-scope techniques (the denominator for the coverage ratio)."""
+        return len(self.in_scope_techniques)
+
+    @property
+    def coverage_ratio(self) -> float:
+        total = self.total_techniques
+        return (len(self.covered_in_scope) / total) if total else 0.0
+
+    def tactics_coverage(self) -> Dict[str, dict]:
+        """Per-tactic coverage: how many in-scope techniques covered vs total."""
+        total_by_tactic: Dict[str, int] = defaultdict(int)
+        covered_by_tactic: Dict[str, int] = defaultdict(int)
+
+        for tid, tech in self.db.techniques.items():
+            if not self._in_scope(tid, tech):
+                continue
+            for tactic in tech.get("tactics", []):
+                total_by_tactic[tactic] += 1
+                # Count a covered technique in EVERY tactic it belongs to.
+                # Each tactic row has its own denominator, so this is not
+                # double counting — it's how the ATT&CK matrix itself works:
+                # covering T1053.005 protects Execution AND Persistence AND
+                # Privilege Escalation, and all three bars should say so.
+                if tid in self.covered:
+                    covered_by_tactic[tactic] += 1
+
+        result: Dict[str, dict] = {}
+        for tactic, total in sorted(total_by_tactic.items(), key=lambda x: -x[1]):
+            c = covered_by_tactic.get(tactic, 0)
+            result[tactic] = {
+                "name": self.db.tactic_name(tactic),
+                "covered": c,
+                "total": total,
+                "ratio": (c / total) if total else 0.0,
+            }
+        return result
+
+
+def build_report(
+    rules: List[ParsedRule],
+    db: AttackDB,
+    include: Optional[Iterable[str]] = None,
+    ignore: Optional[Iterable[str]] = None,
+) -> CoverageReport:
+    """Map parsed Sigma rules onto ATT&CK and produce a coverage report."""
+    report = CoverageReport(
+        db=db,
+        rule_count=len(rules),
+        include=_normalize_scope(include, db),
+        ignore=_normalize_scope(ignore, db),
+    )
+    covered: Dict[str, List[str]] = defaultdict(list)
+    seen_unknown: set = set()
+
+    for rule in rules:
+        if not rule.technique_ids:
+            report.unmapped_rules.append(rule)
+            continue
+        for tid in rule.technique_ids:
+            if db.valid_technique(tid):
+                covered[tid].append(rule.path)
+            else:
+                seen_unknown.add(tid)
+
+    # Inherit coverage to parent techniques so the number shown ("N covered")
+    # matches the green cells in the HTML: a covered sub-technique also lights
+    # up its parent technique.
+    for tid in list(covered.keys()):
+        if "." in tid:
+            parent = tid.split(".", 1)[0]
+            if parent in db.techniques and parent not in covered:
+                covered[parent] = list(covered[tid])
+
+    report.covered = dict(covered)
+    report.unknown = sorted(seen_unknown, key=lambda t: (len(t), t))
+
+    # Classify each ATT&CK technique as ignored or out-of-scope (for reporting).
+    for tid, tech in db.techniques.items():
+        if tid in report.covered or tid in seen_unknown:
+            continue
+        is_ignored = bool(report.ignore) and (
+            _matches(tid, report.ignore)
+            or any(_matches(t, report.ignore) for t in tech.get("tactics", []))
+        )
+        if is_ignored:
+            report.ignored.append(tid)
+        elif report.include and not (
+            _matches(tid, report.include)
+            or any(_matches(t, report.include) for t in tech.get("tactics", []))
+        ):
+            report.out_of_scope.append(tid)
+    report.ignored.sort(key=lambda t: (len(t), t))
+    report.out_of_scope.sort(key=lambda t: (len(t), t))
+    return report