attack-mapper 0.4.0__py3-none-any.whl

attack_mapper/sigma_parser.py

@@ -0,0 +1,128 @@
+"""Parse Sigma rules and extract referenced MITRE ATT&CK techniques.
+
+Sigma rules are YAML files. ATT&CK technique IDs (e.g. ``T1059``) are commonly
+referenced in a few places:
+
+* ``tags:`` list, as ``attack.<id>`` (the Sigma convention) or raw ``T1059``.
+* ``references:`` list of URLs containing ``attack.mitre.org/techniques/Txxxx``.
+* Free text in the ``description:`` / ``logsource:`` (rare, optional).
+
+This module supports both the canonical ``attack.*`` tag form and URL
+extraction so it works with rules written by different teams.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Iterable
+
+try:
+    import yaml
+except ImportError as exc:  # pragma: no cover - surfaced to the user clearly
+    raise SystemExit(
+        "PyYAML is required. Install it with: pip install pyyaml"
+    ) from exc
+
+
+# Matches T<4 digits> optionally followed by .<2-3 digits> (sub-technique)
+TECH_ID_RE = re.compile(r"\bT\d{4}(?:\.\d{1,3})?\b", re.IGNORECASE)
+# MITRE URLs use slashes (attack.mitre.org/techniques/T1059/001), so accept
+# both '.' and '/' as the sub-technique separator and normalize to '.'.
+URL_RE = re.compile(r"attack\.mitre\.org/techniques/(T\d{4}(?:[./]\d{1,3})?)", re.IGNORECASE)
+
+
+@dataclass
+class ParsedRule:
+    """A Sigma rule reduced to the data we care about for coverage mapping."""
+
+    path: str
+    title: str | None = None
+    technique_ids: set[str] = field(default_factory=set)
+
+    @property
+    def techniques(self) -> list[str]:
+        return sorted(self.technique_ids, key=lambda t: (len(t), t))
+
+
+def _extract_from_tags(tags: Iterable[str]) -> set[str]:
+    found = set()
+    for tag in tags or []:
+        if not isinstance(tag, str):
+            continue
+        # Canonical Sigma form: attack.t1059 / attack.t1059.001 (case-insensitive)
+        if tag.lower().startswith("attack."):
+            cand = tag.split(".", 1)[1]
+            m = TECH_ID_RE.search(cand)
+            if m:
+                found.add(m.group(0).upper())
+        else:
+            m = TECH_ID_RE.search(tag)
+            if m:
+                found.add(m.group(0).upper())
+    return found
+
+
+def _extract_from_references(references: Iterable) -> set[str]:
+    found = set()
+    for ref in references or []:
+        url = ref.get("url") if isinstance(ref, dict) else str(ref)
+        if not url:
+            continue
+        for m in URL_RE.finditer(url):
+            # Normalize a slash separator (T1059/001) to a dot (T1059.001)
+            found.add(m.group(1).upper().replace("/", "."))
+    return found
+
+
+def parse_rule_text(text: str, path: str = "<string>") -> ParsedRule:
+    """Parse a single Sigma rule from a YAML string."""
+    try:
+        doc = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return ParsedRule(path=path, title=None, technique_ids=set())
+
+    if not isinstance(doc, dict):
+        return ParsedRule(path=path, title=None, technique_ids=set())
+
+    rule = ParsedRule(path=path, title=doc.get("title"))
+
+    found = set()
+    found |= _extract_from_tags(doc.get("tags", []))
+    found |= _extract_from_references(doc.get("references", []))
+    # Fallback: scan description for raw technique IDs
+    desc = doc.get("description") or ""
+    if isinstance(desc, str):
+        found |= {m.group(0).upper() for m in TECH_ID_RE.finditer(desc)}
+
+    rule.technique_ids = found
+    return rule
+
+
+def parse_rule_file(path: str) -> ParsedRule:
+    """Parse a Sigma rule from a file on disk."""
+    with open(path, "r", encoding="utf-8") as fh:
+        return parse_rule_text(fh.read(), path=path)
+
+
+def parse_rules(paths: Iterable[str]) -> list[ParsedRule]:
+    """Parse many rule files. ``paths`` may include glob patterns."""
+    resolved: list[str] = []
+    for p in paths:
+        if any(ch in p for ch in "*?[]"):
+            resolved.extend(sorted(glob.glob(p, recursive=True)))
+        elif os.path.isdir(p):
+            resolved.extend(sorted(glob.glob(os.path.join(p, "**", "*.yml"), recursive=True)))
+            resolved.extend(sorted(glob.glob(os.path.join(p, "**", "*.yaml"), recursive=True)))
+        elif os.path.isfile(p):
+            resolved.append(p)
+    # De-duplicate while preserving order
+    seen, rules = set(), []
+    for fp in resolved:
+        if fp in seen:
+            continue
+        seen.add(fp)
+        rules.append(parse_rule_file(fp))
+    return rules

attack_mapper-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+attack_mapper/__init__.py,sha256=8E18haz50dxYNYdDxJp3C8ojsctzdhhLT6dfxw8L8nM,687
+attack_mapper/attack_loader.py,sha256=v323T6kObJ0e2WEkF2Ro79UFBYcObUSkd4gOeri7RHM,5332
+attack_mapper/build_db.py,sha256=mBV3WGxd4Xu0pV769eqvKzXrK5yGS87oT0r9U7vG5Pk,1173
+attack_mapper/cli.py,sha256=6LUz7XLd7unNnrBhdBnOeIVyo1o8kBTWOfvD-YkBnOo,3099
+attack_mapper/coverage.py,sha256=8JAaH3Dh2iZbjv03ltPk9GYXFPJ6ePlWOKgpFCsfkqg,7457
+attack_mapper/plugins.py,sha256=BJOIHWUubcqTjcdGsK6gF9TDztDoX4kthC6pQrkSS-U,2677
+attack_mapper/renderers.py,sha256=y89X4W6Gs7BWCKv0ZewzUepnaPAf9su5RbbzYHkQcqY,29866
+attack_mapper/sigma_parser.py,sha256=A_YZgbC2R1BhPfFbMmkekZyrRUnXdSLqvg8rmDftNHE,4400
+attack_mapper/data/attack_db.json,sha256=8itrhEmKWjqy7nYKv29wmZJDmAz-H5UpmeOKQ9DEYDI,148132
+attack_mapper-0.4.0.dist-info/licenses/LICENSE,sha256=UQZhhedQt0Hg_y1c16euHxg79FIigwTEWjETNCBz78Y,1075
+attack_mapper-0.4.0.dist-info/METADATA,sha256=ax7hy2u5TPDRE9F_E1siFisIktRd4SL3rTy-S_7hY3o,8177
+attack_mapper-0.4.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+attack_mapper-0.4.0.dist-info/entry_points.txt,sha256=l1kpky2iHq28vnfzZq-g3uPcjVhNZzyYaz3YSDvX6aI,57
+attack_mapper-0.4.0.dist-info/top_level.txt,sha256=DpO7ULjELDmK02KXSLwvGUSRbKNr6F5trdGEh1HCcjU,14
+attack_mapper-0.4.0.dist-info/RECORD,,

attack_mapper-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

attack_mapper-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+attack-mapper = attack_mapper.cli:main

attack_mapper-0.4.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+attack_mapper