hackscan 0.1.0__py3-none-any.whl

hackscan/cli.py

@@ -0,0 +1,326 @@
+"""Command-line interface.
+
+Exit codes: 0 = no failing findings, 1 = `--fail-on` threshold hit,
+2 = usage, configuration or plugin error, an incomplete scan (a file could not be
+analyzed, unless `--allow-incomplete`), or (with `--strict-tools`) an external tool error.
+An incomplete scan takes precedence over findings: its results cannot be trusted to be
+complete, so it must not look like a pass or an ordinary failure.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from hackscan import __version__
+from hackscan.config import ConfigError, HackScanConfig, load, parse_import_format, parse_tools
+from hackscan.core.models import OWN_SOURCE, Finding, Severity, Status
+from hackscan.core.pipeline import ScanResult, scan
+from hackscan.plugins.loader import PluginError, resolve_plugins
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+SEVERITIES = [s.value for s in Severity]
+TOOL_FAILURES = {"missing", "failed", "timeout", "partial"}
+REPORT_SIGNATURES = ('"name": "HackScan"', '"name": "hackscan"', "HackScan ")
+
+
+@click.group()
+@click.version_option(__version__, prog_name="hackscan")
+def main() -> None:
+    """HackScan: Python SAST orchestrator and verifier."""
+
+
+@main.command("scan")
+@click.argument("path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--format", "fmt", type=click.Choice(["text", "json", "sarif"]), default="text")
+@click.option("-o", "--output", type=click.Path(dir_okay=False, path_type=Path))
+@click.option("--severity", type=click.Choice(SEVERITIES), help="Minimum severity to report.")
+@click.option("--min-confidence", type=click.IntRange(0, 100), help="Minimum confidence.")
+@click.option(
+    "--fail-on",
+    type=click.Choice(SEVERITIES),
+    help="Exit 1 if an open finding is at least this severe.",
+)
+@click.option("--ignore", multiple=True, help="Glob of paths to skip (repeatable).")
+@click.option("--show-suppressed", is_flag=True, default=None, help="Include suppressed findings.")
+@click.option(
+    "--plugins",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Directory of custom rule plugins.",
+)
+@click.option("--with", "with_tools", help="Run external tools: semgrep,bandit,gitleaks.")
+@click.option(
+    "--import",
+    "imports",
+    multiple=True,
+    metavar="FORMAT=FILE",
+    help="Import a report: sarif|semgrep|bandit|codeql|gitleaks=FILE (repeatable).",
+)
+@click.option("--tool-timeout", type=click.IntRange(0), help="Seconds per tool (0 = none).")
+@click.option(
+    "--strict-tools", is_flag=True, default=None, help="Exit 2 if an external tool fails."
+)
+@click.option(
+    "--sarif-omit-suppressed",
+    is_flag=True,
+    default=False,
+    help="Leave suppressed findings out of SARIF (recommended for GitHub uploads).",
+)
+@click.option(
+    "--allow-incomplete",
+    is_flag=True,
+    default=None,
+    help="Do not exit 2 when some files cannot be analyzed (they are still reported).",
+)
+@click.option("--no-taint", is_flag=True, default=False, help="Skip the taint pass.")
+@click.option("--jobs", type=click.IntRange(0), help="Worker processes (0 = automatic).")
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Use this config file instead of discovering .hackscan.yml.",
+)
+@click.option("-q", "--quiet", is_flag=True, help="Only print findings (no header/summary).")
+def scan_command(
+    path: Path,
+    fmt: str,
+    output: Path | None,
+    quiet: bool,
+    config_path: Path | None,
+    no_taint: bool,
+    with_tools: str | None,
+    imports: tuple[str, ...],
+    sarif_omit_suppressed: bool,
+    **options,
+) -> None:
+    """Scan PATH (a directory or a Python file) for vulnerabilities."""
+    if output is not None:
+        _check_output(output, path)
+    try:
+        config = load(path, config_path).with_overrides(
+            severity=Severity(options["severity"]) if options["severity"] else None,
+            fail_on=Severity(options["fail_on"]) if options["fail_on"] else None,
+            min_confidence=options["min_confidence"],
+            ignore=tuple(options["ignore"]) or None,
+            show_suppressed=options["show_suppressed"],
+            plugins=options["plugins"].resolve() if options["plugins"] else None,
+            tool_timeout=options["tool_timeout"],
+            strict_tools=options["strict_tools"],
+            allow_incomplete=options["allow_incomplete"],
+            jobs=options["jobs"],
+            taint=False if no_taint else None,
+            with_tools=parse_tools(with_tools, click.BadParameter) if with_tools else None,
+            imports=_parse_imports(imports) if imports else None,
+        )
+        result = scan(path, config)
+        plugins = resolve_plugins(config.plugins)
+    except (ConfigError, PluginError, click.BadParameter) as exc:
+        click.echo(f"hackscan: error: {exc}", err=True)
+        sys.exit(EXIT_ERROR)
+
+    if fmt == "sarif":
+        from hackscan.sarif.generator import export_sarif
+
+        shown = _visible(result.findings, config, include_suppressed=True)
+        log = export_sarif(_with(result, shown), plugins, omit_suppressed=sarif_omit_suppressed)
+        text = json.dumps(log, indent=2)
+    elif fmt == "json":
+        shown = _visible(result.findings, config, config.show_suppressed)
+        text = json.dumps(_json(result, shown), indent=2)
+    else:
+        shown = _visible(result.findings, config, config.show_suppressed)
+        text = _text(result, shown, config, quiet)
+
+    if output is not None:
+        try:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(text + "\n", encoding="utf-8")
+        except OSError as exc:
+            click.echo(f"hackscan: error: cannot write {output}: {exc}", err=True)
+            sys.exit(EXIT_ERROR)
+        if not quiet:
+            click.echo(f"hackscan: wrote {fmt} report to {output}", err=True)
+    else:
+        click.echo(text)
+
+    if result.errors and not config.allow_incomplete:
+        click.echo(
+            f"hackscan: error: scan incomplete, {len(result.errors)} file(s) or report(s) "
+            "could not be analyzed (see errors above; --allow-incomplete to accept)",
+            err=True,
+        )
+        sys.exit(EXIT_ERROR)
+    if config.strict_tools and any(r.status in TOOL_FAILURES for r in result.tool_runs):
+        click.echo("hackscan: error: an external tool failed (--strict-tools)", err=True)
+        sys.exit(EXIT_ERROR)
+    if config.fail_on is not None and _failing(result.findings, config):
+        sys.exit(EXIT_FINDINGS)
+    sys.exit(EXIT_OK)
+
+
+@main.command("rules")
+@click.option("--plugins", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def rules_command(plugins: Path | None) -> None:
+    """List the detection rules."""
+    try:
+        loaded = resolve_plugins(plugins)
+    except PluginError as exc:
+        click.echo(f"hackscan: error: {exc}", err=True)
+        sys.exit(EXIT_ERROR)
+    for p in loaded:
+        cwe = ", ".join(p.cwe) or "-"
+        click.echo(f"{p.rule_id:<16} {p.severity.value:<8} {cwe:<10} {p.description}")
+
+
+# -- helpers ------------------------------------------------------------------------------
+
+
+def _check_output(output: Path, target: Path) -> None:
+    """A report never overwrites anything but a previous HackScan report.
+
+    New files are fine unless they would be Python source; an existing file is only
+    replaced if it already is a HackScan report (text, JSON or SARIF), so `-o
+    pyproject.toml` or `-o app.py` cannot destroy project files.
+    """
+    resolved = output.resolve()
+    refuse = resolved.suffix in {".py", ".pyw", ".pyi"} or resolved == target.resolve()
+    if not refuse and resolved.exists():
+        refuse = resolved.is_dir() or not _is_hackscan_report(resolved)
+    if refuse:
+        click.echo(
+            f"hackscan: error: refusing to write the report to {output} "
+            "(existing file is not a HackScan report)",
+            err=True,
+        )
+        sys.exit(EXIT_ERROR)
+
+
+def _is_hackscan_report(path: Path) -> bool:
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            head = fh.read(4096)
+    except OSError:
+        return False
+    return head.startswith("HackScan ") or any(sig in head for sig in REPORT_SIGNATURES[:2])
+
+
+def _parse_imports(values: tuple[str, ...]) -> tuple[tuple[str, Path], ...]:
+    out = []
+    for value in values:
+        fmt, sep, file = value.partition("=")
+        if not sep or not file:
+            raise click.BadParameter(f"--import expects FORMAT=FILE, got {value!r}")
+        report = Path(file)
+        if not report.is_file():
+            raise click.BadParameter(f"--import report not found: {file}")
+        out.append((parse_import_format(fmt, click.BadParameter), report.resolve()))
+    return tuple(out)
+
+
+def _visible(
+    findings: list[Finding], config: HackScanConfig, include_suppressed: bool
+) -> list[Finding]:
+    return [
+        f
+        for f in findings
+        if f.severity.rank >= config.severity.rank
+        and f.confidence >= config.min_confidence
+        and (include_suppressed or f.status is not Status.SUPPRESSED)
+    ]
+
+
+def _failing(findings: list[Finding], config: HackScanConfig) -> list[Finding]:
+    """Open (candidate/confirmed) findings at or above --fail-on; suppressed never count."""
+    assert config.fail_on is not None
+    return [
+        f
+        for f in findings
+        if f.status is not Status.SUPPRESSED
+        and f.severity.rank >= config.fail_on.rank
+        and f.confidence >= config.min_confidence
+    ]
+
+
+def _with(result: ScanResult, findings: list[Finding]) -> ScanResult:
+    return ScanResult(
+        root=result.root,
+        findings=findings,
+        files_scanned=result.files_scanned,
+        duration_seconds=result.duration_seconds,
+        errors=result.errors,
+        warnings=result.warnings,
+        tool_runs=result.tool_runs,
+    )
+
+
+def _json(result: ScanResult, findings: list[Finding]) -> dict:
+    return {
+        "tool": {"name": "hackscan", "version": __version__},
+        "root": result.root.as_posix(),
+        "stats": {
+            "files_scanned": result.files_scanned,
+            "duration_seconds": round(result.duration_seconds, 3),
+            "findings": len(findings),
+            "by_status": {s.value: sum(f.status is s for f in findings) for s in Status},
+        },
+        "findings": [f.to_dict() for f in findings],
+        "errors": result.errors,
+        "warnings": result.warnings,
+        "tool_runs": [vars(r) for r in result.tool_runs],
+    }
+
+
+def _text(result: ScanResult, findings: list[Finding], config: HackScanConfig, quiet: bool) -> str:
+    lines: list[str] = []
+    if not quiet:
+        lines.append(
+            f"HackScan {__version__} - scanned {result.files_scanned} files "
+            f"in {result.duration_seconds:.2f}s"
+        )
+        lines.append("")
+    ordered = sorted(
+        findings,
+        key=lambda f: (-f.severity.rank, f.status is not Status.CONFIRMED, f.sort_key()),
+    )
+    for f in ordered:
+        loc = f"{f.location.path}:{f.location.start_line}:{f.location.start_column}"
+        status = f.status.value
+        if f.status is Status.SUPPRESSED:
+            status = f"suppressed ({f.suppression})"
+        lines.append(
+            f"{f.severity.value.upper():<8} {status:<10} {loc}  {f.rule_id}  [{f.confidence}%]"
+        )
+        lines.append(f"    {f.message}")
+        if f.snippet:
+            lines.append(f"    | {f.snippet.splitlines()[0].strip()}")
+        lines.extend(
+            f"    > {e.message}" for e in f.evidence if e.kind in {"taint_step", "taint_verdict"}
+        )
+        if f.sources != (OWN_SOURCE,):
+            lines.append(f"    sources: {', '.join(f.sources)}")
+    if quiet:
+        return "\n".join(lines)
+    counts = {s: sum(f.status is s for f in findings) for s in Status}
+    hidden = sum(f.status is Status.SUPPRESSED for f in result.findings) - counts[Status.SUPPRESSED]
+    if not findings:
+        lines.append("No findings.")
+    lines.append("")
+    summary = (
+        f"Summary: {counts[Status.CONFIRMED]} confirmed, {counts[Status.CANDIDATE]} candidates"
+    )
+    if counts[Status.SUPPRESSED]:
+        summary += f", {counts[Status.SUPPRESSED]} suppressed shown"
+    if hidden:
+        summary += f", {hidden} suppressed hidden (--show-suppressed)"
+    lines.append(summary)
+    if result.errors:
+        lines.append(f"INCOMPLETE: {len(result.errors)} file(s) could not be analyzed")
+    lines.extend(f"error: {e}" for e in result.errors)
+    lines.extend(f"warning: {w}" for w in result.warnings)
+    if config.fail_on is not None:
+        failing = len(_failing(result.findings, config))
+        lines.append(f"fail-on {config.fail_on.value}: {failing} open finding(s) at or above")
+    return "\n".join(lines)

hackscan/config.py

@@ -0,0 +1,184 @@
+"""Configuration: `.hackscan.yml` discovery, validation and CLI overrides.
+
+Discovery is hierarchical: every `.hackscan.yml` from the filesystem root down to the
+scan root is loaded and merged, nearer files overriding farther ones (lists such as
+`ignore` are concatenated). CLI options override the merged file configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from hackscan.core.models import Severity
+
+CONFIG_NAME = ".hackscan.yml"
+# Keys accepted in .hackscan.yml (and only these: anything else is an error, so a typo
+# never silently disables a setting).
+CONFIG_KEYS = frozenset(
+    {
+        "ignore",
+        "severity",
+        "min-confidence",
+        "fail-on",
+        "show-suppressed",
+        "plugins",
+        "taint",
+        "with",
+        "import",
+        "tool-timeout",
+        "strict-tools",
+        "allow-incomplete",
+        "jobs",
+    }
+)
+
+DEFAULT_IGNORES = (
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    ".tox",
+    ".nox",
+    "node_modules",
+    "build",
+    "dist",
+    "site-packages",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".eggs",
+    "*.egg-info",
+)
+
+KNOWN_TOOLS = ("semgrep", "bandit", "gitleaks")
+IMPORT_FORMATS = ("sarif", "semgrep", "bandit", "codeql", "gitleaks")
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class HackScanConfig:
+    ignore: tuple[str, ...] = ()
+    severity: Severity = Severity.LOW  # minimum severity reported
+    min_confidence: int = 0
+    fail_on: Severity | None = None
+    show_suppressed: bool = False
+    plugins: Path | None = None
+    taint: bool = True
+    with_tools: tuple[str, ...] = ()
+    imports: tuple[tuple[str, Path], ...] = ()  # (format, report file)
+    tool_timeout: int = 300
+    strict_tools: bool = False
+    allow_incomplete: bool = False  # files that cannot be analyzed do not fail the run
+    jobs: int = 0  # 0 = automatic
+    sources: tuple[Path, ...] = field(default=(), compare=False)  # config files loaded
+
+    def with_overrides(self, **overrides: Any) -> HackScanConfig:
+        """Apply CLI overrides; `None` means "not given". `ignore` is appended."""
+        values = {k: v for k, v in overrides.items() if v is not None}
+        if "ignore" in values:
+            values["ignore"] = (*self.ignore, *values["ignore"])
+        return replace(self, **values)
+
+
+def discover(scan_root: Path) -> list[Path]:
+    """Config files from the filesystem root down to `scan_root` (nearest last)."""
+    start = scan_root if scan_root.is_dir() else scan_root.parent
+    found = [d / CONFIG_NAME for d in [start.resolve(), *start.resolve().parents]]
+    return [p for p in reversed(found) if p.is_file()]
+
+
+def load(scan_root: Path, explicit: Path | None = None) -> HackScanConfig:
+    paths = [explicit] if explicit is not None else discover(scan_root)
+    config = HackScanConfig()
+    for path in paths:
+        config = _merge(config, _parse(path), path)
+    return config
+
+
+def _parse(path: Path) -> dict[str, Any]:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError) as exc:
+        raise ConfigError(f"{path}: cannot read config: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: top level must be a mapping")
+    unknown = sorted(set(data) - CONFIG_KEYS)
+    if unknown:
+        raise ConfigError(f"{path}: unknown option(s): {', '.join(unknown)}")
+    return data
+
+
+def _merge(config: HackScanConfig, data: dict[str, Any], path: Path) -> HackScanConfig:
+    def err(message: str) -> ConfigError:
+        return ConfigError(f"{path}: {message}")
+
+    values: dict[str, Any] = {}
+    if "ignore" in data:
+        ignore = data["ignore"]
+        if not isinstance(ignore, list) or not all(isinstance(i, str) for i in ignore):
+            raise err("`ignore` must be a list of glob strings")
+        values["ignore"] = (*config.ignore, *ignore)
+    for key in ("severity", "fail-on"):
+        if key in data:
+            try:
+                values[key.replace("-", "_")] = Severity(str(data[key]).lower())
+            except ValueError:
+                options = ", ".join(s.value for s in Severity)
+                raise err(f"`{key}` must be one of: {options}") from None
+    if "min-confidence" in data:
+        value = data["min-confidence"]
+        if not isinstance(value, int) or not 0 <= value <= 100:
+            raise err("`min-confidence` must be an integer 0-100")
+        values["min_confidence"] = value
+    for key in ("show-suppressed", "taint", "strict-tools", "allow-incomplete"):
+        if key in data:
+            if not isinstance(data[key], bool):
+                raise err(f"`{key}` must be true or false")
+            values[key.replace("-", "_")] = data[key]
+    for key in ("tool-timeout", "jobs"):
+        if key in data:
+            if not isinstance(data[key], int) or data[key] < 0:
+                raise err(f"`{key}` must be a non-negative integer")
+            values[key.replace("-", "_")] = data[key]
+    if "plugins" in data:
+        values["plugins"] = (path.parent / str(data["plugins"])).resolve()
+    if "with" in data:
+        values["with_tools"] = parse_tools(data["with"], err)
+    if "import" in data:
+        items = data["import"]
+        if not isinstance(items, dict):
+            raise err("`import` must map format to report path, e.g. {codeql: results.sarif}")
+        values["imports"] = tuple(
+            (parse_import_format(fmt, err), (path.parent / str(p)).resolve())
+            for fmt, p in items.items()
+        )
+    return replace(config, sources=(*config.sources, path), **values)
+
+
+def parse_tools(value: Any, err=ConfigError) -> tuple[str, ...]:
+    items = value.split(",") if isinstance(value, str) else value
+    if not isinstance(items, (list, tuple)):
+        raise err("`with` must be a list or comma-separated string of tools")
+    tools = tuple(dict.fromkeys(str(t).strip().lower() for t in items if str(t).strip()))
+    unknown = [t for t in tools if t not in KNOWN_TOOLS]
+    if unknown:
+        raise err(f"unknown tool(s) {', '.join(unknown)}; supported: {', '.join(KNOWN_TOOLS)}")
+    return tools
+
+
+def parse_import_format(value: Any, err=ConfigError) -> str:
+    fmt = str(value).strip().lower()
+    if fmt not in IMPORT_FORMATS:
+        raise err(f"unknown import format {fmt!r}; supported: {', '.join(IMPORT_FORMATS)}")
+    return fmt

hackscan/core/__init__.py

@@ -0,0 +1 @@
+"""Core data model, taxonomy, fingerprinting and dedupe."""

hackscan/core/dedupe.py

@@ -0,0 +1,147 @@
+"""Cross-source dedupe with a deterministic, order-independent merge policy.
+
+Pipeline order: collect (own engine + importers) -> `merge_findings` -> `assign_ids`.
+
+Clustering is not transitive. Invariant: every pair of findings in a cluster overlaps.
+Findings are visited from most to least precise (smallest region first, own engine breaks
+ties) and each joins the first cluster in which it overlaps *every* member; otherwise it
+starts a new cluster. Two findings that do not overlap each other (distinct sinks) can
+therefore never be fused, whatever a third, broader report covers.
+
+Overlap alone is not identity: nested sinks such as `eval(eval(x))` overlap. Two findings
+that share a source but record different sinks are distinct reports from the same producer
+and never merge, so a merge never reports fewer findings than any single source did.
+
+A finding may join a cluster only when it shares `vuln_class` and path with its members,
+their regions overlap (column-aware), and both identities are grounded
+(see `taxonomy.is_mergeable_class`).
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import replace
+
+from hackscan.core.fingerprint import normalize_expression, sink_text
+from hackscan.core.models import OWN_SOURCE, Finding, Region, Status
+from hackscan.core.taxonomy import is_mergeable_class, normalize_cwes
+
+
+def merge_findings(findings: Iterable[Finding]) -> list[Finding]:
+    """Merge duplicates across sources. Output is sorted by `Finding.sort_key`."""
+    buckets: dict[tuple[str, str], list[Finding]] = defaultdict(list)
+    singles: list[Finding] = []
+    for f in findings:
+        if is_mergeable_class(f.vuln_class, f.cwe):
+            buckets[(f.vuln_class, f.location.path)].append(f)
+        else:
+            singles.append(f)
+
+    merged: list[Finding] = list(singles)
+    for members in buckets.values():
+        for cluster in _anchor_clusters(members):
+            merged.append(_merge_cluster(cluster) if len(cluster) > 1 else cluster[0])
+    merged.sort(key=Finding.sort_key)
+    return merged
+
+
+def _precision_key(f: Finding) -> tuple:
+    """Total order: most precise region first; own engine breaks ties, then full content.
+
+    Precision must come first: a broad anchor would absorb separate sinks it spans.
+    """
+    return (
+        f.location.span,
+        f.location.start_pos,
+        OWN_SOURCE not in f.sources,
+        f.canonical_json(),
+    )
+
+
+def _anchor_clusters(members: list[Finding]) -> list[list[Finding]]:
+    clusters: list[list[Finding]] = []
+    for f in sorted(members, key=_precision_key):
+        for cluster in clusters:
+            if all(_compatible(m, f) for m in cluster):
+                cluster.append(f)
+                break
+        else:
+            clusters.append([f])
+    return clusters
+
+
+def _compatible(a: Finding, b: Finding) -> bool:
+    if not a.location.overlaps(b.location):
+        return False
+    if set(a.sources) & set(b.sources):
+        return normalize_expression(sink_text(a)) == normalize_expression(sink_text(b))
+    return True
+
+
+def _primary(cluster: list[Finding]) -> Finding:
+    """Own-engine finding wins; otherwise the lexicographically smallest rule id."""
+    own = [f for f in cluster if OWN_SOURCE in f.sources]
+    pool = own or cluster
+    return min(pool, key=lambda f: (f.rule_id, f.canonical_json()))
+
+
+def _merge_cluster(cluster: list[Finding]) -> Finding:
+    primary = _primary(cluster)
+    ordered = sorted(cluster, key=lambda f: f.canonical_json())
+    status = max((f.status for f in cluster), key=lambda s: s.rank)
+    suppression = None
+    if status is Status.SUPPRESSED:
+        suppression = ";".join(sorted({f.suppression for f in cluster if f.suppression}))
+
+    rules = {f.rule_id for f in cluster} | {r for f in cluster for r in f.related_rules}
+    rules.discard(primary.rule_id)
+
+    # Concatenation (duplicates kept: each contributor's evidence stands on its own).
+    evidence = sorted(
+        (e for f in cluster for e in f.evidence),
+        key=lambda e: (e.producer, e.kind, e.message, e.region.sort_key() if e.region else ()),
+    )
+    fix = primary.fix or next((f.fix for f in ordered if f.fix is not None), None)
+    sink = primary.sink or next((f.sink for f in _by_precedence(cluster) if f.sink), "")
+    function = primary.function or next(
+        (f.function for f in _by_precedence(cluster) if f.function), None
+    )
+
+    return replace(
+        primary,
+        location=_union(f.location for f in cluster),
+        severity=max((f.severity for f in cluster), key=lambda s: s.rank),
+        confidence=max(f.confidence for f in cluster),
+        status=status,
+        suppression=suppression,
+        sources=tuple(sorted({s for f in cluster for s in f.sources})),
+        related_rules=tuple(sorted(rules)),
+        cwe=normalize_cwes(c for f in cluster for c in f.cwe),
+        evidence=tuple(evidence),
+        fix=fix,
+        sink=sink,
+        function=function,
+    )
+
+
+def _by_precedence(cluster: list[Finding]) -> list[Finding]:
+    """Own-engine contributors first, then by rule id and content."""
+    return sorted(
+        cluster, key=lambda f: (OWN_SOURCE not in f.sources, f.rule_id, f.canonical_json())
+    )
+
+
+def _union(regions: Iterable[Region]) -> Region:
+    """Smallest region covering every contributor (using effective, exclusive ends)."""
+    regions = list(regions)
+    start_line, start_column = min(r.start_pos for r in regions)
+    end_line, end_column = max(r.end_pos for r in regions)
+    return Region(
+        path=regions[0].path,
+        start_line=start_line,
+        start_column=int(start_column),
+        end_line=end_line,
+        end_column=None if end_column == math.inf else int(end_column),
+    )