attack-mapper 0.4.0__tar.gz

attack_mapper-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose (JoseArgento)
+
+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.

attack_mapper-0.4.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: attack-mapper
+Version: 0.4.0
+Summary: Map your Sigma detection rules onto the MITRE ATT&CK matrix and find coverage gaps.
+Author: Jose (JoseArgento)
+License: MIT
+Project-URL: Homepage, https://github.com/JoseArgento/attack-mapper
+Project-URL: Repository, https://github.com/JoseArgento/attack-mapper
+Project-URL: Issues, https://github.com/JoseArgento/attack-mapper/issues
+Keywords: mitre,att-ck,sigma,detection-engineering,soc,blue-team
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# attack-mapper 🎯
+
+[![CI](https://github.com/JoseArgento/attack-mapper/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseArgento/attack-mapper/actions/workflows/ci.yml)
+[![ATT&CK dataset](https://github.com/JoseArgento/attack-mapper/actions/workflows/update-attack-db.yml/badge.svg)](https://github.com/JoseArgento/attack-mapper/actions/workflows/update-attack-db.yml)
+[![PyPI](https://img.shields.io/pypi/v/attack-mapper)](https://pypi.org/project/attack-mapper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Map your **Sigma detection rules** onto the **MITRE ATT&CK** matrix and find your
+coverage gaps — fast, offline, and CI-friendly.
+
+Part of a detection-engineering toolkit that pairs perfectly with a
+*Detection-as-Code* pipeline (Sigma → CI → SIEM). It answers the question every
+blue team eventually asks: *"Which ATT&CK techniques do my rules actually
+cover, and where are the blind spots?"*
+
+## Features
+
+- 🔍 Extracts ATT&CK technique IDs from Sigma rules via:
+  - canonical `attack.<id>` tags,
+  - raw `T1059` tags,
+  - `attack.mitre.org/techniques/...` URLs in `references:`.
+- 📊 Per-tactic coverage bars + overall coverage ratio in the terminal.
+- 🎨 **Four HTML styles** to show off your coverage:
+  - `matrix` (default) — tactic cards with technique chips,
+  - `rows` — compact tactic progress bars,
+  - `heat` — dense heatmap of every technique,
+  - `report` — print-ready dossier with canonical vertical ATT&CK columns
+    and sub-techniques nested under their parents (PDF it for audits/portfolio).
+- 🟢 Covered techniques (incl. parent techniques of covered sub-techniques)
+  render green; gaps render red; explicitly ignored ones render grey.
+- 🔎 **Scope filters** — `--include` and `--ignore` narrow the analysis to the
+  techniques/tactics you care about (or exclude the ones you don't). The active
+  scope is shown in the report so readers know what was filtered.
+- 🏅 **Portfolio badge** (`--badge`) — a shields.io-style SVG coverage badge.
+- 🧾 **JSON summary** (`--json`) — machine-readable output for dashboards/CI.
+- 🧭 **ATT&CK Navigator export** — every HTML report embeds an
+  "Export layer" button that downloads a ready-to-import Navigator layer.
+- 🧱 Uses the **real MITRE ATT&CK enterprise dataset** (v19 structure:
+  Stealth + Defense Impairment). Revoked/deprecated techniques are
+  filtered out so the coverage denominator matches the official matrix
+  (15 tactics, 222 techniques, 475 sub-techniques). Shipped as a compact
+  JSON, no network needed at runtime.
+- ✅ Pure Python stdlib + `pyyaml`; tiny dependency footprint.
+- 🤖 Non-zero exit when nothing maps → use it as a **CI gate** in your
+  detection repo.
+
+## Screenshots
+
+| `report` (print-ready dossier) | `matrix` (cards) |
+| --- | --- |
+| ![report style](docs/screenshot_report.png) | ![matrix style](docs/screenshot_matrix.png) |
+
+## Install
+
+```bash
+pip install attack-mapper
+```
+
+For development:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```bash
+# Map a folder of Sigma rules, print the terminal report, emit HTML (matrix)
+attack-mapper rules/ --html sample/coverage_matrix.html
+
+# Try the other HTML styles
+attack-mapper rules/ --html sample/coverage_rows.html  --style rows
+attack-mapper rules/ --html sample/coverage_heat.html  --style heat
+attack-mapper rules/ --html sample/coverage_report.html --style report
+
+# Scope the analysis: only Execution + T1053, ignore Reconnaissance
+attack-mapper rules/ --include T1059 TA0002 --ignore Reconnaissance
+
+# Portfolio artifacts: badge + JSON
+attack-mapper rules/ --badge sample/coverage_badge.svg --json sample/coverage.json
+```
+
+Run against the bundled sample rules:
+
+```bash
+attack-mapper rules/ --html sample/coverage_matrix.html --badge sample/coverage_badge.svg
+```
+
+## Why not sigma2attack or DeTT&CT?
+
+Both are excellent and you should know they exist. **sigma2attack** (from the
+Sigma tooling) converts Sigma rules into an ATT&CK Navigator heatmap layer —
+if all you need is a layer file, it does the job. **DeTT&CT** is the
+heavyweight: it scores data-source *visibility* as well as detection
+coverage, and is the right tool for a mature SOC doing formal capability
+assessments.
+
+attack-mapper sits in between, optimized for Detection-as-Code pipelines:
+it runs offline with a bundled dataset, produces self-contained HTML
+reports you can email or print (plus the Navigator layer, a badge, and
+JSON), gates CI with its exit code, and supports scope filters for
+counting only the techniques relevant to your environment. It is also
+**ATT&CK v19-native** (Stealth + Defense Impairment) with a scheduled
+workflow that flags future MITRE updates automatically.
+
+## How it works
+
+```
+Sigma rules ──▶ sigma_parser ──▶ technique IDs
+                                    │
+ATT&CK DB  ──▶ attack_loader       │
+                                    ▼
+            coverage.build_report (with --include/--ignore) ──▶ CoverageReport
+                                    │
+            renderers (terminal / HTML matrix|rows|heat)
+            plugins  (badge SVG / JSON)
+```
+
+## Scope filters
+
+`--include` and `--ignore` accept technique IDs (e.g. `T1059`), sub-technique
+prefixes (e.g. `T1059` also covers `T1059.001`), tactic shortnames
+(e.g. `execution`) or tactic IDs (e.g. `TA0002`). A covered technique is always
+recorded as covered even if it falls outside an `--include` scope, but only
+in-scope covered techniques count toward the coverage ratio (both numerator
+and denominator are scoped).
+
+## Updating the ATT&CK dataset
+
+The shipped `attack_mapper/data/attack_db.json` is a snapshot (regenerated
+automatically by a monthly GitHub Action that fails when MITRE ships an update). To regenerate from the latest
+official STIX bundle:
+
+```bash
+curl -L -o enterprise-attack.json \
+  https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json
+ATTACK_MAPPER_STIX=enterprise-attack.json python -m attack_mapper.build_db
+```
+
+You can also run directly off the STIX bundle at runtime by setting
+`ATTACK_MAPPER_STIX`.
+
+## Project layout
+
+```
+attack-mapper/
+├── attack_mapper/
+│   ├── cli.py            # argparse entry point
+│   ├── sigma_parser.py   # Sigma → ATT&CK technique IDs
+│   ├── attack_loader.py  # ATT&CK DB (compact JSON / STIX)
+│   ├── coverage.py       # coverage + gaps + scope filters
+│   ├── renderers.py      # terminal table + 4 HTML styles
+│   ├── plugins.py        # badge SVG + JSON summary
+│   ├── build_db.py       # regenerate the compact ATT&CK DB
+│   └── data/attack_db.json  # real ATT&CK (compact, ships with the package)
+├── rules/                # sample Sigma rules
+├── sample/               # generated HTML / badge / JSON examples
+├── tests/                # pytest suite
+└── pyproject.toml
+```
+
+## License
+
+MIT

attack_mapper-0.4.0/README.md

@@ -0,0 +1,166 @@
+# attack-mapper 🎯
+
+[![CI](https://github.com/JoseArgento/attack-mapper/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseArgento/attack-mapper/actions/workflows/ci.yml)
+[![ATT&CK dataset](https://github.com/JoseArgento/attack-mapper/actions/workflows/update-attack-db.yml/badge.svg)](https://github.com/JoseArgento/attack-mapper/actions/workflows/update-attack-db.yml)
+[![PyPI](https://img.shields.io/pypi/v/attack-mapper)](https://pypi.org/project/attack-mapper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Map your **Sigma detection rules** onto the **MITRE ATT&CK** matrix and find your
+coverage gaps — fast, offline, and CI-friendly.
+
+Part of a detection-engineering toolkit that pairs perfectly with a
+*Detection-as-Code* pipeline (Sigma → CI → SIEM). It answers the question every
+blue team eventually asks: *"Which ATT&CK techniques do my rules actually
+cover, and where are the blind spots?"*
+
+## Features
+
+- 🔍 Extracts ATT&CK technique IDs from Sigma rules via:
+  - canonical `attack.<id>` tags,
+  - raw `T1059` tags,
+  - `attack.mitre.org/techniques/...` URLs in `references:`.
+- 📊 Per-tactic coverage bars + overall coverage ratio in the terminal.
+- 🎨 **Four HTML styles** to show off your coverage:
+  - `matrix` (default) — tactic cards with technique chips,
+  - `rows` — compact tactic progress bars,
+  - `heat` — dense heatmap of every technique,
+  - `report` — print-ready dossier with canonical vertical ATT&CK columns
+    and sub-techniques nested under their parents (PDF it for audits/portfolio).
+- 🟢 Covered techniques (incl. parent techniques of covered sub-techniques)
+  render green; gaps render red; explicitly ignored ones render grey.
+- 🔎 **Scope filters** — `--include` and `--ignore` narrow the analysis to the
+  techniques/tactics you care about (or exclude the ones you don't). The active
+  scope is shown in the report so readers know what was filtered.
+- 🏅 **Portfolio badge** (`--badge`) — a shields.io-style SVG coverage badge.
+- 🧾 **JSON summary** (`--json`) — machine-readable output for dashboards/CI.
+- 🧭 **ATT&CK Navigator export** — every HTML report embeds an
+  "Export layer" button that downloads a ready-to-import Navigator layer.
+- 🧱 Uses the **real MITRE ATT&CK enterprise dataset** (v19 structure:
+  Stealth + Defense Impairment). Revoked/deprecated techniques are
+  filtered out so the coverage denominator matches the official matrix
+  (15 tactics, 222 techniques, 475 sub-techniques). Shipped as a compact
+  JSON, no network needed at runtime.
+- ✅ Pure Python stdlib + `pyyaml`; tiny dependency footprint.
+- 🤖 Non-zero exit when nothing maps → use it as a **CI gate** in your
+  detection repo.
+
+## Screenshots
+
+| `report` (print-ready dossier) | `matrix` (cards) |
+| --- | --- |
+| ![report style](docs/screenshot_report.png) | ![matrix style](docs/screenshot_matrix.png) |
+
+## Install
+
+```bash
+pip install attack-mapper
+```
+
+For development:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```bash
+# Map a folder of Sigma rules, print the terminal report, emit HTML (matrix)
+attack-mapper rules/ --html sample/coverage_matrix.html
+
+# Try the other HTML styles
+attack-mapper rules/ --html sample/coverage_rows.html  --style rows
+attack-mapper rules/ --html sample/coverage_heat.html  --style heat
+attack-mapper rules/ --html sample/coverage_report.html --style report
+
+# Scope the analysis: only Execution + T1053, ignore Reconnaissance
+attack-mapper rules/ --include T1059 TA0002 --ignore Reconnaissance
+
+# Portfolio artifacts: badge + JSON
+attack-mapper rules/ --badge sample/coverage_badge.svg --json sample/coverage.json
+```
+
+Run against the bundled sample rules:
+
+```bash
+attack-mapper rules/ --html sample/coverage_matrix.html --badge sample/coverage_badge.svg
+```
+
+## Why not sigma2attack or DeTT&CT?
+
+Both are excellent and you should know they exist. **sigma2attack** (from the
+Sigma tooling) converts Sigma rules into an ATT&CK Navigator heatmap layer —
+if all you need is a layer file, it does the job. **DeTT&CT** is the
+heavyweight: it scores data-source *visibility* as well as detection
+coverage, and is the right tool for a mature SOC doing formal capability
+assessments.
+
+attack-mapper sits in between, optimized for Detection-as-Code pipelines:
+it runs offline with a bundled dataset, produces self-contained HTML
+reports you can email or print (plus the Navigator layer, a badge, and
+JSON), gates CI with its exit code, and supports scope filters for
+counting only the techniques relevant to your environment. It is also
+**ATT&CK v19-native** (Stealth + Defense Impairment) with a scheduled
+workflow that flags future MITRE updates automatically.
+
+## How it works
+
+```
+Sigma rules ──▶ sigma_parser ──▶ technique IDs
+                                    │
+ATT&CK DB  ──▶ attack_loader       │
+                                    ▼
+            coverage.build_report (with --include/--ignore) ──▶ CoverageReport
+                                    │
+            renderers (terminal / HTML matrix|rows|heat)
+            plugins  (badge SVG / JSON)
+```
+
+## Scope filters
+
+`--include` and `--ignore` accept technique IDs (e.g. `T1059`), sub-technique
+prefixes (e.g. `T1059` also covers `T1059.001`), tactic shortnames
+(e.g. `execution`) or tactic IDs (e.g. `TA0002`). A covered technique is always
+recorded as covered even if it falls outside an `--include` scope, but only
+in-scope covered techniques count toward the coverage ratio (both numerator
+and denominator are scoped).
+
+## Updating the ATT&CK dataset
+
+The shipped `attack_mapper/data/attack_db.json` is a snapshot (regenerated
+automatically by a monthly GitHub Action that fails when MITRE ships an update). To regenerate from the latest
+official STIX bundle:
+
+```bash
+curl -L -o enterprise-attack.json \
+  https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json
+ATTACK_MAPPER_STIX=enterprise-attack.json python -m attack_mapper.build_db
+```
+
+You can also run directly off the STIX bundle at runtime by setting
+`ATTACK_MAPPER_STIX`.
+
+## Project layout
+
+```
+attack-mapper/
+├── attack_mapper/
+│   ├── cli.py            # argparse entry point
+│   ├── sigma_parser.py   # Sigma → ATT&CK technique IDs
+│   ├── attack_loader.py  # ATT&CK DB (compact JSON / STIX)
+│   ├── coverage.py       # coverage + gaps + scope filters
+│   ├── renderers.py      # terminal table + 4 HTML styles
+│   ├── plugins.py        # badge SVG + JSON summary
+│   ├── build_db.py       # regenerate the compact ATT&CK DB
+│   └── data/attack_db.json  # real ATT&CK (compact, ships with the package)
+├── rules/                # sample Sigma rules
+├── sample/               # generated HTML / badge / JSON examples
+├── tests/                # pytest suite
+└── pyproject.toml
+```
+
+## License
+
+MIT

attack_mapper-0.4.0/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-0.4.0/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-0.4.0/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-0.4.0/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())