attackmap 0.6.4__py3-none-any.whl

attackmap/fleet.py

@@ -0,0 +1,370 @@
+"""Fleet (multi-repo) container + summary rendering — cross-repo phase 1 (#146a).
+
+The lowest-blast-radius shape for cross-repo analysis (epic #150): rather than
+merge N repos into one `ScanResult` (which would force a repo id onto every
+signal model and rewrite the scanner's path relativization), each repo is
+scanned independently into its own `ScanResult` — its own root, its own
+relative paths, no collisions — and the results are collected into a `FleetScan`
+over which later phases (#146b–#146d: contract linking, cross-boundary taint,
+trust-gap) will reason.
+
+This module is deliberately pure: the CLI does the per-repo scanning (reusing
+the same building blocks a single-repo run uses) and hands the results here for
+identity assignment and summary rendering, so the logic stays unit-testable
+without a real scan. Phase 1 adds **no** cross-repo detection — it is the
+foundation the seam-analysis phases build on.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .contracts import ContractLink
+from .crossrepo import CrossBoundaryFlow, CrossRepoAnomaly, TrustGap
+from .diagrams import _mermaid_text
+from .md import md_code, md_text
+
+if TYPE_CHECKING:
+    from .models import AttackPath, Finding, ScanResult
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+_SEVERITIES = ("high", "medium", "low")
+
+
+def _slug(name: str) -> str:
+    """A filesystem- and link-safe slug for a repo directory name."""
+    s = _SLUG_RE.sub("-", name.lower()).strip("-")
+    return s or "repo"
+
+
+def fleet_repo_ids(paths: list[Path]) -> list[str]:
+    """Stable, unique per-repo identifiers derived from the directory names.
+
+    Two repos with the same basename (``a/service`` and ``b/service``) would
+    collide into one report subdirectory, so collisions are disambiguated by
+    appending ``-2``, ``-3``, … in input order. Each candidate is checked against
+    **every id already emitted** — not just a per-base counter — so a suffix that
+    coincides with a later input's own name (``api``, ``api``, ``api-2`` →
+    ``api``, ``api-2``, ``api-2-2``) still stays globally unique. Deterministic.
+    """
+    ids: list[str] = []
+    used: set[str] = set()
+    for path in paths:
+        base = _slug(path.name)
+        candidate = base
+        n = 1
+        while candidate in used:
+            n += 1
+            candidate = f"{base}-{n}"
+        used.add(candidate)
+        ids.append(candidate)
+    return ids
+
+
+@dataclass
+class FleetRepoResult:
+    """One repo's analysis within a fleet run."""
+
+    repo_id: str
+    root: str  # absolute path scanned
+    report_dir: str  # where this repo's reports were written (output/<repo_id>)
+    scan: "ScanResult"
+    findings: list["Finding"]
+    attack_paths: list["AttackPath"] = field(default_factory=list)
+    suppressed_count: int = 0
+
+    def severity_counts(self) -> dict[str, int]:
+        counts = {sev: 0 for sev in _SEVERITIES}
+        for f in self.findings:
+            if f.severity in counts:
+                counts[f.severity] += 1
+        return counts
+
+
+@dataclass
+class FleetScan:
+    """A multi-repo analysis run — the input surface for cross-repo phases."""
+
+    results: list[FleetRepoResult] = field(default_factory=list)
+    # Cross-repo client→server contract links (#146b), computed once all repos
+    # are scanned. Empty until the linker runs.
+    links: list[ContractLink] = field(default_factory=list)
+    # Cross-boundary trust flows (#146c) — confused-deputy leads over the links.
+    cross_boundary: list[CrossBoundaryFlow] = field(default_factory=list)
+    # Trust-assumption gaps + cross-repo anomalies (#146d / #149b).
+    trust_gaps: list[TrustGap] = field(default_factory=list)
+    cross_repo_anomalies: list[CrossRepoAnomaly] = field(default_factory=list)
+    # Repos whose analysis raised (#217): {repo_id, root, error}. The run keeps
+    # going without them and exits non-zero at the end.
+    failed: list[dict[str, str]] = field(default_factory=list)
+
+    @property
+    def repo_count(self) -> int:
+        return len(self.results)
+
+    def total_findings(self) -> int:
+        return sum(len(r.findings) for r in self.results)
+
+
+def _top_findings(result: FleetRepoResult, limit: int = 3) -> list["Finding"]:
+    order = {sev: i for i, sev in enumerate(_SEVERITIES)}
+    ranked = sorted(
+        result.findings,
+        key=lambda f: (order.get(f.severity, 99), -(f.score or 0), f.title),
+    )
+    return ranked[:limit]
+
+
+def render_fleet_summary(fleet: FleetScan) -> str:
+    """A Markdown fleet index: one row per repo with a severity breakdown, plus
+    each repo's top findings and a link to its per-repo report directory."""
+    lines: list[str] = ["# AttackMap fleet summary", ""]
+    lines.append(
+        f"{fleet.repo_count} repositories analyzed · "
+        f"{fleet.total_findings()} finding(s) total."
+    )
+    lines.append("")
+    if fleet.failed:
+        lines.append(f"**{len(fleet.failed)} repositor{'y' if len(fleet.failed) == 1 else 'ies'} failed and "
+                     "are not included below:**")
+        for f in fleet.failed:
+            lines.append(f"- {md_code(f['repo_id'])} — {md_text(f['error'])}")
+        lines.append("")
+    lines.append("| Repository | HIGH | MED | LOW | Total | Report |")
+    lines.append("|---|---:|---:|---:|---:|---|")
+    for r in fleet.results:
+        c = r.severity_counts()
+        total = len(r.findings)
+        lines.append(
+            f"| {md_code(r.repo_id)} | {c['high']} | {c['medium']} | {c['low']} | "
+            f"{total} | [{r.repo_id}/]({r.repo_id}/) |"
+        )
+    lines.append("")
+
+    for r in fleet.results:
+        lines.append(f"## {md_code(r.repo_id)}")
+        lines.append("")
+        lines.append(f"- Path: {md_code(r.root)}")
+        lines.append(f"- Findings: {len(r.findings)} ({r.suppressed_count} suppressed)")
+        top = _top_findings(r)
+        if top:
+            lines.append("- Top findings:")
+            for f in top:
+                lines.append(f"  - **[{f.severity.upper()}]** {md_text(f.title)}")
+        lines.append("")
+
+    lines.append("## Cross-repo links (#146b)")
+    lines.append("")
+    if fleet.links:
+        loc = lambda f, ln: md_text(f"{f}:{ln}" if ln else f)  # noqa: E731
+        lines.append(
+            f"{len(fleet.links)} client→server contract link(s) — an outbound call "
+            "in one repo matched to a route another repo serves:"
+        )
+        lines.append("")
+        lines.append("| Client | Call | → | Server | Route |")
+        lines.append("|---|---|---|---|---|")
+        for lk in fleet.links:
+            lines.append(
+                f"| {md_code(lk.client_repo)} | {md_code(f'{lk.method} {lk.client_target}')} "
+                f"[{loc(lk.client_file, lk.client_line)}] | → | {md_code(lk.server_repo)} | "
+                f"{md_code(f'{lk.method} {lk.server_route_path}')} [{loc(lk.server_file, lk.server_line)}] |"
+            )
+        lines.append("")
+    else:
+        lines.append("_No cross-repo client→server HTTP links detected._")
+        lines.append("")
+
+    lines.append("## Cross-boundary trust (#146c)")
+    lines.append("")
+    if fleet.cross_boundary:
+        loc = lambda f, ln: md_text(f"{f}:{ln}" if ln else f)  # noqa: E731
+        lines.append(
+            f"{len(fleet.cross_boundary)} SPECULATIVE confused-deputy flow(s) — a "
+            "value forwarded across a link that the callee trusts into a sink or "
+            "unguarded object access. Adjudicate before acting:"
+        )
+        lines.append("")
+        for cb in fleet.cross_boundary:
+            what = (
+                f"reaches a {md_text(cb.detail)} sink"
+                if cb.basis == "taint"
+                else f"is an unguarded {md_text(cb.detail)}"
+            )
+            lines.append(
+                f"- **[{cb.severity.upper()}, SPECULATIVE]** {md_code(cb.client_repo)} calls "
+                f"{md_code(f'{cb.method} {cb.route}')} served by {md_code(cb.server_repo)}, which {what} — "
+                f"the caller's value is trusted without the callee re-validating. "
+                f"Caller: {md_code(cb.client_target)} [{loc(cb.client_file, cb.client_line)}]; "
+                f"callee: [{loc(cb.server_file, cb.server_line)}]."
+            )
+        lines.append("")
+    else:
+        lines.append("_No cross-boundary trust flows detected._")
+        lines.append("")
+
+    loc = lambda f, ln: md_text(f"{f}:{ln}" if ln else f)  # noqa: E731
+
+    lines.append("## Trust-assumption gaps (#146d)")
+    lines.append("")
+    if fleet.trust_gaps:
+        lines.append(
+            f"{len(fleet.trust_gaps)} SPECULATIVE gap(s) — a state-changing call "
+            "crosses a link to a route the callee serves with no auth control "
+            "(if each side assumes the other enforces, nobody does):"
+        )
+        lines.append("")
+        for g in fleet.trust_gaps:
+            lines.append(
+                f"- **[{g.severity.upper()}, SPECULATIVE]** {md_code(g.client_repo)} calls "
+                f"{md_code(f'{g.method} {g.route}')} on {md_code(g.server_repo)}, which enforces no "
+                f"authentication. Caller: {md_code(g.client_target)} "
+                f"[{loc(g.client_file, g.client_line)}]; callee route: "
+                f"[{loc(g.server_file, g.server_line)}]."
+            )
+        lines.append("")
+    else:
+        lines.append("_No trust-assumption gaps detected._")
+        lines.append("")
+
+    lines.append("## Cross-repo anomalies (#149b)")
+    lines.append("")
+    if fleet.cross_repo_anomalies:
+        lines.append(
+            f"{len(fleet.cross_repo_anomalies)} SPECULATIVE outlier(s) — a service "
+            "that omits an auth control its siblings enforce on the same route:"
+        )
+        lines.append("")
+        for a in fleet.cross_repo_anomalies:
+            peers = ", ".join(md_code(p) for p in a.peers)
+            lines.append(
+                f"- **[{a.severity.upper()}, SPECULATIVE]** {md_code(a.repo)} serves "
+                f"{md_code(f'{a.method} {a.route}')} with no auth, but {peers} guard the same "
+                f"{md_code(f'/{a.template}')} route."
+            )
+        lines.append("")
+    else:
+        lines.append("_No cross-repo control anomalies detected._")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_fleet_graph_mermaid(fleet: FleetScan) -> str:
+    """A Mermaid flowchart of the fleet: one node per repo, one edge per distinct
+    client→server route link (labeled with the served contract)."""
+    lines = ["```mermaid", "flowchart LR"]
+    ids = {r.repo_id for r in fleet.results}
+    node_id = {rid: f"R{i}" for i, rid in enumerate(sorted(ids))}
+    for rid in sorted(ids):
+        lines.append(f'    {node_id[rid]}["{_mermaid_text(rid)}"]')
+    # Collapse multiple links between the same pair to one edge per route.
+    seen: set[tuple[str, str, str, str]] = set()
+    for lk in fleet.links:
+        edge = (lk.client_repo, lk.server_repo, lk.method, lk.path_template)
+        if edge in seen or lk.client_repo not in node_id or lk.server_repo not in node_id:
+            continue
+        seen.add(edge)
+        label = _mermaid_text(f"{lk.method} /{lk.path_template}")
+        lines.append(f'    {node_id[lk.client_repo]} -->|"{label}"| {node_id[lk.server_repo]}')
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def fleet_summary_json(fleet: FleetScan) -> dict:
+    """Machine-readable fleet index (for GUI / tooling front-ends)."""
+    return {
+        "repo_count": fleet.repo_count,
+        "total_findings": fleet.total_findings(),
+        "failed": list(fleet.failed),
+        "repos": [
+            {
+                "repo_id": r.repo_id,
+                "root": r.root,
+                "report_dir": r.report_dir,
+                "findings": len(r.findings),
+                "suppressed": r.suppressed_count,
+                "severity_counts": r.severity_counts(),
+            }
+            for r in fleet.results
+        ],
+        "cross_repo_links": [
+            {
+                "client_repo": lk.client_repo,
+                "server_repo": lk.server_repo,
+                "method": lk.method,
+                "path_template": lk.path_template,
+                "client_target": lk.client_target,
+                "client_location": f"{lk.client_file}:{lk.client_line}"
+                if lk.client_line
+                else lk.client_file,
+                "server_route_path": lk.server_route_path,
+                "server_location": f"{lk.server_file}:{lk.server_line}"
+                if lk.server_line
+                else lk.server_file,
+            }
+            for lk in fleet.links
+        ],
+        "cross_boundary_flows": [
+            {
+                "client_repo": cb.client_repo,
+                "server_repo": cb.server_repo,
+                "method": cb.method,
+                "route": cb.route,
+                "basis": cb.basis,
+                "detail": cb.detail,
+                "severity": cb.severity,
+                "speculative": True,
+                "client_location": f"{cb.client_file}:{cb.client_line}"
+                if cb.client_line
+                else cb.client_file,
+                "server_location": f"{cb.server_file}:{cb.server_line}"
+                if cb.server_line
+                else cb.server_file,
+            }
+            for cb in fleet.cross_boundary
+        ],
+        "trust_gaps": [
+            {
+                "client_repo": g.client_repo,
+                "server_repo": g.server_repo,
+                "method": g.method,
+                "route": g.route,
+                "severity": g.severity,
+                "speculative": True,
+                "client_location": f"{g.client_file}:{g.client_line}"
+                if g.client_line
+                else g.client_file,
+                "server_location": f"{g.server_file}:{g.server_line}"
+                if g.server_line
+                else g.server_file,
+            }
+            for g in fleet.trust_gaps
+        ],
+        "cross_repo_anomalies": [
+            {
+                "repo": a.repo,
+                "method": a.method,
+                "route": a.route,
+                "template": a.template,
+                "peers": list(a.peers),
+                "severity": a.severity,
+                "speculative": True,
+            }
+            for a in fleet.cross_repo_anomalies
+        ],
+    }
+
+
+__all__ = [
+    "FleetRepoResult",
+    "FleetScan",
+    "fleet_repo_ids",
+    "fleet_summary_json",
+    "render_fleet_graph_mermaid",
+    "render_fleet_summary",
+]

attackmap/gitref.py

@@ -0,0 +1,129 @@
+"""Read files and changed lines from a git ref (#238).
+
+Used to trust only suppressions that already exist on a reference branch (the
+PR's base): a pull request must not be able to suppress its own findings.
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import subprocess
+from pathlib import Path
+
+from .safe_fs import UnsafePathError, read_repo_text
+from .srcpaths import split_lines
+
+
+class GitRefError(RuntimeError):
+    """The ref can't be resolved, or the directory isn't a git checkout."""
+
+
+# The scanned repository is untrusted, and so is its `.git/config`: it can set
+# `core.fsmonitor`, `diff.external`, `core.pager` or textconv drivers that run
+# arbitrary commands when git reads history. Every git call AttackMap makes
+# overrides those, ignores system/global config, never prompts, and never
+# lazily fetches missing objects from a promisor remote (#252).
+_HARDENED_CONFIG = (
+    "-c", "core.fsmonitor=false",
+    "-c", "core.hooksPath=" + os.devnull,
+    "-c", "core.pager=cat",
+    "-c", "diff.external=",
+    "-c", "core.attributesFile=" + os.devnull,
+    "-c", "protocol.allow=never",
+    "-c", "core.sshCommand=false",
+)
+
+
+def hardened_git_env() -> dict[str, str]:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env.update({
+        "GIT_CONFIG_NOSYSTEM": "1",
+        "GIT_CONFIG_GLOBAL": os.devnull,
+        "GIT_TERMINAL_PROMPT": "0",
+        "GIT_NO_LAZY_FETCH": "1",
+        "GIT_PAGER": "cat",
+        "GIT_OPTIONAL_LOCKS": "0",
+    })
+    return env
+
+
+def hardened_git_command(root: Path, *args: str) -> list[str]:
+    """``git -C root <hardening> --no-pager <args>`` (see ``_HARDENED_CONFIG``)."""
+    return ["git", "-C", str(root), *_HARDENED_CONFIG, "--no-pager", *args]
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        hardened_git_command(root, *args),
+        capture_output=True,
+        text=True,
+        check=False,
+        stdin=subprocess.DEVNULL,
+        env=hardened_git_env(),
+    )
+
+
+def validate_ref(root: Path, ref: str) -> None:
+    if not ref or ref.startswith("-"):
+        raise GitRefError(f"invalid git ref {ref!r}")
+    probe = _git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    if probe.returncode != 0:
+        raise GitRefError(
+            f"git ref {ref!r} is not available in {root} (in CI, fetch the base branch first, "
+            "e.g. git fetch --depth=1 origin <base>)"
+        )
+
+
+def show_file(root: Path, ref: str, rel: str) -> str | None:
+    """Content of ``rel`` (relative to ``root``) at ``ref``; None if absent there.
+
+    `cat-file blob` returns the raw object: no textconv and no filter drivers,
+    which a hostile `.git/config` could point at arbitrary commands.
+    """
+    result = _git(root, "cat-file", "blob", f"{ref}:./{rel}")
+    if result.returncode != 0:
+        return None
+    return result.stdout
+
+
+def added_lines(root: Path, ref: str, rel: str) -> set[int]:
+    """Line numbers of ``rel`` (working tree) that are new or changed since ``ref``.
+
+    Computed in Python from the blob at ``ref`` and the working file, never by
+    `git diff <ref> -- <file>`: diffing against the working tree runs the
+    repo's `filter.<driver>.clean` commands, which `--no-textconv` and
+    `--no-ext-diff` don't disable, so a scanned repo could execute code.
+    """
+    try:
+        current = split_lines(read_repo_text(root, rel, errors="replace"))
+    except (OSError, UnsafePathError):
+        return set()
+    previous = show_file(root, ref, rel)
+    if previous is None:
+        return set(range(1, len(current) + 1))  # new since ref (or untracked)
+    matcher = difflib.SequenceMatcher(None, split_lines(previous), current, autojunk=False)
+    lines: set[int] = set()
+    for tag, _i1, _i2, j1, j2 in matcher.get_opcodes():
+        if tag in ("replace", "insert"):
+            lines.update(range(j1 + 1, j2 + 1))
+    return lines
+
+
+def untrusted_output_markers(root: Path, ref: str, *, keep_under: "list[Path] | tuple[Path, ...]" = ()) -> list[Path]:
+    """Output-marker files under ``root`` that do not exist at ``ref``, as
+    paths relative to ``root``: ones a pull request added, which must not
+    exclude their directory from the scan (GHSA-j544-8x8g-c3mw). Markers
+    anywhere under a ``keep_under`` directory (the run's own output
+    directory, which carries markers in its subdirectories too) are trusted."""
+    from .safe_fs import output_marker_files  # noqa: PLC0415 — local, so the module header is untouched
+
+    kept = [os.path.abspath(str(d)) for d in keep_under]
+    untrusted: list[Path] = []
+    for rel in output_marker_files(root):
+        marker = os.path.abspath(str(root / rel))
+        if any(marker == d or marker.startswith(d + os.sep) for d in kept):
+            continue
+        if show_file(root, ref, rel.as_posix()) is None:
+            untrusted.append(rel)
+    return untrusted

attackmap/graph.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import networkx as nx
+
+from .models import ScanResult
+
+
+def build_graph(scan: ScanResult) -> nx.DiGraph:
+    graph = nx.DiGraph()
+
+    graph.add_node("repo", kind="system", label="Repository")
+
+    if scan.routes:
+        graph.add_node("web", kind="service", label="Web/API Layer")
+        graph.add_edge("repo", "web", relation="contains")
+
+    for db in sorted({d.kind for d in scan.databases}):
+        graph.add_node(db, kind="database", label=db)
+        graph.add_edge("web" if scan.routes else "repo", db, relation="uses")
+
+    for idx, call in enumerate(scan.external_calls, start=1):
+        node_id = f"external_{idx}"
+        graph.add_node(node_id, kind="external", label=call.target)
+        graph.add_edge("web" if scan.routes else "repo", node_id, relation="calls")
+
+    return graph