attackmap 0.6.4__py3-none-any.whl

attackmap/exploitability.py

@@ -0,0 +1,493 @@
+"""Exploitability fusion — 'exploitable now' risk scoring (#79).
+
+Everything AttackMap already knows about a route→sink path is fused into a
+single 0–100 score so the highest-risk *combinations* rise to the top of the
+report — the public, unauthenticated route whose request reaches a SQL sink
+next to a secret is a different animal from an internal, authed route that
+reaches the same sink two hops away, even though both are "SQL injection."
+
+Design goals (both from the ticket):
+
+- **Deterministic.** The same scan always produces the same score; no
+  randomness, no clock, no ordering-dependent state. Ties break on a stable
+  key.
+- **Explainable.** The score is the clamped sum of named `ExploitabilityFactor`
+  contributions — every point is attributable, and a factor worth 0 points is
+  still recorded when it's decision-relevant (e.g. "auth present at entry").
+
+The fusion unit is the taint chain (route → dangerous sink). Auth, exposure
+and surface category come from the matching `AttackSurface`; data sensitivity
+from datastores / secrets co-located with the sink; and insecure-crypto /
+web-hardening gaps plus known-vulnerable dependencies imported on the path act
+as amplifiers. CVE fusion (#104) resolves each path file's bare imports to
+package names and matches them against the `--cve` advisory set, so a public
+route reaching a sink through a known-RCE library version scores higher.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .safe_fs import contained_file
+from .models import (
+    AttackSurface,
+    ExploitabilityFactor,
+    ExploitabilityScore,
+    ExploitabilityTier,
+    ScanResult,
+    TaintChain,
+)
+from .srcpaths import JS_TS_SUFFIXES, is_infra_route
+from .taint_sinks import kind_base_score, kind_label
+
+# Human labels for sink kinds (kept in sync with threat_model._TAINT_SINK_LABEL).
+_SINK_LABEL: dict[str, str] = {
+    "sql_execute": "database (SQL execute)",
+    "subprocess_shell": "command execution",
+    "eval": "code eval",
+    "exec": "code exec",
+    "dynamic_open": "filesystem open",
+    "unsafe_deserialization": "unsafe deserialization",
+    "ssti": "template injection",
+    "ssrf": "outbound request (SSRF)",
+    "nosql_injection": "NoSQL query",
+    "open_redirect": "redirect target",
+}
+
+# Base points by sink danger. RCE / SQLi / deserialization class sit at the
+# top; redirect/SSRF are lower because impact is usually narrower.
+_SINK_BASE: dict[str, int] = {
+    "sql_execute": 35,
+    "exec": 35,
+    "eval": 35,
+    "subprocess_shell": 35,
+    "unsafe_deserialization": 35,
+    "ssti": 30,
+    "nosql_injection": 25,
+    "dynamic_open": 22,
+    "ssrf": 20,
+    "open_redirect": 15,
+}
+
+_EXPOSURE_PTS: dict[str, int] = {"public": 20, "unknown": 10, "internal": 5}
+
+# Closer sinks are more exploitable (import-edge ≠ call-edge, but a same-file
+# sink is a stronger signal than a two-hop transitive one).
+_HOPS_PTS: dict[int, int] = {0: 15, 1: 10, 2: 5}
+
+_NO_AUTH_PTS = 20
+_SECRET_AT_SINK_PTS = 15
+_DATASTORE_AT_SINK_PTS = 10
+_WEAKNESS_ON_PATH_PTS = 5
+# A known-vulnerable dependency imported on the path amplifies by CVE severity.
+_CVE_ON_PATH_PTS = {"high": 15, "medium": 8, "low": 3}
+# A risky (not known-vulnerable) dependency on the path is a weaker signal.
+_SUPPLY_CHAIN_ON_PATH_PTS = {"high": 8, "medium": 4, "low": 2}
+_MAX_FILE_BYTES = 1_000_000
+
+# Bare (non-relative) module specifiers imported by a source file.
+_JS_IMPORT_PKG_RE = re.compile(
+    r"""(?:from|require\(\s*)\s*["'](?P<pkg>@?[a-z0-9._-]+(?:/[a-z0-9._-]+)*)["']""",
+    re.IGNORECASE,
+)
+# Single-line only (#226): `\s` used to swallow newlines, so `import os` ran on
+# into the next statement and every later import was lost.
+_PY_IMPORT_PKG_RE = re.compile(
+    r"^[ \t]*(?:from[ \t]+(?P<from>[\w.]+)[ \t]+import\b"
+    r"|import[ \t]+(?P<mod>[\w.]+(?:[ \t]+as[ \t]+\w+)?(?:[ \t]*,[ \t]*[\w.]+(?:[ \t]+as[ \t]+\w+)?)*))",
+    re.MULTILINE,
+)
+# Import name → PyPI distribution name where they differ, so CVE fusion
+# matches `import yaml` against a PyYAML advisory (#226).
+_PY_MODULE_TO_DIST = {
+    "yaml": "pyyaml",
+    "pil": "pillow",
+    "bs4": "beautifulsoup4",
+    "jwt": "pyjwt",
+    "crypto": "pycryptodome",
+    "cryptodome": "pycryptodomex",
+    "cv2": "opencv-python",
+    "sklearn": "scikit-learn",
+    "dateutil": "python-dateutil",
+    "dns": "dnspython",
+    "openssl": "pyopenssl",
+    "jose": "python-jose",
+    "multipart": "python-multipart",
+    "magic": "python-magic",
+    "docx": "python-docx",
+    "git": "gitpython",
+    "ldap": "python-ldap",
+    "serial": "pyserial",
+    "usb": "pyusb",
+    "zmq": "pyzmq",
+    "nacl": "pynacl",
+    "markdown": "markdown",
+    "attr": "attrs",
+    "google.protobuf": "protobuf",
+}
+
+# Tier thresholds on the clamped 0–100 score.
+_TIERS: tuple[tuple[int, ExploitabilityTier], ...] = (
+    (75, "critical"),
+    (50, "high"),
+    (25, "medium"),
+    (0, "low"),
+)
+
+
+def score_exploitability(
+    scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None
+) -> list[ExploitabilityScore]:
+    """Return one deterministic ExploitabilityScore per taint chain, ranked
+    most-exploitable first."""
+    surfaces = attack_surfaces or []
+    surface_index = _SurfaceIndex(surfaces)
+
+    secret_files = {_norm(h.file) for h in scan.secret_hints}
+    secret_modules = {_module(h.file) for h in scan.secret_hints}
+    db_files = {_norm(d.file) for d in scan.databases}
+    db_modules = {_module(d.file) for d in scan.databases}
+    weakness_files = {_norm(w.file) for w in scan.crypto_weaknesses}
+    weakness_files |= {_norm(w.file) for w in scan.web_hardening_issues}
+
+    # CVE → exploitability fusion (#104): a known-vulnerable dependency imported
+    # by a file on the route→sink path amplifies the score by CVE severity.
+    vuln_index = _vuln_index(scan)
+    # Supply-chain risk (#247): a typosquat / confusable / mutable / install-
+    # script dependency imported on the path amplifies like a CVE does.
+    risk_index = _supply_chain_index(scan)
+    root = Path(scan.root)
+    import_cache: dict[str, set[str]] = {}
+
+    scores: list[ExploitabilityScore] = []
+    for chain in scan.taint_chains:
+        # Sanitized chains (#137) are neutralized before the sink — not
+        # "exploitable now", so they don't earn an exploitability score.
+        # Speculative recall chains (#148a) are unconfirmed leads — likewise
+        # not scored as exploitable until the verifier confirms them.
+        if chain.sanitized or chain.speculative:
+            continue
+        # Skip conventional infra/static routes — a SQL/RCE sink "reachable"
+        # from robots.txt or /_health is over-linking, not an exploit.
+        if is_infra_route(chain.route_path):
+            continue
+        vuln_on_path = _vulns_on_path(chain, vuln_index, root, import_cache) if vuln_index else []
+        risk_on_path = _vulns_on_path(chain, risk_index, root, import_cache) if risk_index else []
+        scores.append(
+            _score_chain(
+                chain,
+                surface_index,
+                secret_files,
+                secret_modules,
+                db_files,
+                db_modules,
+                weakness_files,
+                vuln_on_path,
+                risk_on_path,
+            )
+        )
+
+    scores.sort(key=lambda s: (-s.score, s.route, s.location))
+    return scores
+
+
+def best_by_sink_kind(scores: list[ExploitabilityScore]) -> dict[str, ExploitabilityScore]:
+    """Map each sink kind to its highest-scoring chain — used to attach a
+    single exploitability number to the aggregated per-kind taint finding."""
+    best: dict[str, ExploitabilityScore] = {}
+    for s in scores:
+        cur = best.get(s.sink_kind)
+        if cur is None or s.score > cur.score:
+            best[s.sink_kind] = s
+    return best
+
+
+# --- Internals -------------------------------------------------------------
+
+
+class _SurfaceIndex:
+    """Match a chain to the attack surface of its own entry route (#226).
+
+    Two services in a monorepo can both expose `POST /run`; keying on
+    (method, route) alone handed both chains whichever surface came first, so an
+    unauthenticated route inherited its authed twin's auth signals. Look up by
+    (method, route, file) first, and fall back only to an unambiguous match.
+    """
+
+    def __init__(self, surfaces: list[AttackSurface]) -> None:
+        self._exact: dict[tuple[str, str, str], AttackSurface] = {}
+        self._by_route: dict[tuple[str, str], list[AttackSurface]] = {}
+        self._by_file: dict[str, list[AttackSurface]] = {}
+        for s in surfaces:
+            self._exact.setdefault((s.method, s.route, _norm(s.file)), s)
+            self._by_route.setdefault((s.method, s.route), []).append(s)
+            self._by_file.setdefault(_norm(s.file), []).append(s)
+
+    def lookup(self, chain: TaintChain) -> AttackSurface | None:
+        route_file = _norm(chain.route_file)
+        exact = self._exact.get((chain.route_method, chain.route_path, route_file))
+        if exact is not None:
+            return exact
+        for candidates in (
+            self._by_route.get((chain.route_method, chain.route_path), []),
+            self._by_file.get(route_file, []),
+        ):
+            if len(candidates) == 1:
+                return candidates[0]
+        return None
+
+
+def _vulns_on_path(
+    chain: TaintChain,
+    vuln_index: dict[str, tuple[str, list[str]]],
+    root: Path,
+    cache: dict[str, set[str]],
+) -> list[tuple[str, str, list[str]]]:
+    """Return (pkg, severity, ids) for known-vulnerable deps imported by any
+    file on the chain's route→sink path. Deterministic (sorted by pkg)."""
+    matches: dict[str, tuple[str, list[str]]] = {}
+    path_files = dict.fromkeys(_norm(f) for f in (chain.route_file, *chain.files, chain.sink_file))
+    for rel in path_files:
+        if rel not in cache:
+            cache[rel] = _read_external_imports(contained_file(root, rel))
+        for pkg in cache[rel]:
+            hit = vuln_index.get(pkg)
+            if hit is not None:
+                matches[pkg] = hit
+    return sorted((pkg, sev, ids) for pkg, (sev, ids) in matches.items())
+
+
+def _read_external_imports(path: Path | None) -> set[str]:
+    try:
+        if path is not None and path.stat().st_size <= _MAX_FILE_BYTES:
+            return _external_imports(path.read_text(encoding="utf-8", errors="ignore"), path.suffix)
+    except (OSError, ValueError):
+        pass
+    return set()
+
+
+def _score_chain(
+    chain: TaintChain,
+    surface_index: "_SurfaceIndex",
+    secret_files: set[str],
+    secret_modules: set[str],
+    db_files: set[str],
+    db_modules: set[str],
+    weakness_files: set[str],
+    vuln_on_path: list[tuple[str, str, list[str]]] | None = None,
+    risk_on_path: list[tuple[str, str, list[str]]] | None = None,
+) -> ExploitabilityScore:
+    factors: list[ExploitabilityFactor] = []
+    sink_label = _SINK_LABEL.get(chain.sink_kind) or kind_label(chain.sink_kind)
+
+    # 1. Sink danger (base).
+    # Kinds without a hand-tuned weight take the registry's base score (#240).
+    base = _SINK_BASE.get(chain.sink_kind) or kind_base_score(chain.sink_kind)
+    factors.append(
+        ExploitabilityFactor(
+            name=f"reaches {chain.sink_kind} sink",
+            points=base,
+            detail=f"request-derived data reaches a {sink_label} sink at "
+            f"{chain.sink_file}:{chain.sink_line}",
+        )
+    )
+
+    surface = surface_index.lookup(chain)
+
+    # 2. Exposure.
+    exposure = surface.exposure if surface else "unknown"
+    factors.append(
+        ExploitabilityFactor(
+            name=f"{exposure} exposure",
+            points=_EXPOSURE_PTS.get(exposure, 10),
+            detail=(
+                f"entry route {chain.route_method} {chain.route_path} is {exposure}"
+                + (f" ({surface.category})" if surface else " (no surface classification)")
+            ),
+        )
+    )
+
+    # 3. Auth at entry.
+    has_auth = bool(surface and surface.auth_signals)
+    if has_auth:
+        factors.append(
+            ExploitabilityFactor(
+                name="auth present at entry",
+                points=0,
+                detail=f"auth signals observed: {', '.join(surface.auth_signals)}",
+            )
+        )
+    else:
+        factors.append(
+            ExploitabilityFactor(
+                name="no auth at entry",
+                points=_NO_AUTH_PTS,
+                detail="no auth signal observed on the entry route",
+            )
+        )
+
+    # 4. Reachability (closer = higher).
+    factors.append(
+        ExploitabilityFactor(
+            name=f"{chain.hops}-hop reachability",
+            points=_HOPS_PTS.get(chain.hops, 3),
+            detail=f"{chain.hops} import edge(s) from route to sink",
+        )
+    )
+
+    # 5. Data sensitivity at the sink.
+    sink_file = _norm(chain.sink_file)
+    sink_mod = _module(chain.sink_file)
+    if sink_file in secret_files or sink_mod in secret_modules:
+        factors.append(
+            ExploitabilityFactor(
+                name="secret material at sink",
+                points=_SECRET_AT_SINK_PTS,
+                detail="a secret/credential is co-located with the sink",
+            )
+        )
+    elif sink_file in db_files or sink_mod in db_modules:
+        factors.append(
+            ExploitabilityFactor(
+                name="datastore at sink",
+                points=_DATASTORE_AT_SINK_PTS,
+                detail="a datastore is co-located with the sink",
+            )
+        )
+
+    # 6. Amplifiers on the path.
+    path_files = {_norm(f) for f in (*chain.files, chain.route_file, chain.sink_file)}
+    if path_files & weakness_files:
+        factors.append(
+            ExploitabilityFactor(
+                name="crypto/web-hardening gap on path",
+                points=_WEAKNESS_ON_PATH_PTS,
+                detail="an insecure-crypto or web-hardening issue sits on this path",
+            )
+        )
+
+    # 7. Known-vulnerable dependency imported on the path (#104).
+    for pkg, severity, ids in vuln_on_path or []:
+        factors.append(
+            ExploitabilityFactor(
+                name=f"vulnerable dependency on path ({pkg})",
+                points=_CVE_ON_PATH_PTS.get(severity, 8),
+                detail=f"{pkg} has a known {severity}-severity advisory "
+                f"({', '.join(ids[:3])}) and is imported on this path",
+            )
+        )
+
+    # 8. Supply-chain-risky dependency imported on the path (#247).
+    for pkg, severity, kinds in risk_on_path or []:
+        factors.append(
+            ExploitabilityFactor(
+                name=f"supply-chain-risky dependency on path ({pkg})",
+                points=_SUPPLY_CHAIN_ON_PATH_PTS.get(severity, 4),
+                detail=f"{pkg} carries supply-chain risk ({', '.join(k.replace('_', ' ') for k in kinds[:3])}) "
+                "and is imported on this path",
+            )
+        )
+
+    raw = sum(f.points for f in factors)
+    score = max(0, min(100, raw))
+    return ExploitabilityScore(
+        subject=f"{chain.route_method} {chain.route_path} → {chain.sink_kind}",
+        route=chain.route_path,
+        method=chain.route_method,
+        sink_kind=chain.sink_kind,
+        location=f"{chain.sink_file}:{chain.sink_line}",
+        score=score,
+        raw_score=raw,
+        tier=_tier(score),
+        factors=factors,
+    )
+
+
+def _tier(score: int) -> ExploitabilityTier:
+    for threshold, tier in _TIERS:
+        if score >= threshold:
+            return tier
+    return "low"
+
+
+def _vuln_index(scan: ScanResult) -> dict[str, tuple[str, list[str]]]:
+    """pkg-name (lowercased) → (worst severity, sorted advisory ids)."""
+    order = {"low": 0, "medium": 1, "high": 2}
+    out: dict[str, tuple[str, list[str]]] = {}
+    for v in scan.vulnerabilities:
+        key = _pep503(v.package_name) if v.ecosystem == "pypi" else v.package_name.lower()
+        sev = v.severity if v.severity in order else "medium"
+        prev = out.get(key)
+        if prev is None:
+            out[key] = (sev, [v.id])
+        else:
+            best = sev if order[sev] > order[prev[0]] else prev[0]
+            out[key] = (best, sorted({*prev[1], v.id}))
+    return out
+
+
+def _supply_chain_index(scan: ScanResult) -> dict[str, tuple[str, list[str]]]:
+    """pkg-name → (worst severity, sorted issue kinds) for package-level
+    supply-chain issues (#247), keyed like ``_vuln_index``."""
+    order = {"low": 0, "medium": 1, "high": 2}
+    out: dict[str, tuple[str, list[str]]] = {}
+    for issue in scan.supply_chain_issues:
+        if not issue.package:
+            continue
+        key = _pep503(issue.package) if issue.ecosystem == "pypi" else issue.package.lower()
+        prev = out.get(key)
+        if prev is None:
+            out[key] = (issue.severity, [issue.kind])
+        else:
+            best = issue.severity if order[issue.severity] > order[prev[0]] else prev[0]
+            out[key] = (best, sorted({*prev[1], issue.kind}))
+    return out
+
+
+def _normalize_pkg(spec: str) -> str:
+    """Reduce an import specifier to its package name: `lodash/merge` → lodash,
+    `@scope/pkg/sub` → @scope/pkg."""
+    spec = spec.strip().lower()
+    if spec.startswith("@"):
+        parts = spec.split("/")
+        return "/".join(parts[:2])
+    return spec.split("/", 1)[0]
+
+
+def _external_imports(content: str, suffix: str) -> set[str]:
+    """Bare (non-relative) package names imported by a JS/TS or Python file."""
+    pkgs: set[str] = set()
+    if suffix in JS_TS_SUFFIXES:
+        for m in _JS_IMPORT_PKG_RE.finditer(content):
+            spec = m.group("pkg")
+            if not spec.startswith("."):
+                pkgs.add(_normalize_pkg(spec))
+    elif suffix == ".py":
+        for m in _PY_IMPORT_PKG_RE.finditer(content):
+            mod = m.group("from") or m.group("mod") or ""
+            for name in mod.split(","):
+                dotted = name.split()[0].lower() if name.strip() else ""
+                top = dotted.split(".")[0]
+                if not top:  # relative import
+                    continue
+                dist = _PY_MODULE_TO_DIST.get(dotted) or _PY_MODULE_TO_DIST.get(top)
+                pkgs.add(_pep503(dist or top))
+    return pkgs
+
+
+def _pep503(name: str) -> str:
+    """PyPI name normalization: case- and `-`/`_`/`.`-insensitive."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _norm(rel: str) -> str:
+    return rel.replace("\\", "/")
+
+
+def _module(rel: str) -> str:
+    norm = _norm(rel)
+    return norm.rsplit("/", 1)[0] if "/" in norm else ""
+
+
+__all__ = ["score_exploitability", "best_by_sink_kind"]

attackmap/fingerprint.py

@@ -0,0 +1,91 @@
+"""Per-instance fingerprints for finding locations (#222).
+
+A ``Finding`` aggregates every site of one issue type, and its id hashes only
+the title, so a PR that adds a *second* command-injection route used to diff as
+"persisted" and pass ``--fail-on-new-high``. Each ``FindingLocation`` now gets
+a fingerprint that identifies that instance across runs:
+
+    sha256(rule_id | file | normalized source line | occurrence)[:16]
+
+The line *number* is deliberately excluded so unrelated edits above a site
+(line drift) don't make it look new. The source line is normalized —
+whitespace removed, string and number literals masked — so reformatting or
+changing a literal value doesn't either, while a different call or a
+different file does. Identical normalized lines in one file are told apart by
+their occurrence index, counted per rule across all findings: one rule can
+have several findings (cloud misconfigurations split by severity), and two
+of its instances on one line must not share a fingerprint.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from .models import Finding, finding_rule_id
+from .safe_fs import contained_file, is_oversized
+from .srcpaths import split_lines
+
+_STRING = re.compile(r"""(?:[rbuf]{0,2})("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`)""", re.IGNORECASE)
+_NUMBER = re.compile(r"\b\d+(?:\.\d+)?\b")
+_SPACE = re.compile(r"\s+")
+
+
+def normalize_line(line: str) -> str:
+    """Whitespace-insensitive, literal-insensitive form of a source line."""
+    text = _STRING.sub('"S"', line)
+    text = _NUMBER.sub("0", text)
+    # All whitespace goes, not just runs of it: `a + b` and `a+b` are the
+    # same code, and token boundaries don't matter for a hash.
+    return _SPACE.sub("", text)
+
+
+def _digest(*parts: str) -> str:
+    return hashlib.sha256("\x1f".join(parts).encode("utf-8")).hexdigest()[:16]
+
+
+def assign_fingerprints(findings: list[Finding], root: str | Path) -> None:
+    """Set ``fingerprint`` on every location of every finding (in place)."""
+    root_path = Path(root)
+    line_cache: dict[str, list[str] | None] = {}
+
+    def source_line(rel: str, line: int | None) -> str:
+        if line is None:
+            return ""
+        if rel not in line_cache:
+            path = contained_file(root_path, rel)
+            try:
+                line_cache[rel] = (
+                    split_lines(path.read_text(encoding="utf-8", errors="replace"))
+                    if path is not None and not is_oversized(path)
+                    else None
+                )
+            except OSError:
+                line_cache[rel] = None
+        lines = line_cache[rel]
+        if not lines or not 1 <= line <= len(lines):
+            return f"#line-unavailable:{line}"
+        return normalize_line(lines[line - 1])
+
+    # Occurrences are counted per (rule, file, line content) across every
+    # finding, not per finding. A location that was the only one of its
+    # (rule, file, content) keeps occurrence 0, so its fingerprint is
+    # unchanged.
+    seen: dict[tuple[str, str, str], int] = {}
+    for finding in findings:
+        rule = finding_rule_id(finding)
+        for loc in finding.locations:
+            file = loc.file.replace("\\", "/")
+            content = source_line(file, loc.line)
+            if loc.instance is None:
+                occurrence = seen.get((rule, file, content), 0)
+                seen[(rule, file, content)] = occurrence + 1
+                loc.fingerprint = _digest(rule, file, content, str(occurrence))
+            else:
+                # Tiered records name themselves (resource + evidence), so
+                # their fingerprint doesn't depend on same-line neighbours.
+                key = (rule, file, content, loc.instance)
+                occurrence = seen.get(key, 0)
+                seen[key] = occurrence + 1
+                loc.fingerprint = _digest(rule, file, content, loc.instance, str(occurrence))