torusguard 2.0.0-alpha → 2.1.1

package/.torusguard/core/bundle.py

@@ -0,0 +1,141 @@
+"""
+TorusGuard v6 Remediation Bundle Generator
+Constructs self-contained, structured remediation packages per cluster or finding containing:
+- finding.md
+- remediation.md
+- minimal_patch_plan.md
+- verify-after-change.md
+- metadata.json
+"""
+
+import json
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+from typing import Dict, Any, List, Optional
+
+
+@dataclass
+class RemediationBundle:
+    bundle_id: str
+    finding_id: str
+    rule_id: str
+    title: str
+    target_files: List[str]
+    risk_severity: str
+    what_is_wrong: str
+    why_it_matters: str
+    what_should_change: str
+    proposed_diff: str
+    verification_steps: str
+    cluster_id: Optional[str] = None
+    created_at: str = ""
+
+    def write_to_directory(self, base_dir: Path) -> Path:
+        bundle_dir = base_dir / self.bundle_id
+        bundle_dir.mkdir(parents=True, exist_ok=True)
+
+        # 1. finding.md
+        with open(bundle_dir / "finding.md", "w", encoding="utf-8") as f:
+            f.write(f"# Finding: {self.title}\n\n")
+            f.write(f"- **Finding ID:** `{self.finding_id}`\n")
+            f.write(f"- **Rule ID:** `{self.rule_id}`\n")
+            f.write(f"- **Severity:** {self.risk_severity}\n")
+            if self.cluster_id:
+                f.write(f"- **Root-Cause Cluster:** `{self.cluster_id}`\n")
+            f.write(f"- **Target Files:** {', '.join(f'`{tf}`' for tf in self.target_files)}\n\n")
+            f.write("## What Is Wrong\n")
+            f.write(f"{self.what_is_wrong}\n\n")
+            f.write("## Why It Matters\n")
+            f.write(f"{self.why_it_matters}\n")
+
+        # 2. remediation.md
+        with open(bundle_dir / "remediation.md", "w", encoding="utf-8") as f:
+            f.write(f"# Remediation Guide: {self.title}\n\n")
+            f.write("## What Should Change\n")
+            f.write(f"{self.what_should_change}\n\n")
+            f.write("## Target Files to Modify\n")
+            for tf in self.target_files:
+                f.write(f"- `{tf}`\n")
+
+        # 3. minimal_patch_plan.md
+        with open(bundle_dir / "minimal_patch_plan.md", "w", encoding="utf-8") as f:
+            f.write(f"# Minimal Patch Plan for `{self.finding_id}`\n\n")
+            f.write("```diff\n")
+            f.write(self.proposed_diff.strip() + "\n")
+            f.write("```\n")
+
+        # 4. verify-after-change.md
+        with open(bundle_dir / "verify-after-change.md", "w", encoding="utf-8") as f:
+            f.write(f"# Verification Steps for `{self.finding_id}`\n\n")
+            f.write(f"{self.verification_steps}\n\n")
+            f.write("### Recheck Command\n")
+            f.write("```bash\n/torusguard recheck\n```\n")
+
+        # 5. metadata.json
+        meta = {
+            "bundle_id": self.bundle_id,
+            "finding_id": self.finding_id,
+            "rule_id": self.rule_id,
+            "title": self.title,
+            "cluster_id": self.cluster_id,
+            "target_files": self.target_files,
+            "risk_severity": self.risk_severity,
+            "created_at": self.created_at,
+        }
+        with open(bundle_dir / "metadata.json", "w", encoding="utf-8") as f:
+            json.dump(meta, f, indent=2)
+
+        return bundle_dir
+
+
+class BundleManager:
+    """
+    Factory for generating remediation bundles from findings and clusters.
+    """
+
+    @staticmethod
+    def create_bundle(finding: Dict[str, Any], cluster_id: Optional[str] = None) -> RemediationBundle:
+        f_id = finding.get("finding_id", "fnd-01")
+        rule_id = finding.get("rule_id", "TG-GENERIC")
+        title = finding.get("title", "Security Finding")
+        target = finding.get("target", {})
+        file_path = target.get("file_path", "app.py")
+        severity = finding.get("severity", "High")
+
+        bundle_id = f"bundle-{f_id}"
+
+        what_is_wrong = finding.get(
+            "what_is_wrong",
+            f"The component in `{file_path}` violates security rule `{rule_id}`."
+        )
+        why_it_matters = finding.get(
+            "why_it_matters",
+            "This vulnerability could allow attackers to bypass authorization, access unauthorized tenant data, or inject malicious payloads."
+        )
+        what_should_change = finding.get(
+            "what_should_change",
+            f"Apply least-invasive framework-idiomatic hardening to `{file_path}`."
+        )
+        proposed_diff = finding.get(
+            "proposed_diff",
+            f"--- a/{file_path}\n+++ b/{file_path}\n@@ -1,3 +1,3 @@\n-# Unsafe pattern\n+# Hardened pattern\n"
+        )
+        verification_steps = finding.get(
+            "verification_steps",
+            f"Run `/torusguard recheck` on `{file_path}` to confirm vulnerability resolution."
+        )
+
+        return RemediationBundle(
+            bundle_id=bundle_id,
+            finding_id=f_id,
+            rule_id=rule_id,
+            title=title,
+            target_files=[file_path],
+            risk_severity=severity,
+            what_is_wrong=what_is_wrong,
+            why_it_matters=why_it_matters,
+            what_should_change=what_should_change,
+            proposed_diff=proposed_diff,
+            verification_steps=verification_steps,
+            cluster_id=cluster_id,
+        )

package/.torusguard/core/call_graph.py

@@ -0,0 +1,184 @@
+"""
+TorusGuard Project-Wide Call Graph Engine
+Maps interprocedural call sites, function definitions, and caller/callee relationships
+across module boundaries.
+"""
+
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Set, Any
+import re
+
+from core.parser import PolyglotParser, ParseResult
+from core.import_resolver import ImportResolver
+
+
+@dataclass
+class CallSite:
+    caller_file: str
+    caller_func: str
+    caller_line: int
+    callee_name: str
+    callee_file: Optional[str] = None
+    callee_line: Optional[int] = None
+    arguments: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class FunctionDef:
+    file_path: str
+    func_name: str
+    start_line: int
+    end_line: int = 0
+    parameters: List[str] = field(default_factory=list)
+    return_expressions: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class CallGraph:
+    """Project-wide interprocedural function call graph."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root.resolve()
+        self.import_resolver = ImportResolver(self.project_root)
+        # Key: (file_path, func_name) -> FunctionDef
+        self.functions: Dict[Tuple[str, str], FunctionDef] = {}
+        # Key: func_name -> list of FunctionDef (for quick symbol lookup)
+        self.functions_by_name: Dict[str, List[FunctionDef]] = {}
+        # Key: (file_path, func_name) -> list of CallSite where this func is caller
+        self.callees: Dict[Tuple[str, str], List[CallSite]] = {}
+        # Key: (file_path, func_name) -> list of CallSite where this func is callee
+        self.callers: Dict[Tuple[str, str], List[CallSite]] = {}
+
+    def register_function(self, fdef: FunctionDef) -> None:
+        key = (fdef.file_path, fdef.func_name)
+        self.functions[key] = fdef
+        if fdef.func_name not in self.functions_by_name:
+            self.functions_by_name[fdef.func_name] = []
+        self.functions_by_name[fdef.func_name].append(fdef)
+
+    def add_call(self, call: CallSite) -> None:
+        caller_key = (call.caller_file, call.caller_func)
+        if caller_key not in self.callees:
+            self.callees[caller_key] = []
+        self.callees[caller_key].append(call)
+
+        if call.callee_file:
+            callee_key = (call.callee_file, call.callee_name)
+            if callee_key not in self.callers:
+                self.callers[callee_key] = []
+            self.callers[callee_key].append(call)
+
+    def build_from_files(self, file_paths: List[Path], parser: PolyglotParser) -> None:
+        """Parse files and construct functions and call edges."""
+        parsed_results: Dict[str, ParseResult] = {}
+
+        # Pass 1: Extract all function definitions
+        for p in file_paths:
+            try:
+                res = parser.parse_file(p)
+                rel_p = str(p.resolve().relative_to(self.project_root)).replace("\\", "/")
+                parsed_results[rel_p] = res
+                self._extract_function_defs(rel_p, res.raw_content, res.language)
+            except Exception:
+                continue
+
+        # Pass 2: Extract call sites and link to callees
+        for rel_p, res in parsed_results.items():
+            abs_p = self.project_root / rel_p
+            # Build import map: alias/name -> resolved Path
+            resolved_imports: Dict[str, str] = {}
+            for imp in res.imports:
+                target_p = self.import_resolver.resolve(abs_p, imp.module)
+                if target_p:
+                    rel_target = str(target_p.resolve().relative_to(self.project_root)).replace("\\", "/")
+                    for name in imp.imported_names:
+                        resolved_imports[name] = rel_target
+                    for alias, orig in imp.alias_map.items():
+                        resolved_imports[alias] = rel_target
+
+            # Process function calls
+            for fc in res.function_calls:
+                callee_name = fc.name
+                callee_file = None
+                callee_line = None
+
+                # Method call e.g. mod.func
+                if "." in callee_name:
+                    prefix, actual_name = callee_name.split(".", 1)
+                    if prefix in resolved_imports:
+                        callee_file = resolved_imports[prefix]
+                        callee_name = actual_name
+                elif callee_name in resolved_imports:
+                    callee_file = resolved_imports[callee_name]
+                else:
+                    # Check local in same file
+                    if (rel_p, callee_name) in self.functions:
+                        callee_file = rel_p
+
+                # Find which enclosing function contains this call
+                caller_func = self._find_enclosing_function(rel_p, fc.line_number)
+
+                call_site = CallSite(
+                    caller_file=rel_p,
+                    caller_func=caller_func,
+                    caller_line=fc.line_number,
+                    callee_name=callee_name,
+                    callee_file=callee_file,
+                    arguments=fc.arguments
+                )
+                self.add_call(call_site)
+
+    def _extract_function_defs(self, file_path: str, content: str, language: str) -> None:
+        lines = content.splitlines()
+        for idx, line in enumerate(lines):
+            line_num = idx + 1
+            stripped = line.strip()
+
+            # Python: def foo(a, b):
+            py_m = re.match(r"^def\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*?)\)", stripped)
+            if py_m:
+                fname = py_m.group(1)
+                params = [p.strip() for p in py_m.group(2).split(",") if p.strip()]
+                self.register_function(FunctionDef(file_path=file_path, func_name=fname, start_line=line_num, parameters=params))
+                continue
+
+            # JS/TS: function foo(a, b) or const foo = (a, b) =>
+            js_m = re.match(r"^(?:async\s+)?function\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*?)\)", stripped)
+            if js_m:
+                fname = js_m.group(1)
+                params = [p.strip() for p in js_m.group(2).split(",") if p.strip()]
+                self.register_function(FunctionDef(file_path=file_path, func_name=fname, start_line=line_num, parameters=params))
+                continue
+
+            arrow_m = re.match(r"^(?:const|let|var)\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(?:async\s*)?\((.*?)\)\s*=>", stripped)
+            if arrow_m:
+                fname = arrow_m.group(1)
+                params = [p.strip() for p in arrow_m.group(2).split(",") if p.strip()]
+                self.register_function(FunctionDef(file_path=file_path, func_name=fname, start_line=line_num, parameters=params))
+                continue
+
+            # Go: func foo(a string)
+            go_m = re.match(r"^func\s+(?:\(.*?\)\s+)?([a-zA-Z_][a-zA-Z0-9_]*)\s*\((.*?)\)", stripped)
+            if go_m:
+                fname = go_m.group(1)
+                params = [p.strip() for p in go_m.group(2).split(",") if p.strip()]
+                self.register_function(FunctionDef(file_path=file_path, func_name=fname, start_line=line_num, parameters=params))
+
+    def _find_enclosing_function(self, file_path: str, line_num: int) -> str:
+        candidates = [f for (fp, fn), f in self.functions.items() if fp == file_path and f.start_line <= line_num]
+        if not candidates:
+            return "<global>"
+        candidates.sort(key=lambda f: f.start_line, reverse=True)
+        return candidates[0].func_name
+
+    def get_callers(self, file_path: str, func_name: str) -> List[CallSite]:
+        return self.callers.get((file_path, func_name), [])
+
+    def get_callees(self, file_path: str, func_name: str) -> List[CallSite]:
+        return self.callees.get((file_path, func_name), [])

package/.torusguard/core/clustering.py

@@ -0,0 +1,275 @@
+"""
+TorusGuard v6 Root-Cause Clustering Engine
+Groups individual static-analysis findings into cohesive root-cause clusters
+so engineering teams can remediate systemic architectural issues rather than chasing isolated alerts.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Any, Optional
+import hashlib
+
+
+# Canonical Cluster Taxonomy Definitions
+KNOWN_ROOT_CAUSES = {
+    "TG-DB-004": {
+        "cluster_id": "cluster-tenant-isolation",
+        "title": "Missing Multi-Tenant Query Scoping & Model Isolation",
+        "shared_remediation_path": "Implement tenant-aware BaseManager / default queryset filtering or tenancy middleware context.",
+        "shared_verification_plan": "Execute tenant cross-boundary query assertions and recheck query builders."
+    },
+    "TG-INPUT-006": {
+        "cluster_id": "cluster-path-traversal",
+        "title": "Unsafe File Upload Storage & Path Traversal Boundaries",
+        "shared_remediation_path": "Sanitize filenames using secure_filename() and enforce safe directory resolution with Path.resolve().",
+        "shared_verification_plan": "Run path traversal payload test suite and verify storage isolation."
+    },
+    "TG-INPUT-005": {
+        "cluster_id": "cluster-template-escaping",
+        "title": "Disabled Template Autoescaping & Unsafe HTML Rendering",
+        "shared_remediation_path": "Remove explicit mark_safe() / |safe filters and use autoescaped context variables.",
+        "shared_verification_plan": "Execute XSS payload injection test against rendered view outputs."
+    },
+    "TG-AUTH-008": {
+        "cluster_id": "cluster-header-trust",
+        "title": "Untrusted Client Header Trust & Role/Tenant Injection",
+        "shared_remediation_path": "Derive user identity and role scopes exclusively from cryptographically signed session tokens or trusted gateways.",
+        "shared_verification_plan": "Send spoofed client headers (X-User-Role, X-Tenant-ID) and assert rejection."
+    },
+    "TG-AUTH-007": {
+        "cluster_id": "cluster-idor-scoping",
+        "title": "Insecure Direct Object Reference (IDOR) on Primary Keys",
+        "shared_remediation_path": "Scope database queries with user_id or account ownership filters before returning model instances.",
+        "shared_verification_plan": "Run IDOR authorization matrix tests across test accounts."
+    },
+    "TG-RATE-001": {
+        "cluster_id": "cluster-rate-limiting",
+        "title": "Unbounded Resource Consumption & Missing Endpoint Throttling",
+        "shared_remediation_path": "Apply Redis/in-memory rate limiting middleware or DRF Throttling classes.",
+        "shared_verification_plan": "Execute burst traffic simulation and verify 429 Too Many Requests response."
+    },
+    "TG-SSRF-001": {
+        "cluster_id": "cluster-ssrf-network",
+        "title": "Unvalidated Outbound HTTP Requests & Network Boundary Leakage",
+        "shared_remediation_path": "Validate destination URLs against strict allowlists and block internal IP ranges (127.0.0.1, 169.254.169.254).",
+        "shared_verification_plan": "Attempt outbound requests to loopback and link-local metadata endpoints."
+    },
+    "TG-WEBHOOK-001": {
+        "cluster_id": "cluster-webhook-auth",
+        "title": "Unverified Inbound Webhook Signatures & Replay Vulnerability",
+        "shared_remediation_path": "Verify HMAC signatures using timing-safe comparisons and enforce timestamp freshness bounds.",
+        "shared_verification_plan": "Send unsigned and replay webhook payloads and confirm 401/403 rejection."
+    },
+    "TG-SEC-001": {
+        "cluster_id": "cluster-secrets",
+        "title": "Hardcoded Secrets & Sensitive Environment Configuration Exposure",
+        "shared_remediation_path": "Extract secrets into environment variables (.env / secrets manager) and exclude from version control.",
+        "shared_verification_plan": "Audit git history and scan source files for credential patterns."
+    },
+    "TG-AGENT-001": {
+        "cluster_id": "cluster-prompt-injection",
+        "title": "AI Agent User Prompt Concatenation & System Prompt Override",
+        "shared_remediation_path": "Isolate untrusted user input within explicit inert XML delimiters or structured user-role message arrays.",
+        "shared_verification_plan": "Execute prompt injection canary payloads and verify refusal to override system directives."
+    },
+    "TG-CSRF-001": {
+        "cluster_id": "cluster-csrf-missing",
+        "title": "Cross-Site Request Forgery (CSRF) & Missing SameSite Cookie Protection",
+        "shared_remediation_path": "Enforce SameSite=Lax/Strict on session cookies and validate cryptographic anti-CSRF tokens on state mutations.",
+        "shared_verification_plan": "Attempt cross-origin state-changing POST requests without CSRF token."
+    },
+    "TG-GQL-001": {
+        "cluster_id": "cluster-graphql-abuse",
+        "title": "Unbounded GraphQL Query Depth & Production Introspection Exposure",
+        "shared_remediation_path": "Configure GraphQL query depth limiting (max depth 6) and disable schema introspection in production.",
+        "shared_verification_plan": "Send deeply nested recursive query and introspection requests to production endpoint."
+    },
+    "TG-SUPPLY-001": {
+        "cluster_id": "cluster-supply-chain",
+        "title": "Supply Chain Vulnerability & Unpinned CI/CD Action Hashes",
+        "shared_remediation_path": "Pin GitHub Actions to full immutable commit SHAs and enforce lockfile integrity verification in CI.",
+        "shared_verification_plan": "Scan workflow files for mutable tag references and verify lockfile checksums."
+    },
+    "TG-BIZ-001": {
+        "cluster_id": "cluster-business-logic",
+        "title": "Business Logic Invariant Violation & Negative Quantity/Discount Bypass",
+        "shared_remediation_path": "Assert non-negative amount invariants, enforce transactional locks, and cap discounts server-side.",
+        "shared_verification_plan": "Submit negative amount and coupon boundary payloads in transactional API endpoints."
+    },
+    "TG-CACHE-001": {
+        "cluster_id": "cluster-cache-poisoning",
+        "title": "Web Cache Poisoning & Missing Cache-Control on Sensitive Responses",
+        "shared_remediation_path": "Sanitize unkeyed HTTP request headers and apply 'Cache-Control: no-store' on private or authenticated responses.",
+        "shared_verification_plan": "Send unkeyed headers (X-Forwarded-Host) and inspect cached responses."
+    },
+    "TG-WS-001": {
+        "cluster_id": "cluster-websocket-auth",
+        "title": "Missing WebSocket Handshake Authentication & Origin Verification",
+        "shared_remediation_path": "Authenticate client credentials during WebSocket upgrade and reject connections with unwhitelisted Origin headers.",
+        "shared_verification_plan": "Connect from untrusted origin and assert handshake rejection with 403 Forbidden."
+    },
+    "TG-EDGE-001": {
+        "cluster_id": "cluster-edge-abuse",
+        "title": "Serverless Subrequest Fan-Out Explosion & Missing Timeout Bounds",
+        "shared_remediation_path": "Enforce concurrency caps on edge subrequests and configure strict execution timeouts (<= 15s).",
+        "shared_verification_plan": "Simulate high subrequest fan-out and assert bounded concurrency."
+    },
+    "TG-CONT-001": {
+        "cluster_id": "cluster-container-hardening",
+        "title": "Container Security Misconfiguration & Root User Execution",
+        "shared_remediation_path": "Define non-root USER in Dockerfile, avoid mounting /var/run/docker.sock, and disallow privileged mode.",
+        "shared_verification_plan": "Inspect container image metadata and assert non-root UID."
+    },
+    "TG-GIT-001": {
+        "cluster_id": "cluster-git-secret-mining",
+        "title": "Committed Credentials & Leaked Tokens in Git Commit History",
+        "shared_remediation_path": "Rotate exposed keys immediately, purge secret commits using git-filter-repo, and install pre-commit secret hooks.",
+        "shared_verification_plan": "Mine git commit logs for high-entropy tokens and regex matches."
+    },
+    "TG-REDOS-001": {
+        "cluster_id": "cluster-regex-backtracking",
+        "title": "Regular Expression Denial of Service (ReDoS) via Nested Quantifiers",
+        "shared_remediation_path": "Refactor regex patterns to eliminate nested quantifiers (e.g. (a+)+) or enforce execution timeouts.",
+        "shared_verification_plan": "Execute polynomial/exponential adversarial string payloads against regex engine."
+    },
+    "TG-RAG-001": {
+        "cluster_id": "cluster-rag-tenant-leak",
+        "title": "RAG Pipeline Vector Database Multi-Tenant Isolation Leakage",
+        "shared_remediation_path": "Always include tenant_id or user_id in vector similarity filter metadata (e.g. filter={'tenant_id': tid}).",
+        "shared_verification_plan": "Query vector database with tenant A context requesting tenant B documents."
+    },
+    "TG-INPUT-007": {
+        "cluster_id": "cluster-open-redirect",
+        "title": "Unvalidated URL Redirection (Open Redirect)",
+        "shared_remediation_path": "Validate destination URLs against an allowlist of trusted domains and restrict to relative paths.",
+        "shared_verification_plan": "Test redirect endpoints with external and protocol-relative URLs."
+    },
+    "TG-INPUT-008": {
+        "cluster_id": "cluster-deserialization",
+        "title": "Insecure Object Deserialization via Untrusted Streams",
+        "shared_remediation_path": "Avoid pickle/yaml.load with untrusted input; use safe serialization formats (JSON) or SafeLoader.",
+        "shared_verification_plan": "Submit serialized gadget payload and confirm safe parser rejection."
+    }
+}
+
+
+
+@dataclass
+class RootCauseCluster:
+    cluster_id: str
+    title: str
+    primary_rule: str
+    affected_files: List[str] = field(default_factory=list)
+    affected_locations: List[str] = field(default_factory=list)
+    finding_ids: List[str] = field(default_factory=list)
+    shared_remediation_path: str = ""
+    shared_verification_plan: str = ""
+    risk_severity: str = "High"
+    hotspot_module: str = ""
+    is_high_density: bool = False
+
+    def add_finding(self, finding_id: str, file_path: str, location_str: str, severity: str = "High"):
+        if finding_id not in self.finding_ids:
+            self.finding_ids.append(finding_id)
+        if file_path not in self.affected_files:
+            self.affected_files.append(file_path)
+        if location_str not in self.affected_locations:
+            self.affected_locations.append(location_str)
+
+        # Update hotspot module (top directory)
+        parts = file_path.replace("\\", "/").split("/")
+        if len(parts) > 1:
+            self.hotspot_module = "/".join(parts[:2])
+        else:
+            self.hotspot_module = parts[0]
+
+        # Density threshold (> 5 findings in one cluster is high density)
+        if len(self.finding_ids) >= 5:
+            self.is_high_density = True
+
+        # Escalate cluster severity if higher
+        severity_order = {"Critical": 4, "High": 3, "Medium": 2, "Low": 1, "Informational": 0}
+        if severity_order.get(severity, 0) > severity_order.get(self.risk_severity, 0):
+            self.risk_severity = severity
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+# Generated / Vendor File Exclusion Patterns
+IGNORED_PATTERNS = [
+    "migrations/", "node_modules/", "dist/", "build/", "vendor/",
+    ".venv/", "venv/", ".min.js", ".min.css", ".pb.go", "_pb2.py",
+    "bundle.js", ".map"
+]
+
+
+def is_generated_file(file_path: str) -> bool:
+    norm = file_path.replace("\\", "/").lower()
+    return any(p in norm for p in IGNORED_PATTERNS)
+
+
+class ClusteringEngine:
+    """
+    Analyzes findings and groups them into root-cause clusters with scale and density metrics.
+    """
+
+    @staticmethod
+    def cluster_findings(
+        findings: List[Dict[str, Any]],
+        filter_generated: bool = False
+    ) -> List[RootCauseCluster]:
+        clusters: Dict[str, RootCauseCluster] = {}
+
+        for f in findings:
+            target = f.get("target", {})
+            file_path = target.get("file_path", "unknown")
+
+            if filter_generated and is_generated_file(file_path):
+                continue
+
+            rule_id = f.get("rule_id", "TG-GENERIC")
+            finding_id = f.get("finding_id", "unknown")
+            start_line = target.get("line_start", 0)
+            end_line = target.get("line_end", 0)
+            loc_str = f"{file_path}:{start_line}-{end_line}"
+            severity = f.get("severity", "High")
+
+            # Determine cluster mapping
+            if rule_id in KNOWN_ROOT_CAUSES:
+                meta = KNOWN_ROOT_CAUSES[rule_id]
+                cid = meta["cluster_id"]
+                title = meta["title"]
+                rem_path = meta["shared_remediation_path"]
+                ver_plan = meta["shared_verification_plan"]
+            else:
+                cid = f"cluster-{rule_id.lower().replace('tg-', '')}"
+                title = f"Systemic {f.get('title', rule_id)} Issues"
+                rem_path = "Apply framework-native security controls as documented in rule reference."
+                ver_plan = "Re-audit all affected components with /torusguard recheck."
+
+            if cid not in clusters:
+                clusters[cid] = RootCauseCluster(
+                    cluster_id=cid,
+                    title=title,
+                    primary_rule=rule_id,
+                    shared_remediation_path=rem_path,
+                    shared_verification_plan=ver_plan,
+                    risk_severity=severity,
+                )
+
+            clusters[cid].add_finding(
+                finding_id=finding_id,
+                file_path=file_path,
+                location_str=loc_str,
+                severity=severity,
+            )
+
+        # Sort clusters by severity and finding count
+        severity_order = {"Critical": 4, "High": 3, "Medium": 2, "Low": 1, "Informational": 0}
+        sorted_clusters = sorted(
+            clusters.values(),
+            key=lambda c: (severity_order.get(c.risk_severity, 0), len(c.finding_ids)),
+            reverse=True
+        )
+
+        return sorted_clusters